This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
All the authors of these modules have now been contacted;
[perl5.git] / ext / List / Util / lib / List / Util.pm
CommitLineData
f4a2945e
JH
1# List::Util.pm
2#
c29e891d 3# Copyright (c) 1997-2001 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.
6
7package List::Util;
8
9require Exporter;
ee4ffb48 10require DynaLoader;
f4a2945e 11
60f3865b
GB
12our @ISA = qw(Exporter DynaLoader);
13our @EXPORT_OK = qw(first min max minstr maxstr reduce sum shuffle);
97605c51 14our $VERSION = "1.11_00";
105cd853 15our $XS_VERSION = $VERSION;
60f3865b 16$VERSION = eval $VERSION;
f4a2945e 17
105cd853 18bootstrap List::Util $XS_VERSION;
f4a2945e 19
f4a2945e
JH
201;
21
22__END__
23
24=head1 NAME
25
26List::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
JH
31
32=head1 DESCRIPTION
33
34C<List::Util> contains a selection of subroutines that people have
35expressed would be nice to have in the perl core, but the usage would
36not really be high enough to warrant the use of a keyword, and the size
37so small such that being individual extensions would be wasteful.
38
39By default C<List::Util> does not export any subroutines. The
40subroutines defined are
41
42=over 4
43
44=item first BLOCK LIST
45
46Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
47of LIST in turn. C<first> returns the first element where the result from
48BLOCK is a true value. If BLOCK never returns true or LIST was empty then
49C<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
JH
55This function could be implemented using C<reduce> like this
56
57 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
58
59for example wanted() could be defined() which would return the first
60defined value in @list
61
62=item max LIST
63
64Returns the entry in the list with the highest numerical value. If the
65list 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
71This 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
77Similar to C<max>, but treats all the entries in the list as strings
78and returns the highest string as defined by the C<gt> operator.
79If the list is empty then C<undef> is returned.
c29e891d
GB
80
81 $foo = maxstr 'A'..'Z' # 'Z'
f4a2945e
JH
82 $foo = maxstr "hello","world" # "world"
83 $foo = maxstr @bar, @baz # whatever
84
85This 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
91Similar to C<max> but returns the entry in the list with the lowest
92numerical 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
98This 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
104Similar to C<min>, but treats all the entries in the list as strings
105and returns the lowest string as defined by the C<lt> operator.
106If the list is empty then C<undef> is returned.
107
c29e891d
GB
108 $foo = minstr 'A'..'Z' # 'A'
109 $foo = minstr "hello","world" # "hello"
110 $foo = minstr @bar, @baz # whatever
f4a2945e
JH
111
112This 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
118Reduces LIST by calling BLOCK multiple times, setting C<$a> and C<$b>
119each time. The first call will be with C<$a> and C<$b> set to the first
120two elements of the list, subsequent calls will be done by
121setting C<$a> to the result of the previous call and C<$b> to the next
c29e891d 122element in the list.
f4a2945e
JH
123
124Returns the result of the last call to BLOCK. If LIST is empty then
125C<undef> is returned. If LIST only contains one element then that
126element 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
GB
133=item shuffle LIST
134
135Returns the elements of LIST in a random order
136
c29e891d
GB
137 @cards = shuffle 0..51 # 0..51 in a random order
138
f4a2945e
JH
139=item sum LIST
140
141Returns 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
147This function could be implemented using C<reduce> like this
148
149 $foo = reduce { $a + $b } 1..10
150
151=back
152
9c3c560b
JH
153=head1 KNOWN BUGS
154
155With perl versions prior to 5.005 there are some cases where reduce
156will return an incorrect result. This will show up as test 7 of
157reduce.t failing.
158
f4a2945e
JH
159=head1 SUGGESTED ADDITIONS
160
161The following are additions that have been requested, but I have been reluctant
162to 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 190Copyright (c) 1997-2001 Graham Barr <gbarr@pobox.com>. All rights reserved.
f4a2945e
JH
191This program is free software; you can redistribute it and/or
192modify it under the same terms as Perl itself.
193
194=cut