=item my @result = map2 BLOCK ARRAY, ARRAY

Similar to c<map>, but operate on two lists at once.  The values are
passed in as two arguments.  This has a particularly snazzy side
effect; instead of projecting a list onto a series of hash keys the
long way:

  my %hash;
  @hash{@hash_keys} = @values;

You can just:

  my %hash = map2 { @_ } @hash_keys, @values;

On the down side, I've burned myself more than once by using $a and $b
with this function; perl has a special case to not warn about those.
Grumble.

=cut

# create and test a "map2" function that behaves similar to the
# built-in "map" function, but takes two lists instead of just one as
# input.
#
# abigail wrote one that is much snazzier, but i can't find her web
# page right now.
#
# similar to how "sort" takes its arguments, the block here should use
# $a and $b for the two elements.  the block is called in list
# context, just as in the "real" map.
#
# originally written by afoiani a long time ago.

sub map2 (&\@\@)
{
    my ($code_ref, $a_ref, $b_ref) = @_;
    my $max_index = (@$a_ref < @$b_ref) ? @$a_ref : @$b_ref;
    my @rv;
    for (my $i = 0; $i < $max_index; ++$i)
    {
        push @rv, $code_ref->($a_ref->[$i], $b_ref->[$i]);
    }
    return @rv;
}