unsupported 0li~d h p)F _ub &=LV[(?# Copyright (c) 1997-2009 Graham Barr . All rights reserved. # This program is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. # # Maintained since 2013 by Paul Evans package List::Util; use strict; use warnings; require Exporter; our @ISA = qw(Exporter); our @EXPORT_OK = qw( all any first min max minstr maxstr none notall product reduce reductions sum sum0 sample shuffle uniq uniqint uniqnum uniqstr zip zip_longest zip_shortest mesh mesh_longest mesh_shortest head tail pairs unpairs pairkeys pairvalues pairmap pairgrep pairfirst ); our $VERSION = "1.56"; our $XS_VERSION = $VERSION; $VERSION =~ tr/_//d; require XSLoader; XSLoader::load('List::Util', $XS_VERSION); # Used by shuffle() our $RAND; sub import { my $pkg = caller; # (RT88848) Touch the caller's $a and $b, to avoid the warning of # Name "main::a" used only once: possible typo" warning no strict 'refs'; ${"${pkg}::a"} = ${"${pkg}::a"}; ${"${pkg}::b"} = ${"${pkg}::b"}; goto &Exporter::import; } # For objects returned by pairs() sub List::Util::_Pair::key { shift->[0] } sub List::Util::_Pair::value { shift->[1] } sub List::Util::_Pair::TO_JSON { [ @{+shift} ] } =head1 NAME List::Util - A selection of general-utility list subroutines =head1 SYNOPSIS use List::Util qw( reduce any all none notall first reductions max maxstr min minstr product sum sum0 pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap shuffle uniq uniqint uniqnum uniqstr zip mesh ); =head1 DESCRIPTION C contains a selection of subroutines that people have expressed would be nice to have in the perl core, but the usage would not really be high enough to warrant the use of a keyword, and the size so small such that being individual extensions would be wasteful. By default C does not export any subroutines. =cut =head1 LIST-REDUCTION FUNCTIONS The following set of functions all apply a given block of code to a list of values. =cut =head2 reduce $result = reduce { BLOCK } @list Reduces C<@list> by calling C in a scalar context multiple times, setting C<$a> and C<$b> each time. The first call will be with C<$a> and C<$b> set to the first two elements of the list, subsequent calls will be done by setting C<$a> to the result of the previous call and C<$b> to the next element in the list. Returns the result of the last call to the C. If C<@list> is empty then C is returned. If C<@list> only contains one element then that element is returned and C is not executed. The following examples all demonstrate how C could be used to implement the other list-reduction functions in this module. (They are not in fact implemented like this, but instead in a more efficient manner in individual C functions). $foo = reduce { defined($a) ? $a : $code->(local $_ = $b) ? $b : undef } undef, @list # first $foo = reduce { $a > $b ? $a : $b } 1..10 # max $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' # maxstr $foo = reduce { $a < $b ? $a : $b } 1..10 # min $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr $foo = reduce { $a + $b } 1 .. 10 # sum $foo = reduce { $a . $b } @bar # concat $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar # any $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar # all $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar # none $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar # notall # Note that these implementations do not fully short-circuit If your algorithm requires that C produce an identity value, then make sure that you always pass that identity value as the first argument to prevent C being returned $foo = reduce { $a + $b } 0, @values;