1List::Util(3pm) Perl Programmers Reference Guide List::Util(3pm)
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 subrou‐
18 tines 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 multiple times, setting $a and $b
89 each time. The first call will be with $a and $b set to the first
90 two elements of the list, subsequent calls will be done by setting
91 $a to the result of the previous call and $b to the next element in
92 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 shuffle LIST
104 Returns the elements of LIST in a random order
105 @cards = shuffle 0..51 # 0..51 in a random order
107 sum LIST
109 Returns the sum of all the elements in LIST. If LIST is empty then
110 "undef" is returned.
111 $foo = sum 1..10 # 55
113 $foo = sum 3,9,12 # 24
114 $foo = sum @bar, @baz # whatever
115 This function could be implemented using "reduce" like this
117 $foo = reduce { $a + $b } 1..10
119
121 With perl versions prior to 5.005 there are some cases where reduce
122 will return an incorrect result. This will show up as test 7 of
123 reduce.t failing.
124
126 The following are additions that have been requested, but I have been
127 reluctant to add due to them being very simple to implement in perl
128 # One argument is true
130 sub any { $_ && return 1 for @_; 0 }
132 # All arguments are true
134 sub all { $_ ⎪⎪ return 0 for @_; 1 }
136 # All arguments are false
138 sub none { $_ && return 0 for @_; 1 }
140 # One argument is false
142 sub notall { $_ ⎪⎪ return 1 for @_; 0 }
144 # How many elements are true
146 sub true { scalar grep { $_ } @_ }
148 # How many elements are false
150 sub false { scalar grep { !$_ } @_ }
152
154 Copyright (c) 1997-2005 Graham Barr <gbarr@pobox.com>. All rights
155 reserved. This program is free software; you can redistribute it
156 and/or modify it under the same terms as Perl itself.
157perl v5.8.8 2001-09-21 List::Util(3pm)