Commit | Line | Data |
f4a2945e |
1 | # List::Util.pm |
2 | # |
c29e891d |
3 | # Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved. |
f4a2945e |
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; |
ee4ffb48 |
10 | require DynaLoader; |
f4a2945e |
11 | |
60f3865b |
12 | our @ISA = qw(Exporter DynaLoader); |
13 | our @EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle); |
14 | our $VERSION = "1.08_00"; |
105cd853 |
15 | our $XS_VERSION = $VERSION; |
60f3865b |
16 | $VERSION = eval $VERSION; |
f4a2945e |
17 | |
105cd853 |
18 | bootstrap List::Util $XS_VERSION; |
f4a2945e |
19 | |
f4a2945e |
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 | |
c29e891d |
30 | use List::Util qw(first max maxstr min minstr reduce shuffle sum); |
f4a2945e |
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 |
c29e891d |
54 | |
f4a2945e |
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. |
c29e891d |
80 | |
81 | $foo = maxstr 'A'..'Z' # 'Z' |
f4a2945e |
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 | |
c29e891d |
108 | $foo = minstr 'A'..'Z' # 'A' |
109 | $foo = minstr "hello","world" # "hello" |
110 | $foo = minstr @bar, @baz # whatever |
f4a2945e |
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 |
c29e891d |
122 | element in the list. |
f4a2945e |
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 | |
1bfb5477 |
133 | =item shuffle LIST |
134 | |
135 | Returns the elements of LIST in a random order |
136 | |
c29e891d |
137 | @cards = shuffle 0..51 # 0..51 in a random order |
138 | |
f4a2945e |
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 | |
9c3c560b |
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 | |
f4a2945e |
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 | |
c29e891d |
190 | Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved. |
f4a2945e |
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 |