File Coverage

blib/lib/List/Util.pm
Criterion Covered Total %
statement 0 12 0.0
branch n/a
condition n/a
subroutine 0 4 0.0
pod n/a
total 0 16 0.0


line stmt bran cond sub pod time code
1             # Copyright (c) 1997-2009 Graham Barr . All rights reserved.
2             # This program is free software; you can redistribute it and/or
3             # modify it under the same terms as Perl itself.
4             #
5             # Maintained since 2013 by Paul Evans
6              
7             package List::Util;
8              
9             use strict;
10             use warnings;
11             require Exporter;
12              
13             our @ISA = qw(Exporter);
14             our @EXPORT_OK = qw(
15             all any first min max minstr maxstr none notall product reduce reductions sum sum0
16             sample shuffle uniq uniqint uniqnum uniqstr zip zip_longest zip_shortest mesh mesh_longest mesh_shortest
17             head tail pairs unpairs pairkeys pairvalues pairmap pairgrep pairfirst
18             );
19             our $VERSION = "1.62";
20             our $XS_VERSION = $VERSION;
21             $VERSION =~ tr/_//d;
22              
23             require XSLoader;
24             XSLoader::load('List::Util', $XS_VERSION);
25              
26             # Used by shuffle()
27             our $RAND;
28              
29             sub import
30             {
31 0     0     my $pkg = caller;
32              
33             # (RT88848) Touch the caller's $a and $b, to avoid the warning of
34             # Name "main::a" used only once: possible typo" warning
35             no strict 'refs';
36 0           ${"${pkg}::a"} = ${"${pkg}::a"};
  0            
  0            
37 0           ${"${pkg}::b"} = ${"${pkg}::b"};
  0            
  0            
38              
39 0           goto &Exporter::import;
40             }
41              
42             # For objects returned by pairs()
43 0     0     sub List::Util::_Pair::key { shift->[0] }
44 0     0     sub List::Util::_Pair::value { shift->[1] }
45 0     0     sub List::Util::_Pair::TO_JSON { [ @{+shift} ] }
  0            
