1List::MoreUtils(3) User Contributed Perl Documentation List::MoreUtils(3)
2
6 List::MoreUtils - Provide the stuff missing in List::Util
7
9 use List::MoreUtils qw{
10 any all none notall true false
11 firstidx first_index lastidx last_index
12 insert_after insert_after_string
13 apply indexes
14 after after_incl before before_incl
15 firstval first_value lastval last_value
16 each_array each_arrayref
17 pairwise natatime
18 mesh zip uniq distinct minmax part
19 };
20
22 List::MoreUtils provides some trivial but commonly needed functionality
23 on lists which is not going to go into List::Util.
24 All of the below functions are implementable in only a couple of lines
26 of Perl code. Using the functions from this module however should give
27 slightly better performance as everything is implemented in C. The
28 pure-Perl implementation of these functions only serves as a fallback
29 in case the C portions of this module couldn't be compiled on this
30 machine.
31 any BLOCK LIST
33 Returns a true value if any item in LIST meets the criterion given
34 through BLOCK. Sets $_ for each item in LIST in turn:
35 print "At least one value undefined"
37 if any { ! defined($_) } @list;
38 Returns false otherwise, or if LIST is empty.
40 all BLOCK LIST
42 Returns a true value if all items in LIST meet the criterion given
43 through BLOCK, or if LIST is empty. Sets $_ for each item in LIST
44 in turn:
45 print "All items defined"
47 if all { defined($_) } @list;
48 Returns false otherwise.
50 none BLOCK LIST
52 Logically the negation of "any". Returns a true value if no item in
53 LIST meets the criterion given through BLOCK, or if LIST is empty.
54 Sets $_ for each item in LIST in turn:
55 print "No value defined"
57 if none { defined($_) } @list;
58 Returns false otherwise.
60 notall BLOCK LIST
62 Logically the negation of "all". Returns a true value if not all
63 items in LIST meet the criterion given through BLOCK. Sets $_ for
64 each item in LIST in turn:
65 print "Not all values defined"
67 if notall { defined($_) } @list;
68 Returns false otherwise, or if LIST is empty.
70 true BLOCK LIST
72 Counts the number of elements in LIST for which the criterion in
73 BLOCK is true. Sets $_ for each item in LIST in turn:
74 printf "%i item(s) are defined", true { defined($_) } @list;
76 false BLOCK LIST
78 Counts the number of elements in LIST for which the criterion in
79 BLOCK is false. Sets $_ for each item in LIST in turn:
80 printf "%i item(s) are not defined", false { defined($_) } @list;
82 firstidx BLOCK LIST
84 first_index BLOCK LIST
85 Returns the index of the first element in LIST for which the
86 criterion in BLOCK is true. Sets $_ for each item in LIST in turn:
87 my @list = (1, 4, 3, 2, 4, 6);
89 printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
90 __END__
91 item with index 1 in list is 4
92 Returns "-1" if no such item could be found.
94 "first_index" is an alias for "firstidx".
96 lastidx BLOCK LIST
98 last_index BLOCK LIST
99 Returns the index of the last element in LIST for which the
100 criterion in BLOCK is true. Sets $_ for each item in LIST in turn:
101 my @list = (1, 4, 3, 2, 4, 6);
103 printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
104 __END__
105 item with index 4 in list is 4
106 Returns "-1" if no such item could be found.
108 "last_index" is an alias for "lastidx".
110 insert_after BLOCK VALUE LIST
112 Inserts VALUE after the first item in LIST for which the criterion
113 in BLOCK is true. Sets $_ for each item in LIST in turn.
114 my @list = qw/This is a list/;
116 insert_after { $_ eq "a" } "longer" => @list;
117 print "@list";
118 __END__
119 This is a longer list
120 insert_after_string STRING VALUE LIST
122 Inserts VALUE after the first item in LIST which is equal to
123 STRING.
124 my @list = qw/This is a list/;
126 insert_after_string "a", "longer" => @list;
127 print "@list";
128 __END__
129 This is a longer list
130 apply BLOCK LIST
132 Applies BLOCK to each item in LIST and returns a list of the values
133 after BLOCK has been applied. In scalar context, the last element
134 is returned. This function is similar to "map" but will not modify
135 the elements of the input list:
136 my @list = (1 .. 4);
138 my @mult = apply { $_ *= 2 } @list;
139 print "\@list = @list\n";
140 print "\@mult = @mult\n";
141 __END__
142 @list = 1 2 3 4
143 @mult = 2 4 6 8
144 Think of it as syntactic sugar for
146 for (my @mult = @list) { $_ *= 2 }
148 before BLOCK LIST
150 Returns a list of values of LIST upto (and not including) the point
151 where BLOCK returns a true value. Sets $_ for each element in LIST
152 in turn.
153 before_incl BLOCK LIST
155 Same as "before" but also includes the element for which BLOCK is
156 true.
157 after BLOCK LIST
159 Returns a list of the values of LIST after (and not including) the
160 point where BLOCK returns a true value. Sets $_ for each element in
161 LIST in turn.
162 @x = after { $_ % 5 == 0 } (1..9); # returns 6, 7, 8, 9
164 after_incl BLOCK LIST
166 Same as "after" but also inclues the element for which BLOCK is
167 true.
168 indexes BLOCK LIST
170 Evaluates BLOCK for each element in LIST (assigned to $_) and
171 returns a list of the indices of those elements for which BLOCK
172 returned a true value. This is just like "grep" only that it
173 returns indices instead of values:
174 @x = indexes { $_ % 2 == 0 } (1..10); # returns 1, 3, 5, 7, 9
176 firstval BLOCK LIST
178 first_value BLOCK LIST
179 Returns the first element in LIST for which BLOCK evaluates to
180 true. Each element of LIST is set to $_ in turn. Returns "undef" if
181 no such element has been found.
182 "first_val" is an alias for "firstval".
184 lastval BLOCK LIST
186 last_value BLOCK LIST
187 Returns the last value in LIST for which BLOCK evaluates to true.
188 Each element of LIST is set to $_ in turn. Returns "undef" if no
189 such element has been found.
190 "last_val" is an alias for "lastval".
192 pairwise BLOCK ARRAY1 ARRAY2
194 Evaluates BLOCK for each pair of elements in ARRAY1 and ARRAY2 and
195 returns a new list consisting of BLOCK's return values. The two
196 elements are set to $a and $b. Note that those two are aliases to
197 the original value so changing them will modify the input arrays.
198 @a = (1 .. 5);
200 @b = (11 .. 15);
201 @x = pairwise { $a + $b } @a, @b; # returns 12, 14, 16, 18, 20
202 # mesh with pairwise
204 @a = qw/a b c/;
205 @b = qw/1 2 3/;
206 @x = pairwise { ($a, $b) } @a, @b; # returns a, 1, b, 2, c, 3
207 each_array ARRAY1 ARRAY2 ...
209 Creates an array iterator to return the elements of the list of
210 arrays ARRAY1, ARRAY2 throughout ARRAYn in turn. That is, the
211 first time it is called, it returns the first element of each
212 array. The next time, it returns the second elements. And so on,
213 until all elements are exhausted.
214 This is useful for looping over more than one array at once:
216 my $ea = each_array(@a, @b, @c);
218 while ( my ($a, $b, $c) = $ea->() ) { .... }
219 The iterator returns the empty list when it reached the end of all
221 arrays.
222 If the iterator is passed an argument of '"index"', then it retuns
224 the index of the last fetched set of values, as a scalar.
225 each_arrayref LIST
227 Like each_array, but the arguments are references to arrays, not
228 the plain arrays.
229 natatime EXPR, LIST
231 Creates an array iterator, for looping over an array in chunks of
232 $n items at a time. (n at a time, get it?). An example is
233 probably a better explanation than I could give in words.
234 Example:
236 my @x = ('a' .. 'g');
238 my $it = natatime 3, @x;
239 while (my @vals = $it->())
240 {
241 print "@vals\n";
242 }
243 This prints
245 a b c
247 d e f
248 g
249 mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]
251 zip ARRAY1 ARRAY2 [ ARRAY3 ... ]
252 Returns a list consisting of the first elements of each array, then
253 the second, then the third, etc, until all arrays are exhausted.
254 Examples:
256 @x = qw/a b c d/;
258 @y = qw/1 2 3 4/;
259 @z = mesh @x, @y; # returns a, 1, b, 2, c, 3, d, 4
260 @a = ('x');
262 @b = ('1', '2');
263 @c = qw/zip zap zot/;
264 @d = mesh @a, @b, @c; # x, 1, zip, undef, 2, zap, undef, undef, zot
265 "zip" is an alias for "mesh".
267 uniq LIST
269 distinct LIST
270 Returns a new list by stripping duplicate values in LIST. The order
271 of elements in the returned list is the same as in LIST. In scalar
272 context, returns the number of unique elements in LIST.
273 my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
275 my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
276 minmax LIST
278 Calculates the minimum and maximum of LIST and returns a two
279 element list with the first element being the minimum and the
280 second the maximum. Returns the empty list if LIST was empty.
281 The "minmax" algorithm differs from a naive iteration over the list
283 where each element is compared to two values being the so far
284 calculated min and max value in that it only requires 3n/2 - 2
285 comparisons. Thus it is the most efficient possible algorithm.
286 However, the Perl implementation of it has some overhead simply due
288 to the fact that there are more lines of Perl code involved.
289 Therefore, LIST needs to be fairly big in order for "minmax" to win
290 over a naive implementation. This limitation does not apply to the
291 XS version.
292 part BLOCK LIST
294 Partitions LIST based on the return value of BLOCK which denotes
295 into which partition the current value is put.
296 Returns a list of the partitions thusly created. Each partition
298 created is a reference to an array.
299 my $i = 0;
301 my @part = part { $i++ % 2 } 1 .. 8; # returns [1, 3, 5, 7], [2, 4, 6, 8]
302 You can have a sparse list of partitions as well where non-set
304 partitions will be undef:
305 my @part = part { 2 } 1 .. 10; # returns undef, undef, [ 1 .. 10 ]
307 Be careful with negative values, though:
309 my @part = part { -1 } 1 .. 10;
311 __END__
312 Modification of non-creatable array value attempted, subscript -1 ...
313 Negative values are only ok when they refer to a partition
315 previously created:
316 my @idx = ( 0, 1, -1 );
318 my $i = 0;
319 my @part = part { $idx[$++ % 3] } 1 .. 8; # [1, 4, 7], [2, 3, 5, 6, 8]
320
322 Nothing by default. To import all of this module's symbols, do the
323 conventional
324 use List::MoreUtils ':all';
326 It may make more sense though to only import the stuff your program
328 actually needs:
329 use List::MoreUtils qw{ any firstidx };
331
333 When "LIST_MOREUTILS_PP" is set, the module will always use the pure-
334 Perl implementation and not the XS one. This environment variable is
335 really just there for the test-suite to force testing the Perl
336 implementation, and possibly for reporting of bugs. I don't see any
337 reason to use it in a production environment.
338
340 There is a problem with a bug in 5.6.x perls. It is a syntax error to
341 write things like:
342 my @x = apply { s/foo/bar/ } qw{ foo bar baz };
344 It has to be written as either
346 my @x = apply { s/foo/bar/ } 'foo', 'bar', 'baz';
348 or
350 my @x = apply { s/foo/bar/ } my @dummy = qw/foo bar baz/;
352 Perl 5.5.x and Perl 5.8.x don't suffer from this limitation.
354 If you have a functionality that you could imagine being in this
356 module, please drop me a line. This module's policy will be less strict
357 than List::Util's when it comes to additions as it isn't a core module.
358 When you report bugs, it would be nice if you could additionally give
360 me the output of your program with the environment variable
361 "LIST_MOREUTILS_PP" set to a true value. That way I know where to look
362 for the problem (in XS, pure-Perl or possibly both).
363
365 Bugs should always be submitted via the CPAN bug tracker.
366 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=List-MoreUtils>
368
370 Credits go to a number of people: Steve Purkis for giving me namespace
371 advice and James Keenan and Terrence Branno for their effort of keeping
372 the CPAN tidier by making List::Utils obsolete.
373 Brian McCauley suggested the inclusion of apply() and provided the
375 pure-Perl implementation for it.
376 Eric J. Roode asked me to add all functions from his module
378 "List::MoreUtil" into this one. With minor modifications, the pure-Perl
379 implementations of those are by him.
380 The bunch of people who almost immediately pointed out the many
382 problems with the glitchy 0.07 release (Slaven Rezic, Ron Savage, CPAN
383 testers).
384 A particularly nasty memory leak was spotted by Thomas A. Lowery.
386 Lars Thegler made me aware of problems with older Perl versions.
388 Anno Siegel de-orphaned each_arrayref().
390 David Filmer made me aware of a problem in each_arrayref that could
392 ultimately lead to a segfault.
393 Ricardo Signes suggested the inclusion of part() and provided the Perl-
395 implementation.
396 Robin Huston kindly fixed a bug in perl's MULTICALL API to make the XS-
398 implementation of part() work.
399
401 A pile of requests from other people is still pending further
402 processing in my mailbox. This includes:
403 · List::Util export pass-through
405 Allow List::MoreUtils to pass-through the regular List::Util
407 functions to end users only need to "use" the one module.
408 · uniq_by(&@)
410 Use code-reference to extract a key based on which the uniqueness
412 is determined. Suggested by Aaron Crane.
413 · delete_index
415 · random_item
417 · random_item_delete_index
419 · list_diff_hash
421 · list_diff_inboth
423 · list_diff_infirst
425 · list_diff_insecond
427 These were all suggested by Dan Muey.
429 · listify
431 Always return a flat list when either a simple scalar value was
433 passed or an array-reference. Suggested by Mark Summersault.
434
436 List::Util
437
439 Adam Kennedy <adamk@cpan.org>
440 Tassilo von Parseval <tassilo.von.parseval@rwth-aachen.de>
442
444 Some parts copyright 2011 Aaron Crane.
445 Copyright 2004 - 2010 by Tassilo von Parseval
447 This library is free software; you can redistribute it and/or modify it
449 under the same terms as Perl itself, either Perl version 5.8.4 or, at
450 your option, any later version of Perl 5 you may have available.
451perl v5.16.3 2011-08-04 List::MoreUtils(3)