1# Copyright (c) 1997-2009 Graham Barr <gbarr@pobox.com>. All rights reserved. 2# This program is free software; you can redistribute it and/or 3# modify it under the same terms as Perl itself. 4# 5# Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk> 6 7package List::Util; 8 9use strict; 10require Exporter; 11 12our @ISA = qw(Exporter); 13our @EXPORT_OK = qw( 14 all any first min max minstr maxstr none notall product reduce sum sum0 shuffle 15 pairmap pairgrep pairfirst pairs pairkeys pairvalues 16); 17our $VERSION = "1.38"; 18our $XS_VERSION = $VERSION; 19$VERSION = eval $VERSION; 20 21require XSLoader; 22XSLoader::load('List::Util', $XS_VERSION); 23 24sub import 25{ 26 my $pkg = caller; 27 28 # (RT88848) Touch the caller's $a and $b, to avoid the warning of 29 # Name "main::a" used only once: possible typo" warning 30 no strict 'refs'; 31 ${"${pkg}::a"} = ${"${pkg}::a"}; 32 ${"${pkg}::b"} = ${"${pkg}::b"}; 33 34 goto &Exporter::import; 35} 36 371; 38 39__END__ 40 41=head1 NAME 42 43List::Util - A selection of general-utility list subroutines 44 45=head1 SYNOPSIS 46 47 use List::Util qw(first max maxstr min minstr reduce shuffle sum); 48 49=head1 DESCRIPTION 50 51C<List::Util> contains a selection of subroutines that people have expressed 52would be nice to have in the perl core, but the usage would not really be high 53enough to warrant the use of a keyword, and the size so small such that being 54individual extensions would be wasteful. 55 56By default C<List::Util> does not export any subroutines. 57 58=cut 59 60=head1 LIST-REDUCTION FUNCTIONS 61 62The following set of functions all reduce a list down to a single value. 63 64=cut 65 66=head2 $result = reduce { BLOCK } @list 67 68Reduces C<@list> by calling C<BLOCK> in a scalar context multiple times, 69setting C<$a> and C<$b> each time. The first call will be with C<$a> and C<$b> 70set to the first two elements of the list, subsequent calls will be done by 71setting C<$a> to the result of the previous call and C<$b> to the next element 72in the list. 73 74Returns the result of the last call to the C<BLOCK>. If C<@list> is empty then 75C<undef> is returned. If C<@list> only contains one element then that element 76is returned and C<BLOCK> is not executed. 77 78The following examples all demonstrate how C<reduce> could be used to implement 79the other list-reduction functions in this module. (They are not in fact 80implemented like this, but instead in a more efficient manner in individual C 81functions). 82 83 $foo = reduce { defined($a) ? $a : 84 $code->(local $_ = $b) ? $b : 85 undef } undef, @list # first 86 87 $foo = reduce { $a > $b ? $a : $b } 1..10 # max 88 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' # maxstr 89 $foo = reduce { $a < $b ? $a : $b } 1..10 # min 90 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr 91 $foo = reduce { $a + $b } 1 .. 10 # sum 92 $foo = reduce { $a . $b } @bar # concat 93 94 $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar # any 95 $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar # all 96 $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar # none 97 $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar # notall 98 # Note that these implementations do not fully short-circuit 99 100If your algorithm requires that C<reduce> produce an identity value, then make 101sure that you always pass that identity value as the first argument to prevent 102C<undef> being returned 103 104 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value 105 106The remaining list-reduction functions are all specialisations of this generic 107idea. 108 109=head2 $b = any { BLOCK } @list 110 111Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element 112of C<@list> in turn. C<any> returns true if any element makes the C<BLOCK> 113return a true value. If C<BLOCK> never returns true or C<@list> was empty then 114it returns false. 115 116Many cases of using C<grep> in a conditional can be written using C<any> 117instead, as it can short-circuit after the first true result. 118 119 if( any { length > 10 } @strings ) { 120 # at least one string has more than 10 characters 121 } 122 123=head2 $b = all { BLOCK } @list 124 125Similar to C<any>, except that it requires all elements of the C<@list> to make 126the C<BLOCK> return true. If any element returns false, then it returns false. 127If the C<BLOCK> never returns false or the C<@list> was empty then it returns 128true. 129 130=head2 $b = none { BLOCK } @list 131 132=head2 $b = notall { BLOCK } @list 133 134Similar to C<any> and C<all>, but with the return sense inverted. C<none> 135returns true only if no value in the LIST causes the BLOCK to return true, and 136C<notall> returns true only if not all of the values do. 137 138=head2 $val = first { BLOCK } @list 139 140Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element 141of C<@list> in turn. C<first> returns the first element where the result from 142C<BLOCK> is a true value. If C<BLOCK> never returns true or C<@list> was empty 143then C<undef> is returned. 144 145 $foo = first { defined($_) } @list # first defined value in @list 146 $foo = first { $_ > $value } @list # first value in @list which 147 # is greater than $value 148 149=head2 $num = max @list 150 151Returns the entry in the list with the highest numerical value. If the list is 152empty then C<undef> is returned. 153 154 $foo = max 1..10 # 10 155 $foo = max 3,9,12 # 12 156 $foo = max @bar, @baz # whatever 157 158=head2 $str = maxstr @list 159 160Similar to C<max>, but treats all the entries in the list as strings and 161returns the highest string as defined by the C<gt> operator. If the list is 162empty then C<undef> is returned. 163 164 $foo = maxstr 'A'..'Z' # 'Z' 165 $foo = maxstr "hello","world" # "world" 166 $foo = maxstr @bar, @baz # whatever 167 168=head2 $num = min @list 169 170Similar to C<max> but returns the entry in the list with the lowest numerical 171value. If the list is empty then C<undef> is returned. 172 173 $foo = min 1..10 # 1 174 $foo = min 3,9,12 # 3 175 $foo = min @bar, @baz # whatever 176 177=head2 $str = minstr @list 178 179Similar to C<min>, but treats all the entries in the list as strings and 180returns the lowest string as defined by the C<lt> operator. If the list is 181empty then C<undef> is returned. 182 183 $foo = minstr 'A'..'Z' # 'A' 184 $foo = minstr "hello","world" # "hello" 185 $foo = minstr @bar, @baz # whatever 186 187=head2 $num = product @list 188 189Returns the numerical product of all the elements in C<@list>. If C<@list> is 190empty then C<1> is returned. 191 192 $foo = product 1..10 # 3628800 193 $foo = product 3,9,12 # 324 194 195=head2 $num_or_undef = sum @list 196 197Returns the numerical sum of all the elements in C<@list>. For backwards 198compatibility, if C<@list> is empty then C<undef> is returned. 199 200 $foo = sum 1..10 # 55 201 $foo = sum 3,9,12 # 24 202 $foo = sum @bar, @baz # whatever 203 204=head2 $num = sum0 @list 205 206Similar to C<sum>, except this returns 0 when given an empty list, rather than 207C<undef>. 208 209=cut 210 211=head1 KEY/VALUE PAIR LIST FUNCTIONS 212 213The following set of functions, all inspired by L<List::Pairwise>, consume an 214even-sized list of pairs. The pairs may be key/value associations from a hash, 215or just a list of values. The functions will all preserve the original ordering 216of the pairs, and will not be confused by multiple pairs having the same "key" 217value - nor even do they require that the first of each pair be a plain string. 218 219=cut 220 221=head2 @kvlist = pairgrep { BLOCK } @kvlist 222 223=head2 $count = pairgrep { BLOCK } @kvlist 224 225Similar to perl's C<grep> keyword, but interprets the given list as an 226even-sized list of pairs. It invokes the C<BLOCK> multiple times, in scalar 227context, with C<$a> and C<$b> set to successive pairs of values from the 228C<@kvlist>. 229 230Returns an even-sized list of those pairs for which the C<BLOCK> returned true 231in list context, or the count of the B<number of pairs> in scalar context. 232(Note, therefore, in scalar context that it returns a number half the size of 233the count of items it would have returned in list context). 234 235 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist 236 237As with C<grep> aliasing C<$_> to list elements, C<pairgrep> aliases C<$a> and 238C<$b> to elements of the given list. Any modifications of it by the code block 239will be visible to the caller. 240 241=head2 ( $key, $val ) = pairfirst { BLOCK } @kvlist 242 243=head2 $found = pairfirst { BLOCK } @kvlist 244 245Similar to the C<first> function, but interprets the given list as an 246even-sized list of pairs. It invokes the C<BLOCK> multiple times, in scalar 247context, with C<$a> and C<$b> set to successive pairs of values from the 248C<@kvlist>. 249 250Returns the first pair of values from the list for which the C<BLOCK> returned 251true in list context, or an empty list of no such pair was found. In scalar 252context it returns a simple boolean value, rather than either the key or the 253value found. 254 255 ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist 256 257As with C<grep> aliasing C<$_> to list elements, C<pairfirst> aliases C<$a> and 258C<$b> to elements of the given list. Any modifications of it by the code block 259will be visible to the caller. 260 261=head2 @list = pairmap { BLOCK } @kvlist 262 263=head2 $count = pairmap { BLOCK } @kvlist 264 265Similar to perl's C<map> keyword, but interprets the given list as an 266even-sized list of pairs. It invokes the C<BLOCK> multiple times, in list 267context, with C<$a> and C<$b> set to successive pairs of values from the 268C<@kvlist>. 269 270Returns the concatenation of all the values returned by the C<BLOCK> in list 271context, or the count of the number of items that would have been returned in 272scalar context. 273 274 @result = pairmap { "The key $a has value $b" } @kvlist 275 276As with C<map> aliasing C<$_> to list elements, C<pairmap> aliases C<$a> and 277C<$b> to elements of the given list. Any modifications of it by the code block 278will be visible to the caller. 279 280=head2 @pairs = pairs @kvlist 281 282A convenient shortcut to operating on even-sized lists of pairs, this function 283returns a list of ARRAY references, each containing two items from the given 284list. It is a more efficient version of 285 286 @pairs = pairmap { [ $a, $b ] } @kvlist 287 288It is most convenient to use in a C<foreach> loop, for example: 289 290 foreach ( pairs @KVLIST ) { 291 my ( $key, $value ) = @$_; 292 ... 293 } 294 295=head2 @keys = pairkeys @kvlist 296 297A convenient shortcut to operating on even-sized lists of pairs, this function 298returns a list of the the first values of each of the pairs in the given list. 299It is a more efficient version of 300 301 @keys = pairmap { $a } @kvlist 302 303=head2 @values = pairvalues @kvlist 304 305A convenient shortcut to operating on even-sized lists of pairs, this function 306returns a list of the the second values of each of the pairs in the given list. 307It is a more efficient version of 308 309 @values = pairmap { $b } @kvlist 310 311=cut 312 313=head1 OTHER FUNCTIONS 314 315=cut 316 317=head2 @values = shuffle @values 318 319Returns the values of the input in a random order 320 321 @cards = shuffle 0..51 # 0..51 in a random order 322 323=cut 324 325=head1 KNOWN BUGS 326 327With perl versions prior to 5.005 there are some cases where reduce will return 328an incorrect result. This will show up as test 7 of reduce.t failing. 329 330=head1 SUGGESTED ADDITIONS 331 332The following are additions that have been requested, but I have been reluctant 333to add due to them being very simple to implement in perl 334 335 # How many elements are true 336 337 sub true { scalar grep { $_ } @_ } 338 339 # How many elements are false 340 341 sub false { scalar grep { !$_ } @_ } 342 343=head1 SEE ALSO 344 345L<Scalar::Util>, L<List::MoreUtils> 346 347=head1 COPYRIGHT 348 349Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved. 350This program is free software; you can redistribute it and/or 351modify it under the same terms as Perl itself. 352 353Recent additions and current maintenance by 354Paul Evans, <leonerd@leonerd.org.uk>. 355 356=cut 357