"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "cpan/Scalar-List-Utils/lib/List/Util.pm" between
perl-5.32.0-RC0.tar.xz and perl-5.32.0-RC1.tar.xz

About: Perl (Practical Extraction and Report Language) is a high-level, general-purpose, interpreted, dynamic programming language. Release candidate.

Util.pm  (perl-5.32.0-RC0.tar.xz):Util.pm  (perl-5.32.0-RC1.tar.xz)
skipping to change at line 15 skipping to change at line 15
# Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk> # Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk>
package List::Util; package List::Util;
use strict; use strict;
use warnings; use warnings;
require Exporter; require Exporter;
our @ISA = qw(Exporter); our @ISA = qw(Exporter);
our @EXPORT_OK = qw( our @EXPORT_OK = qw(
all any first min max minstr maxstr none notall product reduce sum sum0 shuffl all any first min max minstr maxstr none notall product reduce reductions sum
e uniq uniqnum uniqstr sum0
sample shuffle uniq uniqint uniqnum uniqstr
head tail pairs unpairs pairkeys pairvalues pairmap pairgrep pairfirst head tail pairs unpairs pairkeys pairvalues pairmap pairgrep pairfirst
); );
our $VERSION = "1.53"; our $VERSION = "1.55";
our $XS_VERSION = $VERSION; our $XS_VERSION = $VERSION;
$VERSION =~ tr/_//d; $VERSION =~ tr/_//d;
require XSLoader; require XSLoader;
XSLoader::load('List::Util', $XS_VERSION); XSLoader::load('List::Util', $XS_VERSION);
# Used by shuffle()
our $RAND;
sub import sub import
{ {
my $pkg = caller; my $pkg = caller;
# (RT88848) Touch the caller's $a and $b, to avoid the warning of # (RT88848) Touch the caller's $a and $b, to avoid the warning of
# Name "main::a" used only once: possible typo" warning # Name "main::a" used only once: possible typo" warning
no strict 'refs'; no strict 'refs';
${"${pkg}::a"} = ${"${pkg}::a"}; ${"${pkg}::a"} = ${"${pkg}::a"};
${"${pkg}::b"} = ${"${pkg}::b"}; ${"${pkg}::b"} = ${"${pkg}::b"};
skipping to change at line 50 skipping to change at line 54
sub List::Util::_Pair::value { shift->[1] } sub List::Util::_Pair::value { shift->[1] }
sub List::Util::_Pair::TO_JSON { [ @{+shift} ] } sub List::Util::_Pair::TO_JSON { [ @{+shift} ] }
=head1 NAME =head1 NAME
List::Util - A selection of general-utility list subroutines List::Util - A selection of general-utility list subroutines
=head1 SYNOPSIS =head1 SYNOPSIS
use List::Util qw( use List::Util qw(
reduce any all none notall first reduce any all none notall first reductions
max maxstr min minstr product sum sum0 max maxstr min minstr product sum sum0
pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap
shuffle uniq uniqnum uniqstr shuffle uniq uniqint uniqnum uniqstr
); );
=head1 DESCRIPTION =head1 DESCRIPTION
C<List::Util> contains a selection of subroutines that people have expressed C<List::Util> contains a selection of subroutines that people have expressed
would be nice to have in the perl core, but the usage would not really be high would be nice to have in the perl core, but the usage would not really be high
enough to warrant the use of a keyword, and the size so small such that being enough to warrant the use of a keyword, and the size so small such that being
individual extensions would be wasteful. individual extensions would be wasteful.
By default C<List::Util> does not export any subroutines. By default C<List::Util> does not export any subroutines.
=cut =cut
=head1 LIST-REDUCTION FUNCTIONS =head1 LIST-REDUCTION FUNCTIONS
The following set of functions all reduce a list down to a single value. The following set of functions all apply a given block of code to a list of
values.
=cut =cut
=head2 reduce =head2 reduce
$result = reduce { BLOCK } @list $result = reduce { BLOCK } @list
Reduces C<@list> by calling C<BLOCK> in a scalar context multiple times, 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> setting C<$a> and C<$b> each time. The first call will be with C<$a> and C<$b>
set to the first two elements of the list, subsequent calls will be done by set to the first two elements of the list, subsequent calls will be done by
skipping to change at line 132 skipping to change at line 137
$total = sum map { length } @strings; $total = sum map { length } @strings;
However, this produces a list of temporary integer values as long as the 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 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 can compute the same result more efficiently by using C<reduce> with a code
block that accumulates lengths by writing this instead as: block that accumulates lengths by writing this instead as:
$total = reduce { $a + length $b } 0, @strings $total = reduce { $a + length $b } 0, @strings
The remaining list-reduction functions are all specialisations of this generic The other scalar-returning list reduction functions are all specialisations of
idea. this generic idea.
=head2 reductions
@results = reductions { BLOCK } @list
I<Since version 1.54.>
Similar to C<reduce> except that it also returns the intermediate values along
with the final result. As before, C<$a> is set to the first element of the
given list, and the C<BLOCK> is then called once for remaining item in the
list set into C<$b>, with the result being captured for return as well as
becoming the new value for C<$a>.
The returned list will begin with the initial value for C<$a>, followed by
each return value from the block in order. The final value of the result will
be identical to what the C<reduce> function would have returned given the same
block and list.
reduce { "$a-$b" } "a".."d" # "a-b-c-d"
reductions { "$a-$b" } "a".."d" # "a", "a-b", "a-b-c", "a-b-c-d"
=head2 any =head2 any
my $bool = any { BLOCK } @list; my $bool = any { BLOCK } @list;
I<Since version 1.33.> I<Since version 1.33.>
Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element
of C<@list> in turn. C<any> returns true if any element makes the C<BLOCK> of C<@list> in turn. C<any> returns true if any element makes the C<BLOCK>
return a true value. If C<BLOCK> never returns true or C<@list> was empty then return a true value. If C<BLOCK> never returns true or C<@list> was empty then
skipping to change at line 492 skipping to change at line 517
=cut =cut
=head2 shuffle =head2 shuffle
my @values = shuffle @values; my @values = shuffle @values;
Returns the values of the input in a random order 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
This function is affected by the C<$RAND> variable.
=cut
=head2 sample
my @items = sample $count, @values
I<Since version 1.54.>
Randomly select the given number of elements from the input list. Any given
position in the input list will be selected at most once.
If there are fewer than C<$count> items in the list then the function will
return once all of them have been randomly selected; effectively the function
behaves similarly to L</shuffle>.
This function is affected by the C<$RAND> variable.
=head2 uniq =head2 uniq
my @subset = uniq @values my @subset = uniq @values
I<Since version 1.45.> I<Since version 1.45.>
Filters a list of values to remove subsequent duplicates, as judged by a 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 DWIM-ish string equality or C<undef> test. Preserves the order of unique
elements, and retains the first value of any duplicate set. elements, and retains the first value of any duplicate set.
my $count = uniq @values my $count = uniq @values
In scalar context, returns the number of elements that would have been In scalar context, returns the number of elements that would have been
returned as a list. returned as a list.
The C<undef> value is treated by this function as distinct from the empty 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 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, list. Subsequent C<undef> values are still considered identical to the first,
and will be removed. and will be removed.
=head2 uniqint
my @subset = uniqint @values
I<Since version 1.55.>
Filters a list of values to remove subsequent duplicates, as judged by an
integer numerical equality test. Preserves the order of unique elements, and
retains the first value of any duplicate set. Values in the returned list will
be coerced into integers.
my $count = uniqint @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<uniqint> are well-behaved as integers.
=head2 uniqnum =head2 uniqnum
my @subset = uniqnum @values my @subset = uniqnum @values
I<Since version 1.44.> I<Since version 1.44.>
Filters a list of values to remove subsequent duplicates, as judged by a Filters a list of values to remove subsequent duplicates, as judged by a
numerical equality test. Preserves the order of unique elements, and retains numerical equality test. Preserves the order of unique elements, and retains
the first value of any duplicate set. the first value of any duplicate set.
skipping to change at line 590 skipping to change at line 656
Returns the last C<$size> elements from C<@list>. If C<$size> is negative, retur ns Returns the last C<$size> elements from C<@list>. If C<$size> is negative, retur ns
all but the first C<$size> elements from C<@list>. all but the first C<$size> elements from C<@list>.
@result = tail 2, qw( foo bar baz ); @result = tail 2, qw( foo bar baz );
# bar, baz # bar, baz
@result = tail -2, qw( foo bar baz ); @result = tail -2, qw( foo bar baz );
# baz # baz
=head1 CONFIGURATION VARIABLES
=head2 $RAND
local $List::Util::RAND = sub { ... };
I<Since version 1.54.>
This package variable is used by code which needs to generate random numbers
(such as the L</shuffle> and L</sample> functions). If set to a CODE reference
it provides an alternative to perl's builtin C<rand()> function. When a new
random number is needed this function will be invoked with no arguments and is
expected to return a floating-point value, of which only the fractional part
will be used.
=head1 KNOWN BUGS =head1 KNOWN BUGS
=head2 RT #95409 =head2 RT #95409
L<https://rt.cpan.org/Ticket/Display.html?id=95409> L<https://rt.cpan.org/Ticket/Display.html?id=95409>
If the block of code given to L</pairmap> contains lexical variables that are If the block of code given to L</pairmap> contains lexical variables that are
captured by a returned closure, and the closure is executed after the block captured by a returned closure, and the closure is executed after the block
has been re-used for the next iteration, these lexicals will not see the has been re-used for the next iteration, these lexicals will not see the
correct values. For example: correct values. For example:
 End of changes. 10 change blocks. 
8 lines changed or deleted 89 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)