This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add Scalar-List-Utils 1.02, from Graham Barr.
[perl5.git] / ext / List / Util / lib / List / Util.pm
CommitLineData
f4a2945e
JH
1# List::Util.pm
2#
3# Copyright (c) 1997-2000 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
7package List::Util;
8
9require Exporter;
10
11@ISA = qw(Exporter);
12@EXPORT_OK = qw(first min max minstr maxstr reduce sum);
13$VERSION = $VERSION = "1.02";
14
15eval {
16 require DynaLoader;
17 local @ISA = qw(DynaLoader);
18 bootstrap List::Util $VERSION;
19 1
20};
21
22eval <<'ESQ' unless defined &reduce;
23
24# This code is only compiled if the XS did not load
25
26use vars qw($a $b);
27
28sub reduce (&@) {
29 my $code = shift;
30
31 return shift unless @_ > 1;
32
33 my $caller = caller;
34 local(*{$caller."::a"}) = \my $a;
35 local(*{$caller."::b"}) = \my $b;
36
37 $a = shift;
38 foreach (@_) {
39 $b = $_;
40 $a = &{$code}();
41 }
42
43 $a;
44}
45
46sub sum (@) { reduce { $a + $b } @_ }
47
48sub min (@) { reduce { $a < $b ? $a : $b } @_ }
49
50sub max (@) { reduce { $a > $b ? $a : $b } @_ }
51
52sub minstr (@) { reduce { $a lt $b ? $a : $b } @_ }
53
54sub maxstr (@) { reduce { $a gt $b ? $a : $b } @_ }
55
56sub first (&@) {
57 my $code = shift;
58
59 foreach (@_) {
60 return $_ if &{$code}();
61 }
62
63 undef;
64}
65ESQ
66
671;
68
69__END__
70
71=head1 NAME
72
73List::Util - A selection of general-utility list subroutines
74
75=head1 SYNOPSIS
76
77 use List::Util qw(first sum min max minstr maxstr reduce);
78
79=head1 DESCRIPTION
80
81C<List::Util> contains a selection of subroutines that people have
82expressed would be nice to have in the perl core, but the usage would
83not really be high enough to warrant the use of a keyword, and the size
84so small such that being individual extensions would be wasteful.
85
86By default C<List::Util> does not export any subroutines. The
87subroutines defined are
88
89=over 4
90
91=item first BLOCK LIST
92
93Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
94of LIST in turn. C<first> returns the first element where the result from
95BLOCK is a true value. If BLOCK never returns true or LIST was empty then
96C<undef> is returned.
97
98 $foo = first { defined($_) } @list # first defined value in @list
99 $foo = first { $_ > $value } @list # first value in @list which
100 # is greater than $value
101
102This function could be implemented using C<reduce> like this
103
104 $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
105
106for example wanted() could be defined() which would return the first
107defined value in @list
108
109=item max LIST
110
111Returns the entry in the list with the highest numerical value. If the
112list is empty then C<undef> is returned.
113
114 $foo = max 1..10 # 10
115 $foo = max 3,9,12 # 12
116 $foo = max @bar, @baz # whatever
117
118This function could be implemented using C<reduce> like this
119
120 $foo = reduce { $a > $b ? $a : $b } 1..10
121
122=item maxstr LIST
123
124Similar to C<max>, but treats all the entries in the list as strings
125and returns the highest string as defined by the C<gt> operator.
126If the list is empty then C<undef> is returned.
127
128 $foo = maxstr 'A'..'Z' # 'Z'
129 $foo = maxstr "hello","world" # "world"
130 $foo = maxstr @bar, @baz # whatever
131
132This function could be implemented using C<reduce> like this
133
134 $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
135
136=item min LIST
137
138Similar to C<max> but returns the entry in the list with the lowest
139numerical value. If the list is empty then C<undef> is returned.
140
141 $foo = min 1..10 # 1
142 $foo = min 3,9,12 # 3
143 $foo = min @bar, @baz # whatever
144
145This function could be implemented using C<reduce> like this
146
147 $foo = reduce { $a < $b ? $a : $b } 1..10
148
149=item minstr LIST
150
151Similar to C<min>, but treats all the entries in the list as strings
152and returns the lowest string as defined by the C<lt> operator.
153If the list is empty then C<undef> is returned.
154
155 $foo = maxstr 'A'..'Z' # 'A'
156 $foo = maxstr "hello","world" # "hello"
157 $foo = maxstr @bar, @baz # whatever
158
159This function could be implemented using C<reduce> like this
160
161 $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
162
163=item reduce BLOCK LIST
164
165Reduces LIST by calling BLOCK multiple times, setting C<$a> and C<$b>
166each time. The first call will be with C<$a> and C<$b> set to the first
167two elements of the list, subsequent calls will be done by
168setting C<$a> to the result of the previous call and C<$b> to the next
169element in the list.
170
171Returns the result of the last call to BLOCK. If LIST is empty then
172C<undef> is returned. If LIST only contains one element then that
173element is returned and BLOCK is not executed.
174
175 $foo = reduce { $a < $b ? $a : $b } 1..10 # min
176 $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
177 $foo = reduce { $a + $b } 1 .. 10 # sum
178 $foo = reduce { $a . $b } @bar # concat
179
180=item sum LIST
181
182Returns the sum of all the elements in LIST.
183
184 $foo = sum 1..10 # 55
185 $foo = sum 3,9,12 # 24
186 $foo = sum @bar, @baz # whatever
187
188This function could be implemented using C<reduce> like this
189
190 $foo = reduce { $a + $b } 1..10
191
192=back
193
194=head1 SUGGESTED ADDITIONS
195
196The following are additions that have been requested, but I have been reluctant
197to add due to them being very simple to implement in perl
198
199 # One argument is true
200
201 sub any { $_ && return 1 for @_; 0 }
202
203 # All arguments are true
204
205 sub all { $_ || return 0 for @_; 1 }
206
207 # All arguments are false
208
209 sub none { $_ && return 0 for @_; 1 }
210
211 # One argument is false
212
213 sub notall { $_ || return 1 for @_; 0 }
214
215 # How many elements are true
216
217 sub true { scalar grep { $_ } @_ }
218
219 # How many elements are false
220
221 sub false { scalar grep { !$_ } @_ }
222
223=head1 COPYRIGHT
224
225Copyright (c) 1997-2000 Graham Barr <gbarr@pobox.com>. All rights reserved.
226This program is free software; you can redistribute it and/or
227modify it under the same terms as Perl itself.
228
229=cut