1List::Util(3) User Contributed Perl Documentation List::Util(3)
2
6 List::Util - A selection of general-utility list subroutines
7
9 use List::Util qw(first max maxstr min minstr reduce shuffle sum);
10
12 "List::Util" contains a selection of subroutines that people have
13 expressed would be nice to have in the perl core, but the usage would
14 not really be high enough to warrant the use of a keyword, and the size
15 so small such that being individual extensions would be wasteful.
16 By default "List::Util" does not export any subroutines. The
18 subroutines defined are
19 first BLOCK LIST
21 Similar to "grep" in that it evaluates BLOCK setting $_ to each
22 element of LIST in turn. "first" returns the first element where
23 the result from BLOCK is a true value. If BLOCK never returns true
24 or LIST was empty then "undef" is returned.
25 $foo = first { defined($_) } @list # first defined value in @list
27 $foo = first { $_ > $value } @list # first value in @list which
28 # is greater than $value
29 This function could be implemented using "reduce" like this
31 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
33 for example wanted() could be defined() which would return the
35 first defined value in @list
36 max LIST
38 Returns the entry in the list with the highest numerical value. If
39 the list is empty then "undef" is returned.
40 $foo = max 1..10 # 10
42 $foo = max 3,9,12 # 12
43 $foo = max @bar, @baz # whatever
44 This function could be implemented using "reduce" like this
46 $foo = reduce { $a > $b ? $a : $b } 1..10
48 maxstr LIST
50 Similar to "max", but treats all the entries in the list as strings
51 and returns the highest string as defined by the "gt" operator. If
52 the list is empty then "undef" is returned.
53 $foo = maxstr 'A'..'Z' # 'Z'
55 $foo = maxstr "hello","world" # "world"
56 $foo = maxstr @bar, @baz # whatever
57 This function could be implemented using "reduce" like this
59 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
61 min LIST
63 Similar to "max" but returns the entry in the list with the lowest
64 numerical value. If the list is empty then "undef" is returned.
65 $foo = min 1..10 # 1
67 $foo = min 3,9,12 # 3
68 $foo = min @bar, @baz # whatever
69 This function could be implemented using "reduce" like this
71 $foo = reduce { $a < $b ? $a : $b } 1..10
73 minstr LIST
75 Similar to "min", but treats all the entries in the list as strings
76 and returns the lowest string as defined by the "lt" operator. If
77 the list is empty then "undef" is returned.
78 $foo = minstr 'A'..'Z' # 'A'
80 $foo = minstr "hello","world" # "hello"
81 $foo = minstr @bar, @baz # whatever
82 This function could be implemented using "reduce" like this
84 $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
86 reduce BLOCK LIST
88 Reduces LIST by calling BLOCK, in a scalar context, multiple times,
89 setting $a and $b each time. The first call will be with $a and $b
90 set to the first two elements of the list, subsequent calls will be
91 done by setting $a to the result of the previous call and $b to the
92 next element in the list.
93 Returns the result of the last call to BLOCK. If LIST is empty then
95 "undef" is returned. If LIST only contains one element then that
96 element is returned and BLOCK is not executed.
97 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
99 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
100 $foo = reduce { $a + $b } 1 .. 10 # sum
101 $foo = reduce { $a . $b } @bar # concat
102 If your algorithm requires that "reduce" produce an identity value,
104 then make sure that you always pass that identity value as the
105 first argument to prevent "undef" being returned
106 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
108 shuffle LIST
110 Returns the elements of LIST in a random order
111 @cards = shuffle 0..51 # 0..51 in a random order
113 sum LIST
115 Returns the sum of all the elements in LIST. If LIST is empty then
116 "undef" is returned.
117 $foo = sum 1..10 # 55
119 $foo = sum 3,9,12 # 24
120 $foo = sum @bar, @baz # whatever
121 This function could be implemented using "reduce" like this
123 $foo = reduce { $a + $b } 1..10
125 If your algorithm requires that "sum" produce an identity of 0,
127 then make sure that you always pass 0 as the first argument to
128 prevent "undef" being returned
129 $foo = sum 0, @values;
131 sum0 LIST
133 Similar to "sum", except this returns 0 when given an empty list,
134 rather than "undef".
135
137 With perl versions prior to 5.005 there are some cases where reduce
138 will return an incorrect result. This will show up as test 7 of
139 reduce.t failing.
140
142 The following are additions that have been requested, but I have been
143 reluctant to add due to them being very simple to implement in perl
144 # One argument is true
146 sub any { $_ && return 1 for @_; 0 }
148 # All arguments are true
150 sub all { $_ || return 0 for @_; 1 }
152 # All arguments are false
154 sub none { $_ && return 0 for @_; 1 }
156 # One argument is false
158 sub notall { $_ || return 1 for @_; 0 }
160 # How many elements are true
162 sub true { scalar grep { $_ } @_ }
164 # How many elements are false
166 sub false { scalar grep { !$_ } @_ }
168
170 Scalar::Util, List::MoreUtils
171
173 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights
174 reserved. This program is free software; you can redistribute it
175 and/or modify it under the same terms as Perl itself.
176perl v5.16.3 2012-12-27 List::Util(3)