diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/List::Util.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/List::Util.3pm | 942 |
1 files changed, 942 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/List::Util.3pm b/upstream/mageia-cauldron/man3pm/List::Util.3pm new file mode 100644 index 00000000..f7b2740e --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/List::Util.3pm @@ -0,0 +1,942 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "List::Util 3pm" +.TH List::Util 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +List::Util \- A selection of general\-utility list subroutines +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 2 +\& use List::Util qw( +\& reduce any all none notall first reductions +\& +\& max maxstr min minstr product sum sum0 +\& +\& pairs unpairs pairkeys pairvalues pairfirst pairgrep pairmap +\& +\& shuffle uniq uniqint uniqnum uniqstr zip mesh +\& ); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\f(CW\*(C`List::Util\*(C'\fR 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 +enough to warrant the use of a keyword, and the size so small such that being +individual extensions would be wasteful. +.PP +By default \f(CW\*(C`List::Util\*(C'\fR does not export any subroutines. +.SH "LIST-REDUCTION FUNCTIONS" +.IX Header "LIST-REDUCTION FUNCTIONS" +The following set of functions all apply a given block of code to a list of +values. +.SS reduce +.IX Subsection "reduce" +.Vb 1 +\& $result = reduce { BLOCK } @list +.Ve +.PP +Reduces \f(CW@list\fR by calling \f(CW\*(C`BLOCK\*(C'\fR in a scalar context multiple times, +setting \f(CW$a\fR and \f(CW$b\fR each time. The first call will be with \f(CW$a\fR and \f(CW$b\fR +set to the first two elements of the list, subsequent calls will be done by +setting \f(CW$a\fR to the result of the previous call and \f(CW$b\fR to the next element +in the list. +.PP +Returns the result of the last call to the \f(CW\*(C`BLOCK\*(C'\fR. If \f(CW@list\fR is empty then +\&\f(CW\*(C`undef\*(C'\fR is returned. If \f(CW@list\fR only contains one element then that element +is returned and \f(CW\*(C`BLOCK\*(C'\fR is not executed. +.PP +The following examples all demonstrate how \f(CW\*(C`reduce\*(C'\fR could be used to implement +the other list-reduction functions in this module. (They are not in fact +implemented like this, but instead in a more efficient manner in individual C +functions). +.PP +.Vb 3 +\& $foo = reduce { defined($a) ? $a : +\& $code\->(local $_ = $b) ? $b : +\& undef } undef, @list # first +\& +\& $foo = reduce { $a > $b ? $a : $b } 1..10 # max +\& $foo = reduce { $a gt $b ? $a : $b } \*(AqA\*(Aq..\*(AqZ\*(Aq # maxstr +\& $foo = reduce { $a < $b ? $a : $b } 1..10 # min +\& $foo = reduce { $a lt $b ? $a : $b } \*(Aqaa\*(Aq..\*(Aqzz\*(Aq # minstr +\& $foo = reduce { $a + $b } 1 .. 10 # sum +\& $foo = reduce { $a . $b } @bar # concat +\& +\& $foo = reduce { $a || $code\->(local $_ = $b) } 0, @bar # any +\& $foo = reduce { $a && $code\->(local $_ = $b) } 1, @bar # all +\& $foo = reduce { $a && !$code\->(local $_ = $b) } 1, @bar # none +\& $foo = reduce { $a || !$code\->(local $_ = $b) } 0, @bar # notall +\& # Note that these implementations do not fully short\-circuit +.Ve +.PP +If your algorithm requires that \f(CW\*(C`reduce\*(C'\fR produce an identity value, then make +sure that you always pass that identity value as the first argument to prevent +\&\f(CW\*(C`undef\*(C'\fR being returned +.PP +.Vb 1 +\& $foo = reduce { $a + $b } 0, @values; # sum with 0 identity value +.Ve +.PP +The above example code blocks also suggest how to use \f(CW\*(C`reduce\*(C'\fR to build a +more efficient combined version of one of these basic functions and a \f(CW\*(C`map\*(C'\fR +block. For example, to find the total length of all the strings in a list, +we could use +.PP +.Vb 1 +\& $total = sum map { length } @strings; +.Ve +.PP +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 \f(CW\*(C`reduce\*(C'\fR with a code +block that accumulates lengths by writing this instead as: +.PP +.Vb 1 +\& $total = reduce { $a + length $b } 0, @strings +.Ve +.PP +The other scalar-returning list reduction functions are all specialisations of +this generic idea. +.SS reductions +.IX Subsection "reductions" +.Vb 1 +\& @results = reductions { BLOCK } @list +.Ve +.PP +\&\fISince version 1.54.\fR +.PP +Similar to \f(CW\*(C`reduce\*(C'\fR except that it also returns the intermediate values along +with the final result. As before, \f(CW$a\fR is set to the first element of the +given list, and the \f(CW\*(C`BLOCK\*(C'\fR is then called once for remaining item in the +list set into \f(CW$b\fR, with the result being captured for return as well as +becoming the new value for \f(CW$a\fR. +.PP +The returned list will begin with the initial value for \f(CW$a\fR, followed by +each return value from the block in order. The final value of the result will +be identical to what the \f(CW\*(C`reduce\*(C'\fR function would have returned given the same +block and list. +.PP +.Vb 2 +\& reduce { "$a\-$b" } "a".."d" # "a\-b\-c\-d" +\& reductions { "$a\-$b" } "a".."d" # "a", "a\-b", "a\-b\-c", "a\-b\-c\-d" +.Ve +.SS any +.IX Subsection "any" +.Vb 1 +\& my $bool = any { BLOCK } @list; +.Ve +.PP +\&\fISince version 1.33.\fR +.PP +Similar to \f(CW\*(C`grep\*(C'\fR in that it evaluates \f(CW\*(C`BLOCK\*(C'\fR setting \f(CW$_\fR to each element +of \f(CW@list\fR in turn. \f(CW\*(C`any\*(C'\fR returns true if any element makes the \f(CW\*(C`BLOCK\*(C'\fR +return a true value. If \f(CW\*(C`BLOCK\*(C'\fR never returns true or \f(CW@list\fR was empty then +it returns false. +.PP +Many cases of using \f(CW\*(C`grep\*(C'\fR in a conditional can be written using \f(CW\*(C`any\*(C'\fR +instead, as it can short-circuit after the first true result. +.PP +.Vb 3 +\& if( any { length > 10 } @strings ) { +\& # at least one string has more than 10 characters +\& } +.Ve +.PP +Note: Due to XS issues the block passed may be able to access the outer \f(CW@_\fR +directly. This is not intentional and will break under debugger. +.SS all +.IX Subsection "all" +.Vb 1 +\& my $bool = all { BLOCK } @list; +.Ve +.PP +\&\fISince version 1.33.\fR +.PP +Similar to "any", except that it requires all elements of the \f(CW@list\fR to +make the \f(CW\*(C`BLOCK\*(C'\fR return true. If any element returns false, then it returns +false. If the \f(CW\*(C`BLOCK\*(C'\fR never returns false or the \f(CW@list\fR was empty then it +returns true. +.PP +Note: Due to XS issues the block passed may be able to access the outer \f(CW@_\fR +directly. This is not intentional and will break under debugger. +.SS none +.IX Subsection "none" +.SS notall +.IX Subsection "notall" +.Vb 1 +\& my $bool = none { BLOCK } @list; +\& +\& my $bool = notall { BLOCK } @list; +.Ve +.PP +\&\fISince version 1.33.\fR +.PP +Similar to "any" and "all", but with the return sense inverted. \f(CW\*(C`none\*(C'\fR +returns true only if no value in the \f(CW@list\fR causes the \f(CW\*(C`BLOCK\*(C'\fR to return +true, and \f(CW\*(C`notall\*(C'\fR returns true only if not all of the values do. +.PP +Note: Due to XS issues the block passed may be able to access the outer \f(CW@_\fR +directly. This is not intentional and will break under debugger. +.SS first +.IX Subsection "first" +.Vb 1 +\& my $val = first { BLOCK } @list; +.Ve +.PP +Similar to \f(CW\*(C`grep\*(C'\fR in that it evaluates \f(CW\*(C`BLOCK\*(C'\fR setting \f(CW$_\fR to each element +of \f(CW@list\fR in turn. \f(CW\*(C`first\*(C'\fR returns the first element where the result from +\&\f(CW\*(C`BLOCK\*(C'\fR is a true value. If \f(CW\*(C`BLOCK\*(C'\fR never returns true or \f(CW@list\fR was empty +then \f(CW\*(C`undef\*(C'\fR is returned. +.PP +.Vb 3 +\& $foo = first { defined($_) } @list # first defined value in @list +\& $foo = first { $_ > $value } @list # first value in @list which +\& # is greater than $value +.Ve +.SS max +.IX Subsection "max" +.Vb 1 +\& my $num = max @list; +.Ve +.PP +Returns the entry in the list with the highest numerical value. If the list is +empty then \f(CW\*(C`undef\*(C'\fR is returned. +.PP +.Vb 3 +\& $foo = max 1..10 # 10 +\& $foo = max 3,9,12 # 12 +\& $foo = max @bar, @baz # whatever +.Ve +.SS maxstr +.IX Subsection "maxstr" +.Vb 1 +\& my $str = maxstr @list; +.Ve +.PP +Similar to "max", but treats all the entries in the list as strings and +returns the highest string as defined by the \f(CW\*(C`gt\*(C'\fR operator. If the list is +empty then \f(CW\*(C`undef\*(C'\fR is returned. +.PP +.Vb 3 +\& $foo = maxstr \*(AqA\*(Aq..\*(AqZ\*(Aq # \*(AqZ\*(Aq +\& $foo = maxstr "hello","world" # "world" +\& $foo = maxstr @bar, @baz # whatever +.Ve +.SS min +.IX Subsection "min" +.Vb 1 +\& my $num = min @list; +.Ve +.PP +Similar to "max" but returns the entry in the list with the lowest numerical +value. If the list is empty then \f(CW\*(C`undef\*(C'\fR is returned. +.PP +.Vb 3 +\& $foo = min 1..10 # 1 +\& $foo = min 3,9,12 # 3 +\& $foo = min @bar, @baz # whatever +.Ve +.SS minstr +.IX Subsection "minstr" +.Vb 1 +\& my $str = minstr @list; +.Ve +.PP +Similar to "min", but treats all the entries in the list as strings and +returns the lowest string as defined by the \f(CW\*(C`lt\*(C'\fR operator. If the list is +empty then \f(CW\*(C`undef\*(C'\fR is returned. +.PP +.Vb 3 +\& $foo = minstr \*(AqA\*(Aq..\*(AqZ\*(Aq # \*(AqA\*(Aq +\& $foo = minstr "hello","world" # "hello" +\& $foo = minstr @bar, @baz # whatever +.Ve +.SS product +.IX Subsection "product" +.Vb 1 +\& my $num = product @list; +.Ve +.PP +\&\fISince version 1.35.\fR +.PP +Returns the numerical product of all the elements in \f(CW@list\fR. If \f(CW@list\fR is +empty then \f(CW1\fR is returned. +.PP +.Vb 2 +\& $foo = product 1..10 # 3628800 +\& $foo = product 3,9,12 # 324 +.Ve +.SS sum +.IX Subsection "sum" +.Vb 1 +\& my $num_or_undef = sum @list; +.Ve +.PP +Returns the numerical sum of all the elements in \f(CW@list\fR. For backwards +compatibility, if \f(CW@list\fR is empty then \f(CW\*(C`undef\*(C'\fR is returned. +.PP +.Vb 3 +\& $foo = sum 1..10 # 55 +\& $foo = sum 3,9,12 # 24 +\& $foo = sum @bar, @baz # whatever +.Ve +.SS sum0 +.IX Subsection "sum0" +.Vb 1 +\& my $num = sum0 @list; +.Ve +.PP +\&\fISince version 1.26.\fR +.PP +Similar to "sum", except this returns 0 when given an empty list, rather +than \f(CW\*(C`undef\*(C'\fR. +.SH "KEY/VALUE PAIR LIST FUNCTIONS" +.IX Header "KEY/VALUE PAIR LIST FUNCTIONS" +The following set of functions, all inspired by List::Pairwise, consume an +even-sized list of pairs. The pairs may be key/value associations from a hash, +or just a list of values. The functions will all preserve the original ordering +of the pairs, and will not be confused by multiple pairs having the same "key" +value \- nor even do they require that the first of each pair be a plain string. +.PP +\&\fBNOTE\fR: At the time of writing, the following \f(CW\*(C`pair*\*(C'\fR functions that take a +block do not modify the value of \f(CW$_\fR within the block, and instead operate +using the \f(CW$a\fR and \f(CW$b\fR globals instead. This has turned out to be a poor +design, as it precludes the ability to provide a \f(CW\*(C`pairsort\*(C'\fR function. Better +would be to pass pair-like objects as 2\-element array references in \f(CW$_\fR, in +a style similar to the return value of the \f(CW\*(C`pairs\*(C'\fR function. At some future +version this behaviour may be added. +.PP +Until then, users are alerted \fBNOT\fR to rely on the value of \f(CW$_\fR remaining +unmodified between the outside and the inside of the control block. In +particular, the following example is \fBUNSAFE\fR: +.PP +.Vb 1 +\& my @kvlist = ... +\& +\& foreach (qw( some keys here )) { +\& my @items = pairgrep { $a eq $_ } @kvlist; +\& ... +\& } +.Ve +.PP +Instead, write this using a lexical variable: +.PP +.Vb 4 +\& foreach my $key (qw( some keys here )) { +\& my @items = pairgrep { $a eq $key } @kvlist; +\& ... +\& } +.Ve +.SS pairs +.IX Subsection "pairs" +.Vb 1 +\& my @pairs = pairs @kvlist; +.Ve +.PP +\&\fISince version 1.29.\fR +.PP +A convenient shortcut to operating on even-sized lists of pairs, this function +returns a list of \f(CW\*(C`ARRAY\*(C'\fR references, each containing two items from the +given list. It is a more efficient version of +.PP +.Vb 1 +\& @pairs = pairmap { [ $a, $b ] } @kvlist +.Ve +.PP +It is most convenient to use in a \f(CW\*(C`foreach\*(C'\fR loop, for example: +.PP +.Vb 4 +\& foreach my $pair ( pairs @kvlist ) { +\& my ( $key, $value ) = @$pair; +\& ... +\& } +.Ve +.PP +Since version \f(CW1.39\fR these \f(CW\*(C`ARRAY\*(C'\fR references are blessed objects, +recognising the two methods \f(CW\*(C`key\*(C'\fR and \f(CW\*(C`value\*(C'\fR. The following code is +equivalent: +.PP +.Vb 5 +\& foreach my $pair ( pairs @kvlist ) { +\& my $key = $pair\->key; +\& my $value = $pair\->value; +\& ... +\& } +.Ve +.PP +Since version \f(CW1.51\fR they also have a \f(CW\*(C`TO_JSON\*(C'\fR method to ease +serialisation. +.SS unpairs +.IX Subsection "unpairs" +.Vb 1 +\& my @kvlist = unpairs @pairs +.Ve +.PP +\&\fISince version 1.42.\fR +.PP +The inverse function to \f(CW\*(C`pairs\*(C'\fR; this function takes a list of \f(CW\*(C`ARRAY\*(C'\fR +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 +.PP +.Vb 1 +\& my @kvlist = map { @{$_}[0,1] } @pairs +.Ve +.PP +except that it is implemented more efficiently internally. Specifically, for +any input item it will extract exactly two values for the output list; using +\&\f(CW\*(C`undef\*(C'\fR if the input array references are short. +.PP +Between \f(CW\*(C`pairs\*(C'\fR and \f(CW\*(C`unpairs\*(C'\fR, a higher-order list function can be used to +operate on the pairs as single scalars; such as the following near-equivalents +of the other \f(CW\*(C`pair*\*(C'\fR higher-order functions: +.PP +.Vb 2 +\& @kvlist = unpairs grep { FUNC } pairs @kvlist +\& # Like pairgrep, but takes $_ instead of $a and $b +\& +\& @kvlist = unpairs map { FUNC } pairs @kvlist +\& # Like pairmap, but takes $_ instead of $a and $b +.Ve +.PP +Note however that these versions will not behave as nicely in scalar context. +.PP +Finally, this technique can be used to implement a sort on a keyvalue pair +list; e.g.: +.PP +.Vb 1 +\& @kvlist = unpairs sort { $a\->key cmp $b\->key } pairs @kvlist +.Ve +.SS pairkeys +.IX Subsection "pairkeys" +.Vb 1 +\& my @keys = pairkeys @kvlist; +.Ve +.PP +\&\fISince version 1.29.\fR +.PP +A convenient shortcut to operating on even-sized lists of pairs, this function +returns a list of the the first values of each of the pairs in the given list. +It is a more efficient version of +.PP +.Vb 1 +\& @keys = pairmap { $a } @kvlist +.Ve +.SS pairvalues +.IX Subsection "pairvalues" +.Vb 1 +\& my @values = pairvalues @kvlist; +.Ve +.PP +\&\fISince version 1.29.\fR +.PP +A convenient shortcut to operating on even-sized lists of pairs, this function +returns a list of the the second values of each of the pairs in the given list. +It is a more efficient version of +.PP +.Vb 1 +\& @values = pairmap { $b } @kvlist +.Ve +.SS pairgrep +.IX Subsection "pairgrep" +.Vb 1 +\& my @kvlist = pairgrep { BLOCK } @kvlist; +\& +\& my $count = pairgrep { BLOCK } @kvlist; +.Ve +.PP +\&\fISince version 1.29.\fR +.PP +Similar to perl's \f(CW\*(C`grep\*(C'\fR keyword, but interprets the given list as an +even-sized list of pairs. It invokes the \f(CW\*(C`BLOCK\*(C'\fR multiple times, in scalar +context, with \f(CW$a\fR and \f(CW$b\fR set to successive pairs of values from the +\&\f(CW@kvlist\fR. +.PP +Returns an even-sized list of those pairs for which the \f(CW\*(C`BLOCK\*(C'\fR returned true +in list context, or the count of the \fBnumber of pairs\fR in scalar context. +(Note, therefore, in scalar context that it returns a number half the size of +the count of items it would have returned in list context). +.PP +.Vb 1 +\& @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist +.Ve +.PP +As with \f(CW\*(C`grep\*(C'\fR aliasing \f(CW$_\fR to list elements, \f(CW\*(C`pairgrep\*(C'\fR aliases \f(CW$a\fR and +\&\f(CW$b\fR to elements of the given list. Any modifications of it by the code block +will be visible to the caller. +.SS pairfirst +.IX Subsection "pairfirst" +.Vb 1 +\& my ( $key, $val ) = pairfirst { BLOCK } @kvlist; +\& +\& my $found = pairfirst { BLOCK } @kvlist; +.Ve +.PP +\&\fISince version 1.30.\fR +.PP +Similar to the "first" function, but interprets the given list as an +even-sized list of pairs. It invokes the \f(CW\*(C`BLOCK\*(C'\fR multiple times, in scalar +context, with \f(CW$a\fR and \f(CW$b\fR set to successive pairs of values from the +\&\f(CW@kvlist\fR. +.PP +Returns the first pair of values from the list for which the \f(CW\*(C`BLOCK\*(C'\fR returned +true in list context, or an empty list of no such pair was found. In scalar +context it returns a simple boolean value, rather than either the key or the +value found. +.PP +.Vb 1 +\& ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist +.Ve +.PP +As with \f(CW\*(C`grep\*(C'\fR aliasing \f(CW$_\fR to list elements, \f(CW\*(C`pairfirst\*(C'\fR aliases \f(CW$a\fR and +\&\f(CW$b\fR to elements of the given list. Any modifications of it by the code block +will be visible to the caller. +.SS pairmap +.IX Subsection "pairmap" +.Vb 1 +\& my @list = pairmap { BLOCK } @kvlist; +\& +\& my $count = pairmap { BLOCK } @kvlist; +.Ve +.PP +\&\fISince version 1.29.\fR +.PP +Similar to perl's \f(CW\*(C`map\*(C'\fR keyword, but interprets the given list as an +even-sized list of pairs. It invokes the \f(CW\*(C`BLOCK\*(C'\fR multiple times, in list +context, with \f(CW$a\fR and \f(CW$b\fR set to successive pairs of values from the +\&\f(CW@kvlist\fR. +.PP +Returns the concatenation of all the values returned by the \f(CW\*(C`BLOCK\*(C'\fR in list +context, or the count of the number of items that would have been returned in +scalar context. +.PP +.Vb 1 +\& @result = pairmap { "The key $a has value $b" } @kvlist +.Ve +.PP +As with \f(CW\*(C`map\*(C'\fR aliasing \f(CW$_\fR to list elements, \f(CW\*(C`pairmap\*(C'\fR aliases \f(CW$a\fR and +\&\f(CW$b\fR to elements of the given list. Any modifications of it by the code block +will be visible to the caller. +.PP +See "KNOWN BUGS" for a known-bug with \f(CW\*(C`pairmap\*(C'\fR, and a workaround. +.SH "OTHER FUNCTIONS" +.IX Header "OTHER FUNCTIONS" +.SS shuffle +.IX Subsection "shuffle" +.Vb 1 +\& my @values = shuffle @values; +.Ve +.PP +Returns the values of the input in a random order +.PP +.Vb 1 +\& @cards = shuffle 0..51 # 0..51 in a random order +.Ve +.PP +This function is affected by the \f(CW$RAND\fR variable. +.SS sample +.IX Subsection "sample" +.Vb 1 +\& my @items = sample $count, @values +.Ve +.PP +\&\fISince version 1.54.\fR +.PP +Randomly select the given number of elements from the input list. Any given +position in the input list will be selected at most once. +.PP +If there are fewer than \f(CW$count\fR items in the list then the function will +return once all of them have been randomly selected; effectively the function +behaves similarly to "shuffle". +.PP +This function is affected by the \f(CW$RAND\fR variable. +.SS uniq +.IX Subsection "uniq" +.Vb 1 +\& my @subset = uniq @values +.Ve +.PP +\&\fISince version 1.45.\fR +.PP +Filters a list of values to remove subsequent duplicates, as judged by a +DWIM-ish string equality or \f(CW\*(C`undef\*(C'\fR test. Preserves the order of unique +elements, and retains the first value of any duplicate set. +.PP +.Vb 1 +\& my $count = uniq @values +.Ve +.PP +In scalar context, returns the number of elements that would have been +returned as a list. +.PP +The \f(CW\*(C`undef\*(C'\fR 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 \f(CW\*(C`undef\*(C'\fR values are still considered identical to the first, +and will be removed. +.SS uniqint +.IX Subsection "uniqint" +.Vb 1 +\& my @subset = uniqint @values +.Ve +.PP +\&\fISince version 1.55.\fR +.PP +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. +.PP +.Vb 1 +\& my $count = uniqint @values +.Ve +.PP +In scalar context, returns the number of elements that would have been +returned as a list. +.PP +Note that \f(CW\*(C`undef\*(C'\fR is treated much as other numerical operations treat it; it +compares equal to zero but additionally produces a warning if such warnings +are enabled (\f(CW\*(C`use warnings \*(Aquninitialized\*(Aq;\*(C'\fR). In addition, an \f(CW\*(C`undef\*(C'\fR in +the returned list is coerced into a numerical zero, so that the entire list of +values returned by \f(CW\*(C`uniqint\*(C'\fR are well-behaved as integers. +.SS uniqnum +.IX Subsection "uniqnum" +.Vb 1 +\& my @subset = uniqnum @values +.Ve +.PP +\&\fISince version 1.44.\fR +.PP +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. +.PP +.Vb 1 +\& my $count = uniqnum @values +.Ve +.PP +In scalar context, returns the number of elements that would have been +returned as a list. +.PP +Note that \f(CW\*(C`undef\*(C'\fR is treated much as other numerical operations treat it; it +compares equal to zero but additionally produces a warning if such warnings +are enabled (\f(CW\*(C`use warnings \*(Aquninitialized\*(Aq;\*(C'\fR). In addition, an \f(CW\*(C`undef\*(C'\fR in +the returned list is coerced into a numerical zero, so that the entire list of +values returned by \f(CW\*(C`uniqnum\*(C'\fR are well-behaved as numbers. +.PP +Note also that multiple IEEE \f(CW\*(C`NaN\*(C'\fR values are treated as duplicates of +each other, regardless of any differences in their payloads, and despite +the fact that \f(CW\*(C`0+\*(AqNaN\*(Aq == 0+\*(AqNaN\*(Aq\*(C'\fR yields false. +.SS uniqstr +.IX Subsection "uniqstr" +.Vb 1 +\& my @subset = uniqstr @values +.Ve +.PP +\&\fISince version 1.45.\fR +.PP +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. +.PP +.Vb 1 +\& my $count = uniqstr @values +.Ve +.PP +In scalar context, returns the number of elements that would have been +returned as a list. +.PP +Note that \f(CW\*(C`undef\*(C'\fR 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 (\f(CW\*(C`use warnings \*(Aquninitialized\*(Aq;\*(C'\fR). In addition, an +\&\f(CW\*(C`undef\*(C'\fR in the returned list is coerced into an empty string, so that the +entire list of values returned by \f(CW\*(C`uniqstr\*(C'\fR are well-behaved as strings. +.SS head +.IX Subsection "head" +.Vb 1 +\& my @values = head $size, @list; +.Ve +.PP +\&\fISince version 1.50.\fR +.PP +Returns the first \f(CW$size\fR elements from \f(CW@list\fR. If \f(CW$size\fR is negative, returns +all but the last \f(CW$size\fR elements from \f(CW@list\fR. +.PP +.Vb 2 +\& @result = head 2, qw( foo bar baz ); +\& # foo, bar +\& +\& @result = head \-2, qw( foo bar baz ); +\& # foo +.Ve +.SS tail +.IX Subsection "tail" +.Vb 1 +\& my @values = tail $size, @list; +.Ve +.PP +\&\fISince version 1.50.\fR +.PP +Returns the last \f(CW$size\fR elements from \f(CW@list\fR. If \f(CW$size\fR is negative, returns +all but the first \f(CW$size\fR elements from \f(CW@list\fR. +.PP +.Vb 2 +\& @result = tail 2, qw( foo bar baz ); +\& # bar, baz +\& +\& @result = tail \-2, qw( foo bar baz ); +\& # baz +.Ve +.SS zip +.IX Subsection "zip" +.Vb 2 +\& my @result = zip [1..3], [\*(Aqa\*(Aq..\*(Aqc\*(Aq]; +\& # [1, \*(Aqa\*(Aq], [2, \*(Aqb\*(Aq], [3, \*(Aqc\*(Aq] +.Ve +.PP +\&\fISince version 1.56.\fR +.PP +Returns a list of array references, composed of elements from the given list +of array references. Each array in the returned list is composed of elements +at that corresponding position from each of the given input arrays. If any +input arrays run out of elements before others, then \f(CW\*(C`undef\*(C'\fR will be inserted +into the result to fill in the gaps. +.PP +The \f(CW\*(C`zip\*(C'\fR function is particularly handy for iterating over multiple arrays +at the same time with a \f(CW\*(C`foreach\*(C'\fR loop, taking one element from each: +.PP +.Vb 4 +\& foreach ( zip \e@xs, \e@ys, \e@zs ) { +\& my ($x, $y, $z) = @$_; +\& ... +\& } +.Ve +.PP +\&\fBNOTE\fR to users of List::MoreUtils: This function does not behave the same +as \f(CW\*(C`List::MoreUtils::zip\*(C'\fR, but is actually a non-prototyped equivalent to +\&\f(CW\*(C`List::MoreUtils::zip_unflatten\*(C'\fR. This function does not apply a prototype, +so make sure to invoke it with references to arrays. +.PP +For a function similar to the \f(CW\*(C`zip\*(C'\fR function from \f(CW\*(C`List::MoreUtils\*(C'\fR, see +mesh. +.PP +.Vb 1 +\& my @result = zip_shortest ... +.Ve +.PP +A variation of the function that differs in how it behaves when given input +arrays of differing lengths. \f(CW\*(C`zip_shortest\*(C'\fR will stop as soon as any one of +the input arrays run out of elements, discarding any remaining unused values +from the others. +.PP +.Vb 1 +\& my @result = zip_longest ... +.Ve +.PP +\&\f(CW\*(C`zip_longest\*(C'\fR is an alias to the \f(CW\*(C`zip\*(C'\fR function, provided simply to be +explicit about that behaviour as compared to \f(CW\*(C`zip_shortest\*(C'\fR. +.SS mesh +.IX Subsection "mesh" +.Vb 2 +\& my @result = mesh [1..3], [\*(Aqa\*(Aq..\*(Aqc\*(Aq]; +\& # (1, \*(Aqa\*(Aq, 2, \*(Aqb\*(Aq, 3, \*(Aqc\*(Aq) +.Ve +.PP +\&\fISince version 1.56.\fR +.PP +Returns a list of items collected from elements of the given list of array +references. Each section of items in the returned list is composed of elements +at the corresponding position from each of the given input arrays. If any +input arrays run out of elements before others, then \f(CW\*(C`undef\*(C'\fR will be inserted +into the result to fill in the gaps. +.PP +This is similar to zip, except that all of the ranges in the result are +returned in one long flattened list, instead of being bundled into separate +arrays. +.PP +Because it returns a flat list of items, the \f(CW\*(C`mesh\*(C'\fR function is particularly +useful for building a hash out of two separate arrays of keys and values: +.PP +.Vb 1 +\& my %hash = mesh \e@keys, \e@values; +\& +\& my $href = { mesh \e@keys, \e@values }; +.Ve +.PP +\&\fBNOTE\fR to users of List::MoreUtils: This function is a non-prototyped +equivalent to \f(CW\*(C`List::MoreUtils::mesh\*(C'\fR or \f(CW\*(C`List::MoreUtils::zip\*(C'\fR (themselves +aliases of each other). This function does not apply a prototype, so make sure +to invoke it with references to arrays. +.PP +.Vb 1 +\& my @result = mesh_shortest ... +\& +\& my @result = mesh_longest ... +.Ve +.PP +These variations are similar to those of zip, in that they differ in +behaviour when one of the input lists runs out of elements before the others. +.SH "CONFIGURATION VARIABLES" +.IX Header "CONFIGURATION VARIABLES" +.ie n .SS $RAND +.el .SS \f(CW$RAND\fP +.IX Subsection "$RAND" +.Vb 1 +\& local $List::Util::RAND = sub { ... }; +.Ve +.PP +\&\fISince version 1.54.\fR +.PP +This package variable is used by code which needs to generate random numbers +(such as the "shuffle" and "sample" functions). If set to a CODE reference +it provides an alternative to perl's builtin \f(CWrand()\fR 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. +.SH "KNOWN BUGS" +.IX Header "KNOWN BUGS" +.SS "RT #95409" +.IX Subsection "RT #95409" +<https://rt.cpan.org/Ticket/Display.html?id=95409> +.PP +If the block of code given to "pairmap" contains lexical variables that are +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 +correct values. For example: +.PP +.Vb 4 +\& my @subs = pairmap { +\& my $var = "$a is $b"; +\& sub { print "$var\en" }; +\& } one => 1, two => 2, three => 3; +\& +\& $_\->() for @subs; +.Ve +.PP +Will incorrectly print +.PP +.Vb 3 +\& three is 3 +\& three is 3 +\& three is 3 +.Ve +.PP +This is due to the performance optimisation of using \f(CW\*(C`MULTICALL\*(C'\fR for the code +block, which means that fresh SVs do not get allocated for each call to the +block. Instead, the same SV is re-assigned for each iteration, and all the +closures will share the value seen on the final iteration. +.PP +To work around this bug, surround the code with a second set of braces. This +creates an inner block that defeats the \f(CW\*(C`MULTICALL\*(C'\fR logic, and does get fresh +SVs allocated each time: +.PP +.Vb 6 +\& my @subs = pairmap { +\& { +\& my $var = "$a is $b"; +\& sub { print "$var\en"; } +\& } +\& } one => 1, two => 2, three => 3; +.Ve +.PP +This bug only affects closures that are generated by the block but used +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. +.SS "\fBuniqnum()\fP on oversized bignums" +.IX Subsection "uniqnum() on oversized bignums" +Due to the way that \f(CWuniqnum()\fR compares numbers, it cannot distinguish +differences between bignums (especially bigints) that are too large to fit in +the native platform types. For example, +.PP +.Vb 2 +\& my $x = Math::BigInt\->new( "1" x 100 ); +\& my $y = $x + 1; +\& +\& say for uniqnum( $x, $y ); +.Ve +.PP +Will print just the value of \f(CW$x\fR, believing that \f(CW$y\fR is a numerically\- +equivalent value. This bug does not affect \f(CWuniqstr()\fR, which will correctly +observe that the two values stringify to different strings. +.SH "SUGGESTED ADDITIONS" +.IX Header "SUGGESTED ADDITIONS" +The following are additions that have been requested, but I have been reluctant +to add due to them being very simple to implement in perl +.PP +.Vb 1 +\& # How many elements are true +\& +\& sub true { scalar grep { $_ } @_ } +\& +\& # How many elements are false +\& +\& sub false { scalar grep { !$_ } @_ } +.Ve +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Scalar::Util, List::MoreUtils +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 1997\-2007 Graham Barr <gbarr@pobox.com>. All rights reserved. +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. +.PP +Recent additions and current maintenance by +Paul Evans, <leonerd@leonerd.org.uk>. |