Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # List::Util.pm |
2 | # | |
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. | |
6 | ||
7 | package List::Util; | |
8 | ||
9 | require Exporter; | |
10 | require DynaLoader; | |
11 | ||
12 | our @ISA = qw(Exporter DynaLoader); | |
13 | our @EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle); | |
14 | our $VERSION = "1.07_00"; | |
15 | our $XS_VERSION = $VERSION; | |
16 | $VERSION = eval $VERSION; | |
17 | ||
18 | bootstrap List::Util $XS_VERSION; | |
19 | ||
20 | 1; | |
21 | ||
22 | __END__ | |
23 | ||
24 | =head1 NAME | |
25 | ||
26 | List::Util - A selection of general-utility list subroutines | |
27 | ||
28 | =head1 SYNOPSIS | |
29 | ||
30 | use List::Util qw(first max maxstr min minstr reduce shuffle sum); | |
31 | ||
32 | =head1 DESCRIPTION | |
33 | ||
34 | C<List::Util> contains a selection of subroutines that people have | |
35 | expressed would be nice to have in the perl core, but the usage would | |
36 | not really be high enough to warrant the use of a keyword, and the size | |
37 | so small such that being individual extensions would be wasteful. | |
38 | ||
39 | By default C<List::Util> does not export any subroutines. The | |
40 | subroutines defined are | |
41 | ||
42 | =over 4 | |
43 | ||
44 | =item first BLOCK LIST | |
45 | ||
46 | Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element | |
47 | of LIST in turn. C<first> returns the first element where the result from | |
48 | BLOCK is a true value. If BLOCK never returns true or LIST was empty then | |
49 | C<undef> is returned. | |
50 | ||
51 | $foo = first { defined($_) } @list # first defined value in @list | |
52 | $foo = first { $_ > $value } @list # first value in @list which | |
53 | # is greater than $value | |
54 | ||
55 | This function could be implemented using C<reduce> like this | |
56 | ||
57 | $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list | |
58 | ||
59 | for example wanted() could be defined() which would return the first | |
60 | defined value in @list | |
61 | ||
62 | =item max LIST | |
63 | ||
64 | Returns the entry in the list with the highest numerical value. If the | |
65 | list is empty then C<undef> is returned. | |
66 | ||
67 | $foo = max 1..10 # 10 | |
68 | $foo = max 3,9,12 # 12 | |
69 | $foo = max @bar, @baz # whatever | |
70 | ||
71 | This function could be implemented using C<reduce> like this | |
72 | ||
73 | $foo = reduce { $a > $b ? $a : $b } 1..10 | |
74 | ||
75 | =item maxstr LIST | |
76 | ||
77 | Similar to C<max>, but treats all the entries in the list as strings | |
78 | and returns the highest string as defined by the C<gt> operator. | |
79 | If the list is empty then C<undef> is returned. | |
80 | ||
81 | $foo = maxstr 'A'..'Z' # 'Z' | |
82 | $foo = maxstr "hello","world" # "world" | |
83 | $foo = maxstr @bar, @baz # whatever | |
84 | ||
85 | This function could be implemented using C<reduce> like this | |
86 | ||
87 | $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' | |
88 | ||
89 | =item min LIST | |
90 | ||
91 | Similar to C<max> but returns the entry in the list with the lowest | |
92 | numerical value. If the list is empty then C<undef> is returned. | |
93 | ||
94 | $foo = min 1..10 # 1 | |
95 | $foo = min 3,9,12 # 3 | |
96 | $foo = min @bar, @baz # whatever | |
97 | ||
98 | This function could be implemented using C<reduce> like this | |
99 | ||
100 | $foo = reduce { $a < $b ? $a : $b } 1..10 | |
101 | ||
102 | =item minstr LIST | |
103 | ||
104 | Similar to C<min>, but treats all the entries in the list as strings | |
105 | and returns the lowest string as defined by the C<lt> operator. | |
106 | If the list is empty then C<undef> is returned. | |
107 | ||
108 | $foo = minstr 'A'..'Z' # 'A' | |
109 | $foo = minstr "hello","world" # "hello" | |
110 | $foo = minstr @bar, @baz # whatever | |
111 | ||
112 | This function could be implemented using C<reduce> like this | |
113 | ||
114 | $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z' | |
115 | ||
116 | =item reduce BLOCK LIST | |
117 | ||
118 | Reduces LIST by calling BLOCK multiple times, setting C<$a> and C<$b> | |
119 | each time. The first call will be with C<$a> and C<$b> set to the first | |
120 | two elements of the list, subsequent calls will be done by | |
121 | setting C<$a> to the result of the previous call and C<$b> to the next | |
122 | element in the list. | |
123 | ||
124 | Returns the result of the last call to BLOCK. If LIST is empty then | |
125 | C<undef> is returned. If LIST only contains one element then that | |
126 | element is returned and BLOCK is not executed. | |
127 | ||
128 | $foo = reduce { $a < $b ? $a : $b } 1..10 # min | |
129 | $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr | |
130 | $foo = reduce { $a + $b } 1 .. 10 # sum | |
131 | $foo = reduce { $a . $b } @bar # concat | |
132 | ||
133 | =item shuffle LIST | |
134 | ||
135 | Returns the elements of LIST in a random order | |
136 | ||
137 | @cards = shuffle 0..51 # 0..51 in a random order | |
138 | ||
139 | =item sum LIST | |
140 | ||
141 | Returns the sum of all the elements in LIST. | |
142 | ||
143 | $foo = sum 1..10 # 55 | |
144 | $foo = sum 3,9,12 # 24 | |
145 | $foo = sum @bar, @baz # whatever | |
146 | ||
147 | This function could be implemented using C<reduce> like this | |
148 | ||
149 | $foo = reduce { $a + $b } 1..10 | |
150 | ||
151 | =back | |
152 | ||
153 | =head1 KNOWN BUGS | |
154 | ||
155 | With perl versions prior to 5.005 there are some cases where reduce | |
156 | will return an incorrect result. This will show up as test 7 of | |
157 | reduce.t failing. | |
158 | ||
159 | =head1 SUGGESTED ADDITIONS | |
160 | ||
161 | The following are additions that have been requested, but I have been reluctant | |
162 | to add due to them being very simple to implement in perl | |
163 | ||
164 | # One argument is true | |
165 | ||
166 | sub any { $_ && return 1 for @_; 0 } | |
167 | ||
168 | # All arguments are true | |
169 | ||
170 | sub all { $_ || return 0 for @_; 1 } | |
171 | ||
172 | # All arguments are false | |
173 | ||
174 | sub none { $_ && return 0 for @_; 1 } | |
175 | ||
176 | # One argument is false | |
177 | ||
178 | sub notall { $_ || return 1 for @_; 0 } | |
179 | ||
180 | # How many elements are true | |
181 | ||
182 | sub true { scalar grep { $_ } @_ } | |
183 | ||
184 | # How many elements are false | |
185 | ||
186 | sub false { scalar grep { !$_ } @_ } | |
187 | ||
188 | =head1 COPYRIGHT | |
189 | ||
190 | Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved. | |
191 | This program is free software; you can redistribute it and/or | |
192 | modify it under the same terms as Perl itself. | |
193 | ||
194 | =cut |