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;
+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.45";
 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 pairkeys pairvalues pairfirst pairgrep pairmap
+
+      shuffle 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,68 @@ 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.
+
+=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 +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.
 
+=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 +627,5 @@ Recent additions and current maintenance by
 Paul Evans, <leonerd@leonerd.org.uk>.
 
 =cut
+
+1;