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