3 # Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved.
4 # This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
12 our @ISA = qw(Exporter DynaLoader);
13 our @EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle);
14 our $VERSION = "1.05_00";
16 bootstrap List::Util $VERSION;
24 List::Util - A selection of general-utility list subroutines
28 use List::Util qw(first max maxstr min minstr reduce shuffle sum);
32 C<List::Util> contains a selection of subroutines that people have
33 expressed would be nice to have in the perl core, but the usage would
34 not really be high enough to warrant the use of a keyword, and the size
35 so small such that being individual extensions would be wasteful.
37 By default C<List::Util> does not export any subroutines. The
38 subroutines defined are
42 =item first BLOCK LIST
44 Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
45 of LIST in turn. C<first> returns the first element where the result from
46 BLOCK is a true value. If BLOCK never returns true or LIST was empty then
49 $foo = first { defined($_) } @list # first defined value in @list
50 $foo = first { $_ > $value } @list # first value in @list which
51 # is greater than $value
53 This function could be implemented using C<reduce> like this
55 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
57 for example wanted() could be defined() which would return the first
58 defined value in @list
62 Returns the entry in the list with the highest numerical value. If the
63 list is empty then C<undef> is returned.
66 $foo = max 3,9,12 # 12
67 $foo = max @bar, @baz # whatever
69 This function could be implemented using C<reduce> like this
71 $foo = reduce { $a > $b ? $a : $b } 1..10
75 Similar to C<max>, but treats all the entries in the list as strings
76 and returns the highest string as defined by the C<gt> operator.
77 If the list is empty then C<undef> is returned.
79 $foo = maxstr 'A'..'Z' # 'Z'
80 $foo = maxstr "hello","world" # "world"
81 $foo = maxstr @bar, @baz # whatever
83 This function could be implemented using C<reduce> like this
85 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
89 Similar to C<max> but returns the entry in the list with the lowest
90 numerical value. If the list is empty then C<undef> is returned.
94 $foo = min @bar, @baz # whatever
96 This function could be implemented using C<reduce> like this
98 $foo = reduce { $a < $b ? $a : $b } 1..10
102 Similar to C<min>, but treats all the entries in the list as strings
103 and returns the lowest string as defined by the C<lt> operator.
104 If the list is empty then C<undef> is returned.
106 $foo = minstr 'A'..'Z' # 'A'
107 $foo = minstr "hello","world" # "hello"
108 $foo = minstr @bar, @baz # whatever
110 This function could be implemented using C<reduce> like this
112 $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
114 =item reduce BLOCK LIST
116 Reduces LIST by calling BLOCK multiple times, setting C<$a> and C<$b>
117 each time. The first call will be with C<$a> and C<$b> set to the first
118 two elements of the list, subsequent calls will be done by
119 setting C<$a> to the result of the previous call and C<$b> to the next
122 Returns the result of the last call to BLOCK. If LIST is empty then
123 C<undef> is returned. If LIST only contains one element then that
124 element is returned and BLOCK is not executed.
126 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
127 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
128 $foo = reduce { $a + $b } 1 .. 10 # sum
129 $foo = reduce { $a . $b } @bar # concat
133 Returns the elements of LIST in a random order
135 @cards = shuffle 0..51 # 0..51 in a random order
139 Returns the sum of all the elements in LIST.
141 $foo = sum 1..10 # 55
142 $foo = sum 3,9,12 # 24
143 $foo = sum @bar, @baz # whatever
145 This function could be implemented using C<reduce> like this
147 $foo = reduce { $a + $b } 1..10
151 =head1 SUGGESTED ADDITIONS
153 The following are additions that have been requested, but I have been reluctant
154 to add due to them being very simple to implement in perl
156 # One argument is true
158 sub any { $_ && return 1 for @_; 0 }
160 # All arguments are true
162 sub all { $_ || return 0 for @_; 1 }
164 # All arguments are false
166 sub none { $_ && return 0 for @_; 1 }
168 # One argument is false
170 sub notall { $_ || return 1 for @_; 0 }
172 # How many elements are true
174 sub true { scalar grep { $_ } @_ }
176 # How many elements are false
178 sub false { scalar grep { !$_ } @_ }
182 Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved.
183 This program is free software; you can redistribute it and/or
184 modify it under the same terms as Perl itself.