This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Scalar-List-Utils 1.45 from CPAN
[perl5.git] / cpan / Scalar-List-Utils / lib / List / Util.pm
index 75866aa..c256696 100644 (file)
@@ -7,14 +7,15 @@
 package List::Util;
 
 use strict;
 package List::Util;
 
 use strict;
+use warnings;
 require Exporter;
 
 our @ISA        = qw(Exporter);
 our @EXPORT_OK  = qw(
 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
 );
   pairs unpairs pairkeys pairvalues pairmap pairgrep pairfirst
 );
-our $VERSION    = "1.42_02";
+our $VERSION    = "1.45";
 our $XS_VERSION = $VERSION;
 $VERSION    = eval $VERSION;
 
 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] }
 
 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
 
 =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 pairkeys pairvalues pairfirst pairgrep pairmap
+
+      shuffle uniqnum uniqstr
+    );
 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 
@@ -67,7 +72,9 @@ The following set of functions all reduce a list down to a single value.
 
 =cut
 
 
 =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>
 
 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
 
 
   $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.
 
 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
 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:
 
 
     @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;
        ...
     }
 
        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;
        ...
        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.>
 
 
 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
 
 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,68 @@ Returns the values of the input in a random order
 
     @cards = shuffle 0..51      # 0..51 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.
+
+=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
 =cut
 
 =head1 KNOWN BUGS
@@ -501,6 +585,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.
 
 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
 =head1 SUGGESTED ADDITIONS
 
 The following are additions that have been requested, but I have been reluctant
@@ -528,3 +627,5 @@ Recent additions and current maintenance by
 Paul Evans, <leonerd@leonerd.org.uk>.
 
 =cut
 Paul Evans, <leonerd@leonerd.org.uk>.
 
 =cut
+
+1;