Arrayandhashiterators
"pairs %hash"
"pairs @array"
"pairs $hash_or_array_ref"
In list context, "pairs()" returns a list of "pair" objects, each of which contains one key/index and
value from the argument. In scalar and void contexts, "pairs()" throws an exception.
The typical list usage is:
for my $pair (pairs %container) {
# ...do something with $pair
}
The intent is to provide a safe and reliable replacement for the built-in "each()" function;
specifically, a replacement that can be used in "for" loops.
"kvs %hash"
"kvs @array"
"kvs $hash_or_array_ref"
In list context, "kvs()" returns a list of alternating keys and values. That is "kvs %hash" flattens
the hash to "(key, value, key, value...)" and "kvs @array" flattens the array to "(index, value,
index, value...)".
In scalar and void contexts, "kvs()" throws an exception.
The most typical use is to populate a hash from an array:
my %hash = kvs @array;
# does the same as:
my %hash; @hash{0..$#array} = @array;
"each_pair %hash"
"each_pair @array"
"each_pair $hash_or_array_ref"
"each_pair $subroutine_ref"
In all contexts, "each_pair()" returns a single "pair" object, containing the key/index and value of
the next element in the argument.
A separate internal iterator is created for each call to "each_pair()", so multiple calls to
"each_pair()" on the same container variable can be nested without interacting with each other (i.e.
unlike multiple calls to "each()").
When the iterator is exhausted, the next call to "each_pair()" returns "undef" or an empty list
(depending on context), and resets the iterator. The iterator is also reset when execution leaves
the block in which "each_pair()" is called. This means, for example, that "last"-ing out of the
middle of an iterated loop does the right thing (by resetting the iterator).
The typical usage is:
while (my $pair = each_pair %container) {
# ...do something with $pair->key and $pair->value
}
Note, however, that using "pairs()" in a "for" loop is the preferred idiom:
for my $pair (pairs %container) {
# ...do something with $pair->key and $pair->value
}
The "each_pair()" subroutine can also be passed a reference to a subroutine, in which case that
subroutine is used directly as the iterator.
When iterated, this iterator subroutine is called in list context and is expected to return a single
value on each call (i.e. the next value to be iterated), or else an empty list when the iterator is
exhausted.
For example:
# Calling this sub returns a reference to an anonymous iterator sub...
sub count_down {
my ($from, $to) = @_;
return sub {
return () if $from < $to; # End of iterator
return $from--; # Next iterated value
}
}
# Build a 10-->1 countdown and iterate it...
while (my $next = each_pair count_down(10, 1)) {
say $next->value;
}
"each_kv %hash"
"each_kv @array"
"each_kv $hash_or_array_ref"
"each_kv $subroutine_ref"
This subroutine is very similar to "each_pair()", except that in list contexts, <each_kv()> returns a
list of two elements: the key/index and the value of the next element in the argument. In scalar
contexts, just the next key is returned.
As with "each_pair()", a separate internal iterator is created for each call to "each_kv()", so
multiple calls to "each_kv()" on the same container variable can be nested without interacting with
each other (i.e. unlike multiple calls to "each()").
When the iterator is exhausted, the next call to "each_kv()" returns "undef" in scalar context or an
empty list in list context, and resets the iterator. The iterator is also reset when execution leaves
the block in which "each_kv()" is called.
The typical list usage is:
while (my ($key1, $val1) = each_kv %container) {
while (my ($key2, $val2) = each_kv %container) {
# ...do something with the two keys and two values
}
}
The typical scalar usage is:
while (my $key1 = each_kv %container) {
while (my $key2 = each_kv %container) {
# ...do something with the two keys
}
}
In other words, "each_kv()" is a drop-in replacement for Perl's built-in "each()", with two
exceptions: one an advantage, the other a limitation. The advantage is that you can nest "each_kv()"
iterations over the same variable without shooting yourself in the foot. The limitation is that,
unlike "each()", "each_kv()" does not reset when you call the "keys" function on the hash you're
iterating.
"each_value %hash"
"each_value @array"
"each_value $hash_or_array_ref"
"each_value $subroutine_ref"
The "each_value()" subroutine works exactly like "each_kv()", except that in all contexts it just
returns the value being iterated, not the key or key/value combination.
For example:
# Build a 10-->1 countdown and iterate it...
while (my ($next) = each_value count_down(10, -10)) {
say $next;
}
while (my $value1 = each_value %container) {
while (my $value2 = each_value %container) {
# ...do something with the two values
}
}
Note that, if your iterator can return a false value, such as 0 from the "count_down()" iterator in
the previous example, then you should call "each_value()" in list context (as in the "count_down()"
example) so that the false value does not prematurely terminate the "while" loop.
"%hash->pairs"
"@array->pairs"
"$hash_or_array_ref->pairs"
"%hash->kvs"
"@array->kvs"
"$hash_or_array_ref->kvs"
"%hash->each_pair"
"@array->each_pair"
"$hash_or_array_ref->each_pair"
"%hash->each_kv"
"@array->each_kv"
"$hash_or_array_ref->each_kv"
"%hash->each_value"
"@array->each_value"
"$hash_or_array_ref->each_value"
If you have the "autobox" module installed, you can use this OO syntax as well. Apart from their call
syntax, these OO forms are exactly the same as the subroutine-based interface described above.
Pairs
"$pair->key"
Returns a copy of the key of the pair, if the pair was derived from a hash. Returns a copy of the
index of the pair, if the pair was derived from an array.
"$pair->index"
Nothing but a synonym for "$pair->key". Use whichever suits your purpose, your program, or your
predilections.
"$pair->value"
Returns the value of the pair, as an lvalue. That is:
for my $item (pairs %items) {
say $item->value
if $item->key =~ /\d/;
}
will print the value of every entry in the %items hash whose key includes a digit.
And:
for my $item (pairs %items) {
$item->value++;
if $item->key =~ /^Q/;
}
will increment each value in the %items hash whose key starts with 'Q'.
"$pair->kv"
Returns a two-element list containing copies of the key and the value of the pair. That is:
for my $item (pairs %items) {
my ($k, $v) = $item->kv;
say $v
if $k =~ /\d/;
}
will print the value of every entry in the %items hash whose key includes a digit.
"$pair"
When used as a string, a pair is converted to a suitable representation for a pair, namely: "key =>
value"
"0 + $pair"
Pairs cannot be used as numbers: an exception is thrown.
"if ($pair) {...}"
When a pair is used as a boolean, it is always true.
Namedpairconstructors
"to_pair $scalar, @array, %hash, $etc"
The "to_pair" subroutine takes one or more variables and converts each of them to a single Pair
object. The Pair's key is the name of the variable (minus its leading sigil), and the value is the
value of the variable (if it's a scalar) or a reference to the variable (if it's an array or hash).
That is:
to_pair $scalar, @array, %hash, $etc
is equivalent to:
Pair->new( scalar => $scalar ),
Pair->new( array => \@array ),
Pair->new( hash => \%hash ),
Pair->new( etc => $etc )
This is especially useful for generating modern sets of named arguments for other subroutines. For
example:
Sub::Install::install_sub(to_pair $code, $from, $into);
instead of:
Sub::Install::install_sub(
Pair->new(code => $code),
Pair->new(from => $from),
Pair->new(into => $into)
);
"to_kv $scalar, @array, %hash, $etc"
The "to_kv()" subroutine takes one or more variables and converts each of them to a key "=>" value
sequence (i.e. a two-element list, rather than a Pair object).
As with "to_pair()", the key is the name of the variable (minus its leading sigil), and the value is
the value of the variable (if it's a scalar) or a reference to the variable (if it's an array or
hash).
That is:
to_kv $scalar, @array, %hash, $etc
is equivalent to:
scalar => $scalar, array => \@array, hash => \%hash, etc => $etc
This is especially useful for generating traditional sets of named arguments for other subroutines.
For example:
Sub::Install::install_sub({to_kv $code, $from, $into});
instead of:
Sub::Install::install_sub({code => $code, from => $from, into => $into});
Arrayandhashinverters
"invert %hash"
"invert @array"
"invert $hash_or_array_ref"
The "invert" subroutine takes a single hash or array (or a reference to either) and returns a list of
alternating keys and value, where each key is a value from the original variable and each
corresponding value is a reference to an array containing the original key(s). This list is typically
used to initialize a second hash, which can then be used as a reverse mapping. In other words:
my %hash = ( a => 1, b => 2, c => 1, d => 1, e => 2, f => 3 );
my %inversion = invert %hash;
is equivalent to:
my %inversion = (
1 => ['a', 'c', 'd'],
2 => ['b', 'e'],
3 => ['f'],
);
"invert" correctly handles the many-to-many case where some of the values in the original are array
references. For example:
my %hash = ( a => [1,2], b => 2, c => [1,3], d => 1, e => [3,2], f => 3 );
my %inversion = invert %hash;
is equivalent to:
my %inversion = (
1 => ['a', 'c', 'd'],
2 => ['a', 'b', 'e'],
3 => ['c', 'e', 'f'],
);
"invert_pairs %hash"
"invert_pairs @array"
"invert_pairs $hash_or_array_ref"
"invert_pairs()" acts exactly like "invert()", except that it returns a list of Pair objects (like
"pairs()" does).
This is not useful for initializing other hashes, but is handy for debugging a reverse mapping:
say for invert_pairs %hash;
"%hash->invert" or "%hash->invert_pairs"
"@array->invert" or "@array->invert_pairs"
"$hash_or_array_ref->invert" or "$hash_or_array_ref->invert_pairs"
If you have the "autobox" module installed, you can use this OO syntax as well. Apart from their call
syntax, these OO forms are exactly the same as the subroutine-based interfaces described above.
Install Now
PNG Icons
