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.