diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/List')
-rw-r--r-- | Master/tlpkg/tlperl/lib/List/Util.pm | 135 | ||||
-rw-r--r-- | Master/tlpkg/tlperl/lib/List/Util/XS.pm | 3 |
2 files changed, 122 insertions, 16 deletions
diff --git a/Master/tlpkg/tlperl/lib/List/Util.pm b/Master/tlpkg/tlperl/lib/List/Util.pm index 75866aa6c6b..23473fc627b 100644 --- a/Master/tlpkg/tlperl/lib/List/Util.pm +++ b/Master/tlpkg/tlperl/lib/List/Util.pm @@ -7,14 +7,15 @@ package List::Util; use strict; +use warnings; require Exporter; our @ISA = qw(Exporter); our @EXPORT_OK = qw( - all any first min max minstr maxstr none notall product reduce sum sum0 shuffle + all any first min max minstr maxstr none notall product reduce sum sum0 shuffle uniq uniqnum uniqstr pairs unpairs pairkeys pairvalues pairmap pairgrep pairfirst ); -our $VERSION = "1.42_02"; +our $VERSION = "1.46_02"; our $XS_VERSION = $VERSION; $VERSION = eval $VERSION; @@ -38,17 +39,21 @@ sub import sub List::Util::_Pair::key { shift->[0] } sub List::Util::_Pair::value { shift->[1] } -1; - -__END__ - =head1 NAME List::Util - A selection of general-utility list subroutines =head1 SYNOPSIS - use List::Util qw(first max maxstr min minstr reduce shuffle sum); + use List::Util qw( + reduce any all none notall first + + max maxstr min minstr product sum sum0 + + pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap + + shuffle uniq uniqnum uniqstr + ); =head1 DESCRIPTION @@ -67,7 +72,9 @@ The following set of functions all reduce a list down to a single value. =cut -=head2 $result = reduce { BLOCK } @list +=head2 reduce + + $result = reduce { BLOCK } @list Reduces C<@list> by calling C<BLOCK> in a scalar context multiple times, setting C<$a> and C<$b> each time. The first call will be with C<$a> and C<$b> @@ -107,6 +114,20 @@ C<undef> being returned $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value +The above example code blocks also suggest how to use C<reduce> to build a +more efficient combined version of one of these basic functions and a C<map> +block. For example, to find the total length of the all the strings in a list, +we could use + + $total = sum map { length } @strings; + +However, this produces a list of temporary integer values as long as the +original list of strings, only to reduce it down to a single value again. We +can compute the same result more efficiently by using C<reduce> with a code +block that accumulates lengths by writing this instead as: + + $total = reduce { $a + length $b } 0, @strings + The remaining list-reduction functions are all specialisations of this generic idea. @@ -289,22 +310,23 @@ Instead, write this using a lexical variable: I<Since version 1.29.> A convenient shortcut to operating on even-sized lists of pairs, this function -returns a list of ARRAY references, each containing two items from the given -list. It is a more efficient version of +returns a list of C<ARRAY> references, each containing two items from the +given list. It is a more efficient version of @pairs = pairmap { [ $a, $b ] } @kvlist It is most convenient to use in a C<foreach> loop, for example: - foreach my $pair ( pairs @KVLIST ) { + foreach my $pair ( pairs @kvlist ) { my ( $key, $value ) = @$pair; ... } -Since version C<1.39> these ARRAY references are blessed objects, recognising -the two methods C<key> and C<value>. The following code is equivalent: +Since version C<1.39> these C<ARRAY> references are blessed objects, +recognising the two methods C<key> and C<value>. The following code is +equivalent: - foreach my $pair ( pairs @KVLIST ) { + foreach my $pair ( pairs @kvlist ) { my $key = $pair->key; my $value = $pair->value; ... @@ -316,7 +338,7 @@ the two methods C<key> and C<value>. The following code is equivalent: I<Since version 1.42.> -The inverse function to C<pairs>; this function takes a list of ARRAY +The inverse function to C<pairs>; this function takes a list of C<ARRAY> references containing two elements each, and returns a flattened list of the two values from each of the pairs, in order. This is notionally equivalent to @@ -454,6 +476,72 @@ Returns the values of the input in a random order @cards = shuffle 0..51 # 0..51 in a random order +=head2 uniq + + my @subset = uniq @values + +I<Since version 1.45.> + +Filters a list of values to remove subsequent duplicates, as judged by a +DWIM-ish string equality or C<undef> test. Preserves the order of unique +elements, and retains the first value of any duplicate set. + + my $count = uniq @values + +In scalar context, returns the number of elements that would have been +returned as a list. + +The C<undef> value is treated by this function as distinct from the empty +string, and no warning will be produced. It is left as-is in the returned +list. Subsequent C<undef> values are still considered identical to the first, +and will be removed. + +=head2 uniqnum + + my @subset = uniqnum @values + +I<Since version 1.44.> + +Filters a list of values to remove subsequent duplicates, as judged by a +numerical equality test. Preserves the order of unique elements, and retains +the first value of any duplicate set. + + my $count = uniqnum @values + +In scalar context, returns the number of elements that would have been +returned as a list. + +Note that C<undef> is treated much as other numerical operations treat it; it +compares equal to zero but additionally produces a warning if such warnings +are enabled (C<use warnings 'uninitialized';>). In addition, an C<undef> in +the returned list is coerced into a numerical zero, so that the entire list of +values returned by C<uniqnum> are well-behaved as numbers. + +Note also that multiple IEEE C<NaN> values are treated as duplicates of +each other, regardless of any differences in their payloads, and despite +the fact that C<< 0+'NaN' == 0+'NaN' >> yields false. + +=head2 uniqstr + + my @subset = uniqstr @values + +I<Since version 1.45.> + +Filters a list of values to remove subsequent duplicates, as judged by a +string equality test. Preserves the order of unique elements, and retains the +first value of any duplicate set. + + my $count = uniqstr @values + +In scalar context, returns the number of elements that would have been +returned as a list. + +Note that C<undef> is treated much as other string operations treat it; it +compares equal to the empty string but additionally produces a warning if such +warnings are enabled (C<use warnings 'uninitialized';>). In addition, an +C<undef> in the returned list is coerced into an empty string, so that the +entire list of values returned by C<uniqstr> are well-behaved as strings. + =cut =head1 KNOWN BUGS @@ -501,6 +589,21 @@ afterwards. Lexical variables that are only used during the lifetime of the block's execution will take their individual values for each invocation, as normal. +=head2 uniqnum() on oversized bignums + +Due to the way that C<uniqnum()> compares numbers, it cannot distinguish +differences between bignums (especially bigints) that are too large to fit in +the native platform types. For example, + + my $x = Math::BigInt->new( "1" x 100 ); + my $y = $x + 1; + + say for uniqnum( $x, $y ); + +Will print just the value of C<$x>, believing that C<$y> is a numerically- +equivalent value. This bug does not affect C<uniqstr()>, which will correctly +observe that the two values stringify to different strings. + =head1 SUGGESTED ADDITIONS The following are additions that have been requested, but I have been reluctant @@ -528,3 +631,5 @@ Recent additions and current maintenance by Paul Evans, <leonerd@leonerd.org.uk>. =cut + +1; diff --git a/Master/tlpkg/tlperl/lib/List/Util/XS.pm b/Master/tlpkg/tlperl/lib/List/Util/XS.pm index fca0738e5a7..783499c35f6 100644 --- a/Master/tlpkg/tlperl/lib/List/Util/XS.pm +++ b/Master/tlpkg/tlperl/lib/List/Util/XS.pm @@ -1,8 +1,9 @@ package List::Util::XS; use strict; +use warnings; use List::Util; -our $VERSION = "1.42_02"; # FIXUP +our $VERSION = "1.46_02"; # FIXUP $VERSION = eval $VERSION; # FIXUP 1; |