NAME
List::MapMulti - map through multiple arrays at once
SYNOPSIS
use feature qw/say/;
use List::MapMulti qw/mapm/;
my @numbers = (2..10, qw/Jack Queen King Ace/);
my @suits = qw/Clubs Diamonds Hearts Spades/;
my @cards = mapm { "$_[0] of $_[1]" } \@numbers, \@suits;
say scalar(@cards); # says '52'
say $cards[0]; # says '2 of Clubs'
say $cards[1]; # says '2 of Diamonds'
say $cards[-1]; # says 'Ace of Spades'DESCRIPTION
List::MapMulti provides shortcuts for looping through several lists in a nested fashion. Think about all the times you've needed to do something like:
foreach my $x (@exes) {
foreach my $y (@whys) {
# do something with $x and $y
}
}There are two different solutions available to you: map_multi (which has an alias mapm) and iterator_multi.
The only thing this module exports by default is mapm.
map_multi { BLOCK } \@list1, \@list2 ...
(Or mapm!)
Calls the codeblock with every possible combination of values from each list. If you imagine it as calling within a set of nested loops, then the final list is the innermost loop; and the first loop is the outermost loop.
Note that within the codeblock, the items from each list are available as $_[0], $_[1], etc. The $_ variable is set to a List::MapMulti::Iterator object which is used internally by map_multi.
For the special (but common) case where you're just mapping over two lists, $a and $b are aliased to $_[0] and $_[1]. You may need to do our ($a, $b) to suppress warnings about variables being used only once.
mapm is exported by default, but map_multi needs to be requested explicitly.
iterator_multi(\@list1, \@list2, ...)
This allows constructions like this:
my $iterator = iterator_multi(\@numbers, \@suits);
while (my ($number, $suit) = $iterator->())
{
say "$number of $suit";
}Although map_multi is arguably a nicer syntax, the iterator provides you with an important advantage: you don't have to iterate through every possible combination. You can control flow using, say, next, last or redo.
List::MapMulti::Iterator
This is advanced fu that you probably don't need to know about.
While iterators act like coderefs (you get the next set of values via $iterator->()), internally they are blessed objects that overload &{}. As they are objects, they are able to provide some methods.
These are the methods they provide:
new(\@list1, \@list2, ...)
Constructor. The iterator_multi function is just a shortcut for this.
next
Calling $iterator->next is exactly equivalent to calling $iterator->().
current
Returns the same thing as the previous call to next (unless the original arrays have changed since then).
This can also be used as a setter, in which case it writes back to the appropriate slots in the original arrays.
next_indices
Returns the array indices that will be used to read from the original arrays next time next is called. Again, this can be used as a setter.
current_indices
Returns the array indices that was used to read from the original arrays last time next was called.
BUGS
Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=List-MapMulti.
SEE ALSO
List::Util, List::MoreUtils, List::Pairwise.
AUTHOR
Toby Inkster <tobyink@cpan.org>.
COPYRIGHT AND LICENCE
This software is copyright (c) 2012 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
DISCLAIMER OF WARRANTIES
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.