1List::UtilsBy(3) User Contributed Perl Documentation List::UtilsBy(3)
2
6 "List::UtilsBy" - higher-order list utility functions
7
9 use List::UtilsBy qw( nsort_by min_by );
10 use File::stat qw( stat );
12 my @files_by_age = nsort_by { stat($_)->mtime } @files;
13 my $shortest_name = min_by { length } @names;
15
17 This module provides a number of list utility functions, all of which
18 take an initial code block to control their behaviour. They are
19 variations on similar core perl or "List::Util" functions of similar
20 names, but which use the block to control their behaviour. For example,
21 the core Perl function "sort" takes a list of values and returns them,
22 sorted into order by their string value. The "sort_by" function sorts
23 them according to the string value returned by the extra function, when
24 given each value.
25 my @names_sorted = sort @names;
27 my @people_sorted = sort_by { $_->name } @people;
29
31 @vals = sort_by { KEYFUNC } @vals
32 Returns the list of values sorted according to the string values
33 returned by the "KEYFUNC" block or function. A typical use of this may
34 be to sort objects according to the string value of some accessor, such
35 as
36 sort_by { $_->name } @people
38 The key function is called in scalar context, being passed each value
40 in turn as both $_ and the only argument in the parameters, @_. The
41 values are then sorted according to string comparisons on the values
42 returned.
43 This is equivalent to
45 sort { $a->name cmp $b->name } @people
47 except that it guarantees the "name" accessor will be executed only
49 once per value.
50 @vals = nsort_by { KEYFUNC } @vals
52 Similar to "sort_by" but compares its key values numerically.
53 @vals = rev_sort_by { KEYFUNC } @vals
55 @vals = rev_nsort_by { KEYFUNC } @vals
56 Similar to "sort_by" and "nsort_by" but returns the list in the reverse
57 order. Equivalent to
58 @vals = reverse sort_by { KEYFUNC } @vals
60 except that these functions are slightly more efficient because they
62 avoid the final "reverse" operation.
63 $optimal = max_by { KEYFUNC } @vals
65 @optimal = max_by { KEYFUNC } @vals
66 Returns the (first) value from @vals that gives the numerically largest
67 result from the key function.
68 my $tallest = max_by { $_->height } @people
70 use File::stat qw( stat );
72 my $newest = max_by { stat($_)->mtime } @files;
73 In scalar context, the first maximal value is returned. In list
75 context, a list of all the maximal values is returned. This may be used
76 to obtain positions other than the first, if order is significant.
77 If called on an empty list, an empty list is returned.
79 $optimal = min_by { KEYFUNC } @vals
81 @optimal = min_by { KEYFUNC } @vals
82 Similar to "max_by" but returns values which give the numerically
83 smallest result from the key function.
84 @vals = uniq_by { KEYFUNC } @vals
86 Returns a list of the subset of values for which the key function block
87 returns unique values. The first value yielding a particular key is
88 chosen, subsequent values are rejected.
89 my @some_fruit = uniq_by { $_->colour } @fruit;
91 To select instead the last value per key, reverse the input list. If
93 the order of the results is significant, don't forget to reverse the
94 result as well:
95 my @some_fruit = reverse uniq_by { $_->colour } reverse @fruit;
97 %parts = partition_by { KEYFUNC } @vals
99 Returns a hash of ARRAY refs, containing all the original values
100 distributed according to the result of the key function block. Each
101 ARRAY ref will contain all the values which returned the same string
102 from the key function, in their original order.
103 my %balls_by_colour = partition_by { $_->colour } @balls;
105 Because the values returned by the key function are used as hash keys,
107 they ought to either be strings, or at least well-behaved as strings
108 (such as numbers, or object references which overload stringification
109 in a suitable manner).
110 %counts = count_by { KEYFUNC } @vals
112 Returns a hash of integers, giving the number of times the key function
113 block returned a particular result, for each value in the list.
114 my %count_of_balls = count_by { $_->colour } @balls;
116 Because the values returned by the key function are used as hash keys,
118 they ought to either be strings, or at least well-behaved as strings
119 (such as numbers, or object references which overload stringification
120 in a suitable manner).
121 @vals = zip_by { ITEMFUNC } \@arr0, \@arr1, \@arr2,...
123 Returns a list of each of the values returned by the function block,
124 when invoked with values from across each each of the given ARRAY
125 references. Each value in the returned list will be the result of the
126 function having been invoked with arguments at that position, from
127 across each of the arrays given.
128 my @transposition = zip_by { [ @_ ] } @matrix;
130 my @names = zip_by { "$_[1], $_[0]" } \@firstnames, \@surnames;
132 print zip_by { "$_[0] => $_[1]\n" } [ keys %hash ], [ values %hash ];
134 If some of the arrays are shorter than others, the function will behave
136 as if they had "undef" in the trailing positions. The following two
137 lines are equivalent:
138 zip_by { f(@_) } [ 1, 2, 3 ], [ "a", "b" ]
140 f( 1, "a" ), f( 2, "b" ), f( 3, undef )
141 The item function is called by "map", so if it returns a list, the
143 entire list is included in the result. This can be useful for example,
144 for generating a hash from two separate lists of keys and values
145 my %nums = zip_by { @_ } [qw( one two three )], [ 1, 2, 3 ];
147 # %nums = ( one => 1, two => 2, three => 3 )
148 (A function having this behaviour is sometimes called "zipWith", e.g.
150 in Haskell, but that name would not fit the naming scheme used by this
151 module).
152 @vals = extract_by { SELECTFUNC } @arr
154 Removes elements from the referenced array on which the selection
155 function returns true, and returns a list containing those elements.
156 This function is similar to "grep", except that it modifies the
157 referenced array to remove the selected values from it, leaving only
158 the unselected ones.
159 my @red_balls = extract_by { $_->color eq "red" } @balls;
161 # Now there are no red balls in the @balls array
163 This function modifies a real array, unlike most of the other functions
165 in this module. Because of this, it requires a real array, not just a
166 list.
167 This function is implemented by invoking "splice()" on the array, not
169 by constructing a new list and assigning it. One result of this is that
170 weak references function will not be disturbed.
171 extract_by { !defined $_ } @refs;
173 will leave weak references weakened in the @refs array, whereas
175 @refs = grep { defined $_ } @refs;
177 will strengthen them all again.
179 @vals = weighted_shuffle_by { WEIGHTFUNC } @vals
181 Returns the list of values shuffled into a random order. The
182 randomisation is not uniform, but weighted by the value returned by the
183 "WEIGHTFUNC". The probabilty of each item being returned first will be
184 distributed with the distribution of the weights, and so on recursively
185 for the remaining items.
186 @vals = bundle_by { BLOCKFUNC } $number, @vals
188 Similar to a regular "map" functional, returns a list of the values
189 returned by "BLOCKFUNC". Values from the input list are given to the
190 block function in bundles of $number.
191
193 · XS implementations
194 These functions are currently all written in pure perl. Some at
196 least, may benefit from having XS implementations to speed up their
197 logic.
198 · Merge into List::Util or List::MoreUtils
200 This module shouldn't really exist. The functions should instead be
202 part of one of the existing modules that already contain many list
203 utility functions. Having Yet Another List Utilty Module just
204 worsens the problem.
205 I have attempted to contact the authors of both of the above
207 modules, to no avail; therefore I decided it best to write and
208 release this code here anyway so that it is at least on CPAN. Once
209 there, we can then see how best to merge it into an existing
210 module.
211
213 Paul Evans <leonerd@leonerd.org.uk>
214perl v5.12.3 2011-04-29 List::UtilsBy(3)