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(any all none notall true false firstidx first_index
10 lastidx last_index insert_after insert_after_string
11 apply after after_incl before before_incl indexes
12 firstval first_value lastval last_value each_array
13 each_arrayref pairwise natatime mesh zip uniq minmax);
14
16 "List::MoreUtils" provides some trivial but commonly needed
17 functionality on lists which is not going to go into "List::Util".
18 All of the below functions are implementable in only a couple of lines
20 of Perl code. Using the functions from this module however should give
21 slightly better performance as everything is implemented in C. The
22 pure-Perl implementation of these functions only serves as a fallback
23 in case the C portions of this module couldn't be compiled on this
24 machine.
25 any BLOCK LIST
27 Returns a true value if any item in LIST meets the criterion given
28 through BLOCK. Sets $_ for each item in LIST in turn:
29 print "At least one value undefined"
31 if any { !defined($_) } @list;
32 Returns false otherwise, or "undef" if LIST is empty.
34 all BLOCK LIST
36 Returns a true value if all items in LIST meet the criterion given
37 through BLOCK. Sets $_ for each item in LIST in turn:
38 print "All items defined"
40 if all { defined($_) } @list;
41 Returns false otherwise, or "undef" if LIST is empty.
43 none BLOCK LIST
45 Logically the negation of "any". Returns a true value if no item in
46 LIST meets the criterion given through BLOCK. Sets $_ for each item
47 in LIST in turn:
48 print "No value defined"
50 if none { defined($_) } @list;
51 Returns false otherwise, or "undef" if LIST is empty.
53 notall BLOCK LIST
55 Logically the negation of "all". Returns a true value if not all
56 items in LIST meet the criterion given through BLOCK. Sets $_ for
57 each item in LIST in turn:
58 print "Not all values defined"
60 if notall { defined($_) } @list;
61 Returns false otherwise, or "undef" if LIST is empty.
63 true BLOCK LIST
65 Counts the number of elements in LIST for which the criterion in
66 BLOCK is true. Sets $_ for each item in LIST in turn:
67 printf "%i item(s) are defined", true { defined($_) } @list;
69 false BLOCK LIST
71 Counts the number of elements in LIST for which the criterion in
72 BLOCK is false. Sets $_ for each item in LIST in turn:
73 printf "%i item(s) are not defined", false { defined($_) } @list;
75 firstidx BLOCK LIST
77 first_index BLOCK LIST
78 Returns the index of the first element in LIST for which the
79 criterion in BLOCK is true. Sets $_ for each item in LIST in turn:
80 my @list = (1, 4, 3, 2, 4, 6);
82 printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
83 __END__
84 item with index 1 in list is 4
85 Returns "-1" if no such item could be found.
87 "first_index" is an alias for "firstidx".
89 lastidx BLOCK LIST
91 last_index BLOCK LIST
92 Returns the index of the last element in LIST for which the
93 criterion in BLOCK is true. Sets $_ for each item in LIST in turn:
94 my @list = (1, 4, 3, 2, 4, 6);
96 printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
97 __END__
98 item with index 4 in list is 4
99 Returns "-1" if no such item could be found.
101 "last_index" is an alias for "lastidx".
103 insert_after BLOCK VALUE LIST
105 Inserts VALUE after the first item in LIST for which the criterion
106 in BLOCK is true. Sets $_ for each item in LIST in turn.
107 my @list = qw/This is a list/;
109 insert_after { $_ eq "a" } "longer" => @list;
110 print "@list";
111 __END__
112 This is a longer list
113 insert_after_string STRING VALUE LIST
115 Inserts VALUE after the first item in LIST which is equal to
116 STRING.
117 my @list = qw/This is a list/;
119 insert_after_string "a", "longer" => @list;
120 print "@list";
121 __END__
122 This is a longer list
123 apply BLOCK LIST
125 Applies BLOCK to each item in LIST and returns a list of the values
126 after BLOCK has been applied. In scalar context, the last element
127 is returned. This function is similar to "map" but will not modify
128 the elements of the input list:
129 my @list = (1 .. 4);
131 my @mult = apply { $_ *= 2 } @list;
132 print "\@list = @list\n";
133 print "\@mult = @mult\n";
134 __END__
135 @list = 1 2 3 4
136 @mult = 2 4 6 8
137 Think of it as syntactic sugar for
139 for (my @mult = @list) { $_ *= 2 }
141 after BLOCK LIST
143 Returns a list of the values of LIST after (and not including) the
144 point where BLOCK returns a true value. Sets $_ for each element in
145 LIST in turn.
146 @x = after { $_ % 5 == 0 } (1..9); # returns 6, 7, 8, 9
148 after_incl BLOCK LIST
150 Same as "after" but also inclues the element for which BLOCK is
151 true.
152 before BLOCK LIST
154 Returns a list of values of LIST upto (and not including) the point
155 where BLOCK returns a true value. Sets $_ for each element in LIST
156 in turn.
157 before_incl BLOCK LIST
159 Same as "before" but also includes the element for which BLOCK is
160 true.
161 indexes BLOCK LIST
163 Evaluates BLOCK for each element in LIST (assigned to $_) and
164 returns a list of the indices of those elements for which BLOCK
165 returned a true value. This is just like "grep" only that it
166 returns indices instead of values:
167 @x = indexes { $_ % 2 == 0 } (1..10); # returns 1, 3, 5, 7, 9
169 firstval BLOCK LIST
171 first_value BLOCK LIST
172 Returns the first element in LIST for which BLOCK evaluates to
173 true. Each element of LIST is set to $_ in turn. Returns "undef" if
174 no such element has been found.
175 "first_val" is an alias for "firstval".
177 lastval BLOCK LIST
179 last_value BLOCK LIST
180 Returns the last value in LIST for which BLOCK evaluates to true.
181 Each element of LIST is set to $_ in turn. Returns "undef" if no
182 such element has been found.
183 "last_val" is an alias for "lastval".
185 pairwise BLOCK ARRAY1 ARRAY2
187 Evaluates BLOCK for each pair of elements in ARRAY1 and ARRAY2 and
188 returns a new list consisting of BLOCK's return values. The two
189 elements are set to $a and $b. Note that those two are aliases to
190 the original value so changing them will modify the input arrays.
191 @a = (1 .. 5);
193 @b = (11 .. 15);
194 @x = pairwise { $a + $b } @a, @b; # returns 12, 14, 16, 18, 20
195 # mesh with pairwise
197 @a = qw/a b c/;
198 @b = qw/1 2 3/;
199 @x = pairwise { ($a, $b) } @a, @b; # returns a, 1, b, 2, c, 3
200 each_array ARRAY1 ARRAY2 ...
202 Creates an array iterator to return the elements of the list of
203 arrays ARRAY1, ARRAY2 throughout ARRAYn in turn. That is, the
204 first time it is called, it returns the first element of each
205 array. The next time, it returns the second elements. And so on,
206 until all elements are exhausted.
207 This is useful for looping over more than one array at once:
209 my $ea = each_array(@a, @b, @c);
211 while ( my ($a, $b, $c) = $ea->() ) { .... }
212 The iterator returns the empty list when it reached the end of all
214 arrays.
215 If the iterator is passed an argument of '"index"', then it retuns
217 the index of the last fetched set of values, as a scalar.
218 each_arrayref LIST
220 Like each_array, but the arguments are references to arrays, not
221 the plain arrays.
222 natatime BLOCK LIST
224 Creates an array iterator, for looping over an array in chunks of
225 $n items at a time. (n at a time, get it?). An example is
226 probably a better explanation than I could give in words.
227 Example:
229 my @x = ('a' .. 'g');
231 my $it = natatime 3, @x;
232 while (my @vals = $it->())
233 {
234 print "@vals\n";
235 }
236 This prints
238 a b c
240 d e f
241 g
242 mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]
244 zip ARRAY1 ARRAY2 [ ARRAY3 ... ]
245 Returns a list consisting of the first elements of each array, then
246 the second, then the third, etc, until all arrays are exhausted.
247 Examples:
249 @x = qw/a b c d/;
251 @y = qw/1 2 3 4/;
252 @z = mesh @x, @y; # returns a, 1, b, 2, c, 3, d, 4
253 @a = ('x');
255 @b = ('1', '2');
256 @c = qw/zip zap zot/;
257 @d = mesh @a, @b, @c; # x, 1, zip, undef, 2, zap, undef, undef, zot
258 "zip" is an alias for "mesh".
260 uniq LIST
262 Returns a new list by stripping duplicate values in LIST. The order
263 of elements in the returned list is the same as in LIST. In scalar
264 context, returns the number of unique elements in LIST.
265 my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
267 my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
268 minmax LIST
270 Calculates the minimum and maximum of LIST and returns a two
271 element list with the first element being the minimum and the
272 second the maximum. Returns the empty list if LIST was empty.
273 The minmax algorithm differs from a naive iteration over the list
275 where each element is compared to two values being the so far
276 calculated min and max value in that it only requires 3n/2 - 2
277 comparisons. Thus it is the most efficient possible algorithm.
278 However, the Perl implementation of it has some overhead simply due
280 to the fact that there are more lines of Perl code involved.
281 Therefore, LIST needs to be fairly big in order for minmax to win
282 over a naive implementation. This limitation does not apply to the
283 XS version.
284 part BLOCK LIST
286 Partitions LIST based on the return value of BLOCK which denotes
287 into which partition the current value is put.
288 Returns a list of the partitions thusly created. Each partition
290 created is a reference to an array.
291 my $i = 0;
293 my @part = part { $i++ % 2 } 1 .. 8; # returns [1, 3, 5, 7], [2, 4, 6, 8]
294 You can have a sparse list of partitions as well where non-set
296 partitions will be undef:
297 my @part = part { 2 } 1 .. 10; # returns undef, undef, [ 1 .. 10 ]
299 Be careful with negative values, though:
301 my @part = part { -1 } 1 .. 10;
303 __END__
304 Modification of non-creatable array value attempted, subscript -1 ...
305 Negative values are only ok when they refer to a partition
307 previously created:
308 my @idx = (0, 1, -1);
310 my $i = 0;
311 my @part = part { $idx[$++ % 3] } 1 .. 8; # [1, 4, 7], [2, 3, 5, 6, 8]
312
314 Nothing by default. To import all of this module's symbols, do the
315 conventional
316 use List::MoreUtils qw/:all/;
318 It may make more sense though to only import the stuff your program
320 actually needs:
321 use List::MoreUtils qw/any firstidx/;
323
325 When "LIST_MOREUTILS_PP" is set, the module will always use the pure-
326 Perl implementation and not the XS one. This environment variable is
327 really just there for the test-suite to force testing the Perl
328 implementation, and possibly for reporting of bugs. I don't see any
329 reason to use it in a production environment.
330
332 This is version 0.22.
333
335 There is a problem with a bug in 5.6.x perls. It is a syntax error to
336 write things like:
337 my @x = apply { s/foo/bar/ } qw/foo bar baz/;
339 It has to be written as either
341 my @x = apply { s/foo/bar/ } 'foo', 'bar', 'baz';
343 or
345 my @x = apply { s/foo/bar/ } my @dummy = qw/foo bar baz/;
347 Perl5.5.x and perl5.8.x don't suffer from this limitation.
349 If you have a functionality that you could imagine being in this
351 module, please drop me a line. This module's policy will be less strict
352 than "List::Util"'s when it comes to additions as it isn't a core
353 module.
354 When you report bugs, it would be nice if you could additionally give
356 me the output of your program with the environment variable
357 "LIST_MOREUTILS_PP" set to a true value. That way I know where to look
358 for the problem (in XS, pure-Perl or possibly both).
359
361 Credits go to a number of people: Steve Purkis for giving me namespace
362 advice and James Keenan and Terrence Branno for their effort of keeping
363 the CPAN tidier by making List::Utils obsolete.
364 Brian McCauley suggested the inclusion of apply() and provided the
366 pure-Perl implementation for it.
367 Eric J. Roode asked me to add all functions from his module
369 "List::MoreUtil" into this one. With minor modifications, the pure-Perl
370 implementations of those are by him.
371 The bunch of people who almost immediately pointed out the many
373 problems with the glitchy 0.07 release (Slaven Rezic, Ron Savage, CPAN
374 testers).
375 A particularly nasty memory leak was spotted by Thomas A. Lowery.
377 Lars Thegler made me aware of problems with older Perl versions.
379 Anno Siegel de-orphaned each_arrayref().
381 David Filmer made me aware of a problem in each_arrayref that could
383 ultimately lead to a segfault.
384 Ricardo Signes suggested the inclusion of part() and provided the Perl-
386 implementation.
387 Robin Huston kindly fixed a bug in perl's MULTICALL API to make the XS-
389 implementation of part() work.
390
392 A pile of requests from other people is still pending further
393 processing in my mailbox. This includes:
394 · uniq_by(&@)
396 Use code-reference to extract a key based on which the uniqueness
398 is determined. Suggested by Aaron Crane.
399 · delete_index
401 · random_item
403 · random_item_delete_index
405 · list_diff_hash
407 · list_diff_inboth
409 · list_diff_infirst
411 · list_diff_insecond
413 These were all suggested by Dan Muey.
415 · listify
417 Always return a flat list when either a simple scalar value was
419 passed or an array-reference. Suggested by Mark Summersault.
420
422 List::Util
423
425 Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>
426
428 Copyright (C) 2004-2006 by Tassilo von Parseval
429 This library is free software; you can redistribute it and/or modify it
431 under the same terms as Perl itself, either Perl version 5.8.4 or, at
432 your option, any later version of Perl 5 you may have available.
433perl v5.10.1 2006-07-02 List::MoreUtils(3)