46              
47             =head1 NAME
48              
49             List::Util - A selection of general-utility list subroutines
50              
51             =head1 SYNOPSIS
52              
53             use List::Util qw(
54             reduce any all none notall first reductions
55              
56             max maxstr min minstr product sum sum0
57              
58             pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap
59              
60             shuffle uniq uniqint uniqnum uniqstr zip mesh
61             );
62              
63             =head1 DESCRIPTION
64              
65             C contains a selection of subroutines that people have expressed
66             would be nice to have in the perl core, but the usage would not really be high
67             enough to warrant the use of a keyword, and the size so small such that being
68             individual extensions would be wasteful.
69              
70             By default C does not export any subroutines.
71              
72             =cut
73              
74             =head1 LIST-REDUCTION FUNCTIONS
75              
76             The following set of functions all apply a given block of code to a list of
77             values.
78              
79             =cut
80              
81             =head2 reduce
82              
83             $result = reduce { BLOCK } @list
84              
85             Reduces C<@list> by calling C in a scalar context multiple times,
86             setting C<$a> and C<$b> each time. The first call will be with C<$a> and C<$b>
87             set to the first two elements of the list, subsequent calls will be done by
88             setting C<$a> to the result of the previous call and C<$b> to the next element
89             in the list.
90              
91             Returns the result of the last call to the C. If C<@list> is empty then
92             C is returned. If C<@list> only contains one element then that element
93             is returned and C is not executed.
94              
95             The following examples all demonstrate how C could be used to implement
96             the other list-reduction functions in this module. (They are not in fact
97             implemented like this, but instead in a more efficient manner in individual C
98             functions).
99              
100             $foo = reduce { defined($a) ? $a :
101             $code->(local $_ = $b) ? $b :
102             undef } undef, @list # first
103              
104             $foo = reduce { $a > $b ? $a : $b } 1..10 # max
105             $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z' # maxstr
106             $foo = reduce { $a < $b ? $a : $b } 1..10 # min
107             $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
108             $foo = reduce { $a + $b } 1 .. 10 # sum
109             $foo = reduce { $a . $b } @bar # concat
110              
111             $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar # any
112             $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar # all
113             $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar # none
114             $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar # notall
115             # Note that these implementations do not fully short-circuit
116              
117             If your algorithm requires that C produce an identity value, then make
118             sure that you always pass that identity value as the first argument to prevent
119             C being returned
120              
121             $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value
122              
123             The above example code blocks also suggest how to use C to build a
124             more efficient combined version of one of these basic functions and a C
125             block. For example, to find the total length of all the strings in a list,
126             we could use
127              
128             $total = sum map { length } @strings;
129              
130             However, this produces a list of temporary integer values as long as the
131             original list of strings, only to reduce it down to a single value again. We
132             can compute the same result more efficiently by using C with a code
133             block that accumulates lengths by writing this instead as:
134              
135             $total = reduce { $a + length $b } 0, @strings
136              
137             The other scalar-returning list reduction functions are all specialisations of
138             this generic idea.
139              
140             =head2 reductions
141              
142             @results = reductions { BLOCK } @list
143              
144             I
145              
146             Similar to C except that it also returns the intermediate values along
147             with the final result. As before, C<$a> is set to the first element of the
148             given list, and the C is then called once for remaining item in the
149             list set into C<$b>, with the result being captured for return as well as
150             becoming the new value for C<$a>.
151              
152             The returned list will begin with the initial value for C<$a>, followed by
153             each return value from the block in order. The final value of the result will
154             be identical to what the C function would have returned given the same
155             block and list.
156              
157             reduce { "$a-$b" } "a".."d" # "a-b-c-d"
158             reductions { "$a-$b" } "a".."d" # "a", "a-b", "a-b-c", "a-b-c-d"
159              
160             =head2 any
161              
162             my $bool = any { BLOCK } @list;
163              
164             I
165              
166             Similar to C in that it evaluates C setting C<$_> to each element
167             of C<@list> in turn. C returns true if any element makes the C
168             return a true value. If C never returns true or C<@list> was empty then
169             it returns false.
170              
171             Many cases of using C in a conditional can be written using C
172             instead, as it can short-circuit after the first true result.
173              
174             if( any { length > 10 } @strings ) {
175             # at least one string has more than 10 characters
176             }
177              
178             Note: Due to XS issues the block passed may be able to access the outer @_
179             directly. This is not intentional and will break under debugger.
180              
181             =head2 all
182              
183             my $bool = all { BLOCK } @list;
184              
185             I
186              
187             Similar to L, except that it requires all elements of the C<@list> to
188             make the C return true. If any element returns false, then it returns
189             false. If the C never returns false or the C<@list> was empty then it
190             returns true.
191              
192             Note: Due to XS issues the block passed may be able to access the outer @_
193             directly. This is not intentional and will break under debugger.
194              
195             =head2 none
196              
197             =head2 notall
198              
199             my $bool = none { BLOCK } @list;
200              
201             my $bool = notall { BLOCK } @list;
202              
203             I
204              
205             Similar to L and L, but with the return sense inverted. C
206             returns true only if no value in the C<@list> causes the C to return
207             true, and C returns true only if not all of the values do.
208              
209             Note: Due to XS issues the block passed may be able to access the outer @_
210             directly. This is not intentional and will break under debugger.
211              
212             =head2 first
213              
214             my $val = first { BLOCK } @list;
215              
216             Similar to C in that it evaluates C setting C<$_> to each element
217             of C<@list> in turn. C returns the first element where the result from
218             C is a true value. If C never returns true or C<@list> was empty
219             then C is returned.
220              
221             $foo = first { defined($_) } @list # first defined value in @list
222             $foo = first { $_ > $value } @list # first value in @list which
223             # is greater than $value
224              
225             =head2 max
226              
227             my $num = max @list;
228              
229             Returns the entry in the list with the highest numerical value. If the list is
230             empty then C is returned.
231              
232             $foo = max 1..10 # 10
233             $foo = max 3,9,12 # 12
234             $foo = max @bar, @baz # whatever
235              
236             =head2 maxstr
237              
238             my $str = maxstr @list;
239              
240             Similar to L, but treats all the entries in the list as strings and
241             returns the highest string as defined by the C operator. If the list is
242             empty then C is returned.
243              
244             $foo = maxstr 'A'..'Z' # 'Z'
245             $foo = maxstr "hello","world" # "world"
246             $foo = maxstr @bar, @baz # whatever
247              
248             =head2 min
249              
250             my $num = min @list;
251              
252             Similar to L but returns the entry in the list with the lowest numerical
253             value. If the list is empty then C is returned.
254              
255             $foo = min 1..10 # 1
256             $foo = min 3,9,12 # 3
257             $foo = min @bar, @baz # whatever
258              
259             =head2 minstr
260              
261             my $str = minstr @list;
262              
263             Similar to L, but treats all the entries in the list as strings and
264             returns the lowest string as defined by the C operator. If the list is
265             empty then C is returned.
266              
267             $foo = minstr 'A'..'Z' # 'A'
268             $foo = minstr "hello","world" # "hello"
269             $foo = minstr @bar, @baz # whatever
270              
271             =head2 product
272              
273             my $num = product @list;
274              
275             I
276              
277             Returns the numerical product of all the elements in C<@list>. If C<@list> is
278             empty then C<1> is returned.
279              
280             $foo = product 1..10 # 3628800
281             $foo = product 3,9,12 # 324
282              
283             =head2 sum
284              
285             my $num_or_undef = sum @list;
286              
287             Returns the numerical sum of all the elements in C<@list>. For backwards
288             compatibility, if C<@list> is empty then C is returned.
289              
290             $foo = sum 1..10 # 55
291             $foo = sum 3,9,12 # 24
292             $foo = sum @bar, @baz # whatever
293              
294             =head2 sum0
295              
296             my $num = sum0 @list;
297              
298             I
299              
300             Similar to L, except this returns 0 when given an empty list, rather
301             than C.
302              
303             =cut
304              
305             =head1 KEY/VALUE PAIR LIST FUNCTIONS
306              
307             The following set of functions, all inspired by L, consume an
308             even-sized list of pairs. The pairs may be key/value associations from a hash,
309             or just a list of values. The functions will all preserve the original ordering
310             of the pairs, and will not be confused by multiple pairs having the same "key"
311             value - nor even do they require that the first of each pair be a plain string.
312              
313             B: At the time of writing, the following C functions that take a
314             block do not modify the value of C<$_> within the block, and instead operate
315             using the C<$a> and C<$b> globals instead. This has turned out to be a poor
316             design, as it precludes the ability to provide a C function. Better
317             would be to pass pair-like objects as 2-element array references in C<$_>, in
318             a style similar to the return value of the C function. At some future
319             version this behaviour may be added.
320              
321             Until then, users are alerted B to rely on the value of C<$_> remaining
322             unmodified between the outside and the inside of the control block. In
323             particular, the following example is B:
324              
325             my @kvlist = ...
326              
327             foreach (qw( some keys here )) {
328             my @items = pairgrep { $a eq $_ } @kvlist;
329             ...
330             }
331              
332             Instead, write this using a lexical variable:
333              
334             foreach my $key (qw( some keys here )) {
335             my @items = pairgrep { $a eq $key } @kvlist;
336             ...
337             }
338              
339             =cut
340              
341             =head2 pairs
342              
343             my @pairs = pairs @kvlist;
344              
345             I
346              
347             A convenient shortcut to operating on even-sized lists of pairs, this function
348             returns a list of C references, each containing two items from the
349             given list. It is a more efficient version of
350              
351             @pairs = pairmap { [ $a, $b ] } @kvlist
352              
353             It is most convenient to use in a C loop, for example:
354              
355             foreach my $pair ( pairs @kvlist ) {
356             my ( $key, $value ) = @$pair;
357             ...
358             }
359              
360             Since version C<1.39> these C references are blessed objects,
361             recognising the two methods C and C. The following code is
362             equivalent:
363              
364             foreach my $pair ( pairs @kvlist ) {
365             my $key = $pair->key;
366             my $value = $pair->value;
367             ...
368             }
369              
370             Since version C<1.51> they also have a C method to ease
371             serialisation.
372              
373             =head2 unpairs
374              
375             my @kvlist = unpairs @pairs
376              
377             I
378              
379             The inverse function to C; this function takes a list of C
380             references containing two elements each, and returns a flattened list of the
381             two values from each of the pairs, in order. This is notionally equivalent to
382              
383             my @kvlist = map { @{$_}[0,1] } @pairs
384              
385             except that it is implemented more efficiently internally. Specifically, for
386             any input item it will extract exactly two values for the output list; using
387             C if the input array references are short.
388              
389             Between C and C, a higher-order list function can be used to
390             operate on the pairs as single scalars; such as the following near-equivalents
391             of the other C higher-order functions:
392              
393             @kvlist = unpairs grep { FUNC } pairs @kvlist
394             # Like pairgrep, but takes $_ instead of $a and $b
395              
396             @kvlist = unpairs map { FUNC } pairs @kvlist
397             # Like pairmap, but takes $_ instead of $a and $b
398              
399             Note however that these versions will not behave as nicely in scalar context.
400              
401             Finally, this technique can be used to implement a sort on a keyvalue pair
402             list; e.g.:
403              
404             @kvlist = unpairs sort { $a->key cmp $b->key } pairs @kvlist
405              
406             =head2 pairkeys
407              
408             my @keys = pairkeys @kvlist;
409              
410             I
411              
412             A convenient shortcut to operating on even-sized lists of pairs, this function
413             returns a list of the the first values of each of the pairs in the given list.
414             It is a more efficient version of
415              
416             @keys = pairmap { $a } @kvlist
417              
418             =head2 pairvalues
419              
420             my @values = pairvalues @kvlist;
421              
422             I
423              
424             A convenient shortcut to operating on even-sized lists of pairs, this function
425             returns a list of the the second values of each of the pairs in the given list.
426             It is a more efficient version of
427              
428             @values = pairmap { $b } @kvlist
429              
430             =head2 pairgrep
431              
432             my @kvlist = pairgrep { BLOCK } @kvlist;
433              
434             my $count = pairgrep { BLOCK } @kvlist;
435              
436             I
437              
438             Similar to perl's C keyword, but interprets the given list as an
439             even-sized list of pairs. It invokes the C multiple times, in scalar
440             context, with C<$a> and C<$b> set to successive pairs of values from the
441             C<@kvlist>.
442              
443             Returns an even-sized list of those pairs for which the C returned true
444             in list context, or the count of the B in scalar context.
445             (Note, therefore, in scalar context that it returns a number half the size of
446             the count of items it would have returned in list context).
447              
448             @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
449              
450             As with C aliasing C<$_> to list elements, C aliases C<$a> and
451             C<$b> to elements of the given list. Any modifications of it by the code block
452             will be visible to the caller.
453              
454             =head2 pairfirst
455              
456             my ( $key, $val ) = pairfirst { BLOCK } @kvlist;
457              
458             my $found = pairfirst { BLOCK } @kvlist;
459              
460             I
461              
462             Similar to the L function, but interprets the given list as an
463             even-sized list of pairs. It invokes the C multiple times, in scalar
464             context, with C<$a> and C<$b> set to successive pairs of values from the
465             C<@kvlist>.
466              
467             Returns the first pair of values from the list for which the C returned
468             true in list context, or an empty list of no such pair was found. In scalar
469             context it returns a simple boolean value, rather than either the key or the
470             value found.
471              
472             ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
473              
474             As with C aliasing C<$_> to list elements, C aliases C<$a> and
475             C<$b> to elements of the given list. Any modifications of it by the code block
476             will be visible to the caller.
477              
478             =head2 pairmap
479              
480             my @list = pairmap { BLOCK } @kvlist;
481              
482             my $count = pairmap { BLOCK } @kvlist;
483              
484             I
485              
486             Similar to perl's C keyword, but interprets the given list as an
487             even-sized list of pairs. It invokes the C multiple times, in list
488             context, with C<$a> and C<$b> set to successive pairs of values from the
489             C<@kvlist>.
490              
491             Returns the concatenation of all the values returned by the C in list
492             context, or the count of the number of items that would have been returned in
493             scalar context.
494              
495             @result = pairmap { "The key $a has value $b" } @kvlist
496              
497             As with C aliasing C<$_> to list elements, C aliases C<$a> and
498             C<$b> to elements of the given list. Any modifications of it by the code block
499             will be visible to the caller.
500              
501             See L for a known-bug with C, and a workaround.
502              
503             =cut
504              
505             =head1 OTHER FUNCTIONS
506              
507             =cut
508              
509             =head2 shuffle
510              
511             my @values = shuffle @values;
512              
513             Returns the values of the input in a random order
514              
515             @cards = shuffle 0..51 # 0..51 in a random order
516              
517             This function is affected by the C<$RAND> variable.
518              
519             =cut
520              
521             =head2 sample
522              
523             my @items = sample $count, @values
524              
525             I
526              
527             Randomly select the given number of elements from the input list. Any given
528             position in the input list will be selected at most once.
529              
530             If there are fewer than C<$count> items in the list then the function will
531             return once all of them have been randomly selected; effectively the function
532             behaves similarly to L.
533              
534             This function is affected by the C<$RAND> variable.
535              
536             =head2 uniq
537              
538             my @subset = uniq @values
539              
540             I
541              
542             Filters a list of values to remove subsequent duplicates, as judged by a
543             DWIM-ish string equality or C test. Preserves the order of unique
544             elements, and retains the first value of any duplicate set.
545              
546             my $count = uniq @values
547              
548             In scalar context, returns the number of elements that would have been
549             returned as a list.
550              
551             The C value is treated by this function as distinct from the empty
552             string, and no warning will be produced. It is left as-is in the returned
553             list. Subsequent C values are still considered identical to the first,
554             and will be removed.
555              
556             =head2 uniqint
557              
558             my @subset = uniqint @values
559              
560             I
561              
562             Filters a list of values to remove subsequent duplicates, as judged by an
563             integer numerical equality test. Preserves the order of unique elements, and
564             retains the first value of any duplicate set. Values in the returned list will
565             be coerced into integers.
566              
567             my $count = uniqint @values
568              
569             In scalar context, returns the number of elements that would have been
570             returned as a list.
571              
572             Note that C is treated much as other numerical operations treat it; it
573             compares equal to zero but additionally produces a warning if such warnings
574             are enabled (C). In addition, an C in
575             the returned list is coerced into a numerical zero, so that the entire list of
576             values returned by C are well-behaved as integers.
577              
578             =head2 uniqnum
579              
580             my @subset = uniqnum @values
581              
582             I
583              
584             Filters a list of values to remove subsequent duplicates, as judged by a
585             numerical equality test. Preserves the order of unique elements, and retains
586             the first value of any duplicate set.
587              
588             my $count = uniqnum @values
589              
590             In scalar context, returns the number of elements that would have been
591             returned as a list.
592              
593             Note that C is treated much as other numerical operations treat it; it
594             compares equal to zero but additionally produces a warning if such warnings
595             are enabled (C). In addition, an C in
596             the returned list is coerced into a numerical zero, so that the entire list of
597             values returned by C are well-behaved as numbers.
598              
599             Note also that multiple IEEE C values are treated as duplicates of
600             each other, regardless of any differences in their payloads, and despite
601             the fact that C<< 0+'NaN' == 0+'NaN' >> yields false.
602              
603             =head2 uniqstr
604              
605             my @subset = uniqstr @values
606              
607             I
608              
609             Filters a list of values to remove subsequent duplicates, as judged by a
610             string equality test. Preserves the order of unique elements, and retains the
611             first value of any duplicate set.
612              
613             my $count = uniqstr @values
614              
615             In scalar context, returns the number of elements that would have been
616             returned as a list.
617              
618             Note that C is treated much as other string operations treat it; it
619             compares equal to the empty string but additionally produces a warning if such
620             warnings are enabled (C). In addition, an
621             C in the returned list is coerced into an empty string, so that the
622             entire list of values returned by C are well-behaved as strings.
623              
624             =cut
625              
626             =head2 head
627              
628             my @values = head $size, @list;
629              
630             I
631              
632             Returns the first C<$size> elements from C<@list>. If C<$size> is negative, returns
633             all but the last C<$size> elements from C<@list>.
634              
635             @result = head 2, qw( foo bar baz );
636             # foo, bar
637              
638             @result = head -2, qw( foo bar baz );
639             # foo
640              
641             =head2 tail
642              
643             my @values = tail $size, @list;
644              
645             I
646              
647             Returns the last C<$size> elements from C<@list>. If C<$size> is negative, returns
648             all but the first C<$size> elements from C<@list>.
649              
650             @result = tail 2, qw( foo bar baz );
651             # bar, baz
652              
653             @result = tail -2, qw( foo bar baz );
654             # baz
655              
656             =head2 zip
657              
658             my @result = zip [1..3], ['a'..'c'];
659             # [1, 'a'], [2, 'b'], [3, 'c']
660              
661             I
662              
663             Returns a list of array references, composed of elements from the given list
664             of array references. Each array in the returned list is composed of elements
665             at that corresponding position from each of the given input arrays. If any
666             input arrays run out of elements before others, then C will be inserted
667             into the result to fill in the gaps.
668              
669             The C function is particularly handy for iterating over multiple arrays
670             at the same time with a C loop, taking one element from each:
671              
672             foreach ( zip \@xs, \@ys, \@zs ) {
673             my ($x, $y, $z) = @$_;
674             ...
675             }
676              
677             B to users of L: This function does not behave the same
678             as C, but is actually a non-prototyped equivalent to
679             C. This function does not apply a prototype,
680             so make sure to invoke it with references to arrays.
681              
682             For a function similar to the C function from C, see
683             L.
684              
685             my @result = zip_shortest ...
686              
687             A variation of the function that differs in how it behaves when given input
688             arrays of differing lengths. C will stop as soon as any one of
689             the input arrays run out of elements, discarding any remaining unused values
690             from the others.
691              
692             my @result = zip_longest ...
693              
694             C is an alias to the C function, provided simply to be
695             explicit about that behaviour as compared to C.
696              
697             =head2 mesh
698              
699             my @result = mesh [1..3], ['a'..'c'];
700             # (1, 'a', 2, 'b', 3, 'c')
701              
702             I
703              
704             Returns a list of items collected from elements of the given list of array
705             references. Each section of items in the returned list is composed of elements
706             at the corresponding position from each of the given input arrays. If any
707             input arrays run out of elements before others, then C will be inserted
708             into the result to fill in the gaps.
709              
710             This is similar to L, except that all of the ranges in the result are
711             returned in one long flattened list, instead of being bundled into separate
712             arrays.
713              
714             Because it returns a flat list of items, the C function is particularly
715             useful for building a hash out of two separate arrays of keys and values:
716              
717             my %hash = mesh \@keys, \@values;
718              
719             my $href = { mesh \@keys, \@values };
720              
721             B to users of L: This function is a non-prototyped
722             equivalent to C or C (themselves
723             aliases of each other). This function does not apply a prototype, so make sure
724             to invoke it with references to arrays.
725              
726             my @result = mesh_shortest ...
727              
728             my @result = mesh_longest ...
729              
730             These variations are similar to those of L, in that they differ in
731             behaviour when one of the input lists runs out of elements before the others.
732              
733             =head1 CONFIGURATION VARIABLES
734              
735             =head2 $RAND
736              
737             local $List::Util::RAND = sub { ... };
738              
739             I
740              
741             This package variable is used by code which needs to generate random numbers
742             (such as the L and L functions). If set to a CODE reference
743             it provides an alternative to perl's builtin C function. When a new
744             random number is needed this function will be invoked with no arguments and is
745             expected to return a floating-point value, of which only the fractional part
746             will be used.
747              
748             =head1 KNOWN BUGS
749              
750             =head2 RT #95409
751              
752             L
753              
754             If the block of code given to L contains lexical variables that are
755             captured by a returned closure, and the closure is executed after the block
756             has been re-used for the next iteration, these lexicals will not see the
757             correct values. For example:
758              
759             my @subs = pairmap {
760             my $var = "$a is $b";
761             sub { print "$var\n" };
762             } one => 1, two => 2, three => 3;
763              
764             $_->() for @subs;
765              
766             Will incorrectly print
767              
768             three is 3
769             three is 3
770             three is 3
771              
772             This is due to the performance optimisation of using C for the code
773             block, which means that fresh SVs do not get allocated for each call to the
774             block. Instead, the same SV is re-assigned for each iteration, and all the
775             closures will share the value seen on the final iteration.
776              
777             To work around this bug, surround the code with a second set of braces. This
778             creates an inner block that defeats the C logic, and does get fresh
779             SVs allocated each time:
780              
781             my @subs = pairmap {
782             {
783             my $var = "$a is $b";
784             sub { print "$var\n"; }
785             }
786             } one => 1, two => 2, three => 3;
787              
788             This bug only affects closures that are generated by the block but used
789             afterwards. Lexical variables that are only used during the lifetime of the
790             block's execution will take their individual values for each invocation, as
791             normal.
792              
793             =head2 uniqnum() on oversized bignums
794              
795             Due to the way that C compares numbers, it cannot distinguish
796             differences between bignums (especially bigints) that are too large to fit in
797             the native platform types. For example,
798              
799             my $x = Math::BigInt->new( "1" x 100 );
800             my $y = $x + 1;
801              
802             say for uniqnum( $x, $y );
803              
804             Will print just the value of C<$x>, believing that C<$y> is a numerically-
805             equivalent value. This bug does not affect C, which will correctly
806             observe that the two values stringify to different strings.
807              
808             =head1 SUGGESTED ADDITIONS
809              
810             The following are additions that have been requested, but I have been reluctant
811             to add due to them being very simple to implement in perl
812              
813             # How many elements are true
814              
815             sub true { scalar grep { $_ } @_ }
816              
817             # How many elements are false
818              
819             sub false { scalar grep { !$_ } @_ }
820              
821             =head1 SEE ALSO
822              
823             L, L
824              
825             =head1 COPYRIGHT
826              
827             Copyright (c) 1997-2007 Graham Barr . All rights reserved.
828             This program is free software; you can redistribute it and/or
829             modify it under the same terms as Perl itself.
830              
831             Recent additions and current maintenance by
832             Paul Evans, .
833              
834             =cut
835              
836             1;