This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Storable should not assume that sizeof(mg_len) is 4.
[perl5.git] / cpan / List-Util / lib / List / Util.pm
CommitLineData
f4a2945e
JH
1# List::Util.pm
2#
2ff28616 3# Copyright (c) 1997-2009 Graham Barr <gbarr@pobox.com>. All rights reserved.
f4a2945e
JH
4# This program is free software; you can redistribute it and/or
5# modify it under the same terms as Perl itself.
2ff28616
GB
6#
7# This module is normally only loaded if the XS module is not available
f4a2945e
JH
8
9package List::Util;
10
82f35e8b 11use strict;
f4a2945e
JH
12require Exporter;
13
3630f57e 14our @ISA = qw(Exporter);
2dc8d725
CBW
15our @EXPORT_OK = qw(first min max minstr maxstr reduce sum sum0 shuffle pairmap pairgrep pairs pairkeys pairvalues);
16our $VERSION = "1.29";
3630f57e 17our $XS_VERSION = $VERSION;
60f3865b 18$VERSION = eval $VERSION;
f4a2945e 19
3630f57e
CBW
20require XSLoader;
21XSLoader::load('List::Util', $XS_VERSION);
09c2a9b8 22
8b198969
CBW
23sub sum0
24{
25 return 0 unless @_;
26 goto &sum;
27}
28
f4a2945e
JH
291;
30
31__END__
32
33=head1 NAME
34
35List::Util - A selection of general-utility list subroutines
36
37=head1 SYNOPSIS
38
c29e891d 39 use List::Util qw(first max maxstr min minstr reduce shuffle sum);
f4a2945e
JH
40
41=head1 DESCRIPTION
42
43C<List::Util> contains a selection of subroutines that people have
44expressed would be nice to have in the perl core, but the usage would
45not really be high enough to warrant the use of a keyword, and the size
46so small such that being individual extensions would be wasteful.
47
48By default C<List::Util> does not export any subroutines. The
49subroutines defined are
50
51=over 4
52
53=item first BLOCK LIST
54
55Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
56of LIST in turn. C<first> returns the first element where the result from
57BLOCK is a true value. If BLOCK never returns true or LIST was empty then
58C<undef> is returned.
59
60 $foo = first { defined($_) } @list # first defined value in @list
61 $foo = first { $_ > $value } @list # first value in @list which
62 # is greater than $value
c29e891d 63
f4a2945e
JH
64This function could be implemented using C<reduce> like this
65
66 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
67
68for example wanted() could be defined() which would return the first
69defined value in @list
70
71=item max LIST
72
73Returns the entry in the list with the highest numerical value. If the
74list is empty then C<undef> is returned.
75
76 $foo = max 1..10 # 10
77 $foo = max 3,9,12 # 12
78 $foo = max @bar, @baz # whatever
79
80This function could be implemented using C<reduce> like this
81
82 $foo = reduce { $a > $b ? $a : $b } 1..10
83
84=item maxstr LIST
85
86Similar to C<max>, but treats all the entries in the list as strings
87and returns the highest string as defined by the C<gt> operator.
88If the list is empty then C<undef> is returned.
c29e891d
GB
89
90 $foo = maxstr 'A'..'Z' # 'Z'
f4a2945e
JH
91 $foo = maxstr "hello","world" # "world"
92 $foo = maxstr @bar, @baz # whatever
93
94This function could be implemented using C<reduce> like this
95
96 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
97
98=item min LIST
99
100Similar to C<max> but returns the entry in the list with the lowest
101numerical value. If the list is empty then C<undef> is returned.
102
103 $foo = min 1..10 # 1
104 $foo = min 3,9,12 # 3
105 $foo = min @bar, @baz # whatever
106
107This function could be implemented using C<reduce> like this
108
109 $foo = reduce { $a < $b ? $a : $b } 1..10
110
111=item minstr LIST
112
113Similar to C<min>, but treats all the entries in the list as strings
114and returns the lowest string as defined by the C<lt> operator.
115If the list is empty then C<undef> is returned.
116
c29e891d
GB
117 $foo = minstr 'A'..'Z' # 'A'
118 $foo = minstr "hello","world" # "hello"
119 $foo = minstr @bar, @baz # whatever
f4a2945e
JH
120
121This function could be implemented using C<reduce> like this
122
123 $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
124
2dc8d725
CBW
125=item pairgrep BLOCK KVLIST
126
127Similar to perl's C<grep> keyword, but interprets the given list as an
128even-sized list of pairs. It invokes the BLOCK multiple times, in scalar
129context, with C<$a> and C<$b> set to successive pairs of values from the
130KVLIST.
131
132Returns an even-sized list of those pairs for which the BLOCK returned true
133in list context, or the count of the B<number of pairs> in scalar context.
134(Note, therefore, in scalar context that it returns a number half the size
135of the count of items it would have returned in list context).
136
137 @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
138
139Similar to C<grep>, C<pairgrep> aliases C<$a> and C<$b> to elements of the
140given list. Any modifications of it by the code block will be visible to
141the caller.
142
143=item pairmap BLOCK KVLIST
144
145Similar to perl's C<map> keyword, but interprets the given list as an
146even-sized list of pairs. It invokes the BLOCK multiple times, in list
147context, with C<$a> and C<$b> set to successive pairs of values from the
148KVLIST.
149
150Returns the concatenation of all the values returned by the BLOCK in list
151context, or the count of the number of items that would have been returned
152in scalar context.
153
154 @result = pairmap { "The key $a has value $b" } @kvlist
155
156Similar to C<map>, C<pairmap> aliases C<$a> and C<$b> to elements of the
157given list. Any modifications of it by the code block will be visible to
158the caller.
159
160=item pairs KVLIST
161
162A convenient shortcut to operating on even-sized lists of pairs, this
163function returns a list of ARRAY references, each containing two items from
164the given list. It is a more efficient version of
165
166 pairmap { [ $a, $b ] } KVLIST
167
168It is most convenient to use in a C<foreach> loop, for example:
169
170 foreach ( pairs @KVLIST ) {
171 my ( $key, $value ) = @$_;
172 ...
173 }
174
175=item pairkeys KVLIST
176
177A convenient shortcut to operating on even-sized lists of pairs, this
178function returns a list of the the first values of each of the pairs in
179the given list. It is a more efficient version of
180
181 pairmap { $a } KVLIST
182
183=item pairvalues KVLIST
184
185A convenient shortcut to operating on even-sized lists of pairs, this
186function returns a list of the the second values of each of the pairs in
187the given list. It is a more efficient version of
188
189 pairmap { $b } KVLIST
190
f4a2945e
JH
191=item reduce BLOCK LIST
192
ddf53ba4
GB
193Reduces LIST by calling BLOCK, in a scalar context, multiple times,
194setting C<$a> and C<$b> each time. The first call will be with C<$a>
195and C<$b> set to the first two elements of the list, subsequent
196calls will be done by setting C<$a> to the result of the previous
197call and C<$b> to the next element in the list.
f4a2945e
JH
198
199Returns the result of the last call to BLOCK. If LIST is empty then
200C<undef> is returned. If LIST only contains one element then that
201element is returned and BLOCK is not executed.
202
203 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
204 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
205 $foo = reduce { $a + $b } 1 .. 10 # sum
206 $foo = reduce { $a . $b } @bar # concat
207
2ff28616
GB
208If your algorithm requires that C<reduce> produce an identity value, then
209make sure that you always pass that identity value as the first argument to prevent
210C<undef> being returned
211
212 $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
213
1bfb5477
GB
214=item shuffle LIST
215
216Returns the elements of LIST in a random order
217
c29e891d
GB
218 @cards = shuffle 0..51 # 0..51 in a random order
219
f4a2945e
JH
220=item sum LIST
221
82f35e8b
RH
222Returns the sum of all the elements in LIST. If LIST is empty then
223C<undef> is returned.
f4a2945e
JH
224
225 $foo = sum 1..10 # 55
226 $foo = sum 3,9,12 # 24
227 $foo = sum @bar, @baz # whatever
228
229This function could be implemented using C<reduce> like this
230
231 $foo = reduce { $a + $b } 1..10
232
2ff28616
GB
233If your algorithm requires that C<sum> produce an identity of 0, then
234make sure that you always pass C<0> as the first argument to prevent
235C<undef> being returned
236
237 $foo = sum 0, @values;
238
8b198969
CBW
239=item sum0 LIST
240
241Similar to C<sum>, except this returns 0 when given an empty list, rather
242than C<undef>.
243
f4a2945e
JH
244=back
245
9c3c560b
JH
246=head1 KNOWN BUGS
247
248With perl versions prior to 5.005 there are some cases where reduce
249will return an incorrect result. This will show up as test 7 of
250reduce.t failing.
251
f4a2945e
JH
252=head1 SUGGESTED ADDITIONS
253
254The following are additions that have been requested, but I have been reluctant
255to add due to them being very simple to implement in perl
256
257 # One argument is true
258
259 sub any { $_ && return 1 for @_; 0 }
260
261 # All arguments are true
262
263 sub all { $_ || return 0 for @_; 1 }
264
265 # All arguments are false
266
267 sub none { $_ && return 0 for @_; 1 }
268
269 # One argument is false
270
271 sub notall { $_ || return 1 for @_; 0 }
272
273 # How many elements are true
274
275 sub true { scalar grep { $_ } @_ }
276
277 # How many elements are false
278
279 sub false { scalar grep { !$_ } @_ }
280
ddf53ba4
GB
281=head1 SEE ALSO
282
283L<Scalar::Util>, L<List::MoreUtils>
284
f4a2945e
JH
285=head1 COPYRIGHT
286
2ff28616 287Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
f4a2945e
JH
288This program is free software; you can redistribute it and/or
289modify it under the same terms as Perl itself.
290
291=cut