1List::Pairwise(3) User Contributed Perl Documentation List::Pairwise(3)
2
6 List::Pairwise - map/grep arrays and hashes pairwise
7
9 use List::Pairwise qw(mapp grepp);
10 my %hash = (
12 foo => 4,
13 bar => 2,
14 baz => 6,
15 );
16 my @list = %hash;
18 # increment values in-place
20 mapp {++$b} %hash;
21 # copy with modifications on keys
23 %hash = mapp {lc($a) => $b} %hash
24 # iterate pairwise
26 mapp {
27 print "$a: $b\n"
28 } %hash;
29 # reverse array pairs in-place
31 mapp { ($a, $b) = ($b, $a) } @list;
32 # list "keys" and "values"
34 my @keys = mapp {$a} @list;
35 my @values = mapp {$b} @list;
36 # grep hash subset
38 my %subset1 = grepp {$a =~ /^ba/} %hash;
39 my %subset2 = grepp {$b < 5} %hash;
40
42 "List::Pairwise" provides functions to map and grep lists two elements
43 at a time, setting $a and $b to each pair instead of setting $_ to each
44 element.
45 As of version 1.01, List::Pairwise now tries to use the newly
47 implemented XS functions pairmap, pairgrep, pairfirst and pairs from
48 List::Util 1.31 and up, resulting in a major speedup.
49 New code should now preferably use List::Util functions directly, with
51 the added benefit of relying on a Perl core module.
52 /!\ as of version 1.03 List::Pairwise does not use List::Util, because
54 version up to the current one (1.39) presents a strange bug where a key
55 can get undefined after an assignement (see t/listutil.t with paimap
56 instead of mapp) /!\
57 mapp BLOCK LIST
59 map_pairwise BLOCK LIST
60 Evaluates the BLOCK for each pair of LIST (locally setting $a and
61 $b to each pair) and returns the list value composed of the results
62 of each such evaluation. In scalar context, returns the total
63 number of elements so generated (not pairs). Evaluates BLOCK in
64 list context, so each element of LIST may produce zero, one, or
65 more elements in the returned value.
66 Note that $a and $b are aliases to the list elements, so they can
68 be used to modify the elements of the LIST, exept for hash keys ($a
69 when LIST is a hash).
70 "mapp" is optimized in void context, and can thus be used to
72 iterate lists pairwise.
73 "map_pairwise" is an alias for "mapp".
75 keys/values emulation (only slower):
77 my @keys = mapp {$a} %hash;
79 my @keys = mapp {$a} @list; # same
80 my @values = mapp {$b} %hash;
81 my @values = mapp {$b} @list; # same
82 copy (only slower):
84 my %b = mapp {$a, $b} %hash;
86 modify values in-place:
88 mapp {$b = lc($b)} %hash;
90 mapp {$b = lc($b)} @list; # same
91 modifying hash keys in-place does not work with a hash:
93 mapp {$a = lc($a)} %hash; # wrong
95 my %b = mapp {lc($a) => $b} %hash; # ok
96 %hash = mapp {lc($a) => $b} %hash; # also ok (copy)
97 modify array "keys" in-place does work:
99 mapp {$a = lc($a)} @list;
101 modify keys and copy:
103 %hash = mapp {lc($a) => $b} %hash;
105 @hash = mapp {lc($a) => $b} @list; # same
106 reverse hash (does not work in-place):
108 my %reverse_a = mapp {$b, $a} %hash;
110 reverse array pairs in-place:
112 mapp { ($a, $b) = ($b, $a) } @list;
114 each emulation, iterating a list pairwise:
116 mapp {
118 print "$a: $b\n";
119 } %hash;
120 mapp {
122 print "$a: $b\n";
123 } @list;
124 grepp BLOCK LIST
126 grep_pairwise BLOCK LIST
127 Evaluates the BLOCK in scalar context for each pair of LIST
128 (locally setting $a and $b to each pair) and returns the list value
129 consisting of those pairs for which the expression evaluated to
130 true. In scalar context, returns the number of valid pairs, ie the
131 number of times the expression was true.
132 So this equality stands:
134 (grepp BLOCK LIST) == 1/2 * scalar(my @list = (grepp BLOCK LIST))
136 Note that $a and $b are aliases to the list elements, so they can
138 be used to modify the elements of the LIST, exept for hash keys ($a
139 when LIST is a hash).
140 "grep_pairwise" is an alias for "grepp".
142 grep hash subset:
144 my %subset1 = grepp {$a =~ /^ba/} %hash;
146 my %subset2 = grepp {$b < 5} %hash;
147 grep specific values:
149 my @values = mapp {$b} grepp {$a =~ /^ba/} %hash;
151 This does not work:
153 values grepp {$a =~ /^ba/} %hash;
155 values() and keys() expect a hash, whereas grepp returns a list
157 firstp BLOCK LIST
159 first_pairwise BLOCK LIST
160 Evaluates the BLOCK in scalar context for each pair of LIST
161 (locally setting $a and $b to each pair) and returns the first pair
162 for which the expression evaluated to true. In scalar context,
163 returns 1 if a valid pair was found.
164 "firstp" can be used to iterate lists pairwise as does "mapp", but
166 with the additional option of using the value returned by the BLOCK
167 as a "last" statement
168 my $i;
170 firstp {
171 print "$a: $b\n";
172 ++$i==5 # last after 5 iterations
173 } %hash;
174 lastp BLOCK LIST
176 last_pairwise BLOCK LIST
177 Evaluates the BLOCK in scalar context for each pair of LIST
178 (locally setting $a and $b to each pair) and returns the last pair
179 for which the expression evaluated to true. In scalar context,
180 returns 1 if a valid pair was found.
181 pair LIST
183 Returns a list of pairs as array references.
184 my @pairs = pair @list;
186 my @pairs = mapp {[$a, $b]} @list; # same, but slower
187 "pair" can be used in combination with sort, map and grep to do
189 ordered hash-like manipulations in long chains/streams:
190 my @ranges =
192 sort { $a->[0] <=> $b->[0] or $a->[1] <=> $b->[1] }
193 grep { $_->[0] < $_->[1] }
194 pair
195 /\b(\d+)-(\d+)\b/g
196 ;
197
199 Nothing by default. Functions can be imported explicitely
200 use List::Pairwise qw(mapp grepp first_pairwise);
202 You can use the :all tag to import all functions, including *_pairwise
204 aliases
205 use List::Pairwise qw(:all);
207
209 In prior versions, List::Pairwise function did croak when given a list
210 with an odd number of elements. This is not the case anymore: a warning
211 will now be emitted if warnings of the 'misc' category are enabled, and
212 the last pair will be completed with an undefined value. The old
213 behavior can be restored by making these misc warnings FATAL:
214 use warnings FATAL => 'misc';
216
218 As of List::Pairwise version 0.28:
219 ---------------------------- ------ ------ ------ ------ ------ ------ ------
221 File stmt bran cond sub pod time total
222 ---------------------------- ------ ------ ------ ------ ------ ------ ------
223 lib/List/Pairwise.pm 100.0 100.0 100.0 100.0 100.0 88.0 100.0
224 t/01load.t 100.0 n/a n/a 100.0 n/a 0.6 100.0
225 t/context.t 100.0 n/a n/a 100.0 n/a 0.6 100.0
226 t/coverage.pl 100.0 100.0 n/a 100.0 n/a 4.2 100.0
227 t/firstp.t 100.0 n/a n/a 100.0 n/a 1.2 100.0
228 t/grepp.t 100.0 n/a n/a 100.0 n/a 1.2 100.0
229 t/lastp.t 100.0 n/a n/a 100.0 n/a 1.2 100.0
230 t/mapp.t 100.0 n/a n/a 100.0 n/a 1.4 100.0
231 t/pair.t 100.0 n/a n/a 100.0 n/a 1.6 100.0
232 Total 100.0 100.0 100.0 100.0 100.0 100.0 100.0
233 ---------------------------- ------ ------ ------ ------ ------ ------ ------
234
236 List::Util, List::MoreUtils, "grep", "map"
237
239 The author wishes to thank:
240 • Johan Lodin for the "pair" idea and implementation, as well as
242 numerous other contributions (see changelog)
243 • Andreas J. Koenig for his advices on documentation and his insight
245 on how to keep perl 5.10 compatibility
246 • Slaven Rezic for discovering the issues that module has with
248 pre-5.6 versions of perl
249 • Paul "LeoNerd" Evans for having implemented XS versions of these
251 functions in the core module List::Util
252
254 Thomas Drugeon, <tdrugeon@cpan.org>
255
257 Copyright (C) 2006 by Thomas Drugeon
258 This library is free software; you can redistribute it and/or modify it
260 under the same terms as Perl itself, either Perl version 5.8.8 or, at
261 your option, any later version of Perl 5 you may have available.
262perl v5.34.0 2021-07-22 List::Pairwise(3)