1List::Pairwise(3)     User Contributed Perl Documentation    List::Pairwise(3)
2
3
4

NAME

6       List::Pairwise - map/grep arrays and hashes pairwise
7

SYNOPSIS

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

DESCRIPTION

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

EXPORTS

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

CAVEATS

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

TEST COVERAGE

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

SEE ALSO

236       List::Util, List::MoreUtils, "grep", "map"
237

ACKNOWLEDGMENT

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

AUTHOR

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.36.0                      2022-07-22                 List::Pairwise(3)
Impressum