1List::Pairwise(3) User Contributed Perl Documentation List::Pairwise(3)
2
3
4
6 List::Pairwise - map/grep arrays and hashes pairwise
7
9 use List::Pairwise qw(mapp grepp);
10
11 my %hash = (
12 foo => 4,
13 bar => 2,
14 baz => 6,
15 );
16
17 my @list = %hash;
18
19 # increment values in-place
20 mapp {++$b} %hash;
21
22 # copy with modifications on keys
23 %hash = mapp {lc($a) => $b} %hash
24
25 # iterate pairwise
26 mapp {
27 print "$a: $b\n"
28 } %hash;
29
30 # reverse array pairs in-place
31 mapp { ($a, $b) = ($b, $a) } @list;
32
33 # list "keys" and "values"
34 my @keys = mapp {$a} @list;
35 my @values = mapp {$b} @list;
36
37 # 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
46 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
50 New code should now preferably use List::Util functions directly, with
51 the added benefit of relying on a Perl core module.
52
53 /!\ 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
58 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
67 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
71 "mapp" is optimized in void context, and can thus be used to
72 iterate lists pairwise.
73
74 "map_pairwise" is an alias for "mapp".
75
76 keys/values emulation (only slower):
77
78 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
83 copy (only slower):
84
85 my %b = mapp {$a, $b} %hash;
86
87 modify values in-place:
88
89 mapp {$b = lc($b)} %hash;
90 mapp {$b = lc($b)} @list; # same
91
92 modifying hash keys in-place does not work with a hash:
93
94 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
98 modify array "keys" in-place does work:
99
100 mapp {$a = lc($a)} @list;
101
102 modify keys and copy:
103
104 %hash = mapp {lc($a) => $b} %hash;
105 @hash = mapp {lc($a) => $b} @list; # same
106
107 reverse hash (does not work in-place):
108
109 my %reverse_a = mapp {$b, $a} %hash;
110
111 reverse array pairs in-place:
112
113 mapp { ($a, $b) = ($b, $a) } @list;
114
115 each emulation, iterating a list pairwise:
116
117 mapp {
118 print "$a: $b\n";
119 } %hash;
120
121 mapp {
122 print "$a: $b\n";
123 } @list;
124
125 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
133 So this equality stands:
134
135 (grepp BLOCK LIST) == 1/2 * scalar(my @list = (grepp BLOCK LIST))
136
137 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
141 "grep_pairwise" is an alias for "grepp".
142
143 grep hash subset:
144
145 my %subset1 = grepp {$a =~ /^ba/} %hash;
146 my %subset2 = grepp {$b < 5} %hash;
147
148 grep specific values:
149
150 my @values = mapp {$b} grepp {$a =~ /^ba/} %hash;
151
152 This does not work:
153
154 values grepp {$a =~ /^ba/} %hash;
155
156 values() and keys() expect a hash, whereas grepp returns a list
157
158 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
165 "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
169 my $i;
170 firstp {
171 print "$a: $b\n";
172 ++$i==5 # last after 5 iterations
173 } %hash;
174
175 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
182 pair LIST
183 Returns a list of pairs as array references.
184
185 my @pairs = pair @list;
186 my @pairs = mapp {[$a, $b]} @list; # same, but slower
187
188 "pair" can be used in combination with sort, map and grep to do
189 ordered hash-like manipulations in long chains/streams:
190
191 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
201 use List::Pairwise qw(mapp grepp first_pairwise);
202
203 You can use the :all tag to import all functions, including *_pairwise
204 aliases
205
206 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
215 use warnings FATAL => 'misc';
216
218 As of List::Pairwise version 0.28:
219
220 ---------------------------- ------ ------ ------ ------ ------ ------ ------
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
241 · Johan Lodin for the "pair" idea and implementation, as well as
242 numerous other contributions (see changelog)
243
244 · Andreas J. Koenig for his advices on documentation and his insight
245 on how to keep perl 5.10 compatibility
246
247 · Slaven Rezic for discovering the issues that module has with
248 pre-5.6 versions of perl
249
250 · 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
259 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.
262
263
264
265perl v5.28.0 2014-07-07 List::Pairwise(3)