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