local-lib5/man/man3/List::Util.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "List::Util 3"
 127 .TH List::Util 3 "2009-11-14" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 List::Util \- A selection of general\-utility list subroutines
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use List::Util qw(first max maxstr min minstr reduce shuffle sum);
 138 .Ve
 139 .SH "DESCRIPTION"
 140 .IX Header "DESCRIPTION"
 141 \&\f(CW\*(C`List::Util\*(C'\fR contains a selection of subroutines that people have
 142 expressed would be nice to have in the perl core, but the usage would
 143 not really be high enough to warrant the use of a keyword, and the size
 144 so small such that being individual extensions would be wasteful.
 145 .PP
 146 By default \f(CW\*(C`List::Util\*(C'\fR does not export any subroutines. The
 147 subroutines defined are
 148 .IP "first \s-1BLOCK\s0 \s-1LIST\s0" 4
 149 .IX Item "first BLOCK LIST"
 150 Similar to \f(CW\*(C`grep\*(C'\fR in that it evaluates \s-1BLOCK\s0 setting \f(CW$_\fR to each element
 151 of \s-1LIST\s0 in turn. \f(CW\*(C`first\*(C'\fR returns the first element where the result from
 152 \&\s-1BLOCK\s0 is a true value. If \s-1BLOCK\s0 never returns true or \s-1LIST\s0 was empty then
 153 \&\f(CW\*(C`undef\*(C'\fR is returned.
 154 .Sp
 155 .Vb 3
 156 \&    $foo = first { defined($_) } @list    # first defined value in @list
 157 \&    $foo = first { $_ > $value } @list    # first value in @list which
 158 \&                                          # is greater than $value
 159 .Ve
 160 .Sp
 161 This function could be implemented using \f(CW\*(C`reduce\*(C'\fR like this
 162 .Sp
 163 .Vb 1
 164 \&    $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
 165 .Ve
 166 .Sp
 167 for example \fIwanted()\fR could be \fIdefined()\fR which would return the first
 168 defined value in \f(CW@list\fR
 169 .IP "max \s-1LIST\s0" 4
 170 .IX Item "max LIST"
 171 Returns the entry in the list with the highest numerical value. If the
 172 list is empty then \f(CW\*(C`undef\*(C'\fR is returned.
 173 .Sp
 174 .Vb 3
 175 \&    $foo = max 1..10                # 10
 176 \&    $foo = max 3,9,12               # 12
 177 \&    $foo = max @bar, @baz           # whatever
 178 .Ve
 179 .Sp
 180 This function could be implemented using \f(CW\*(C`reduce\*(C'\fR like this
 181 .Sp
 182 .Vb 1
 183 \&    $foo = reduce { $a > $b ? $a : $b } 1..10
 184 .Ve
 185 .IP "maxstr \s-1LIST\s0" 4
 186 .IX Item "maxstr LIST"
 187 Similar to \f(CW\*(C`max\*(C'\fR, but treats all the entries in the list as strings
 188 and returns the highest string as defined by the \f(CW\*(C`gt\*(C'\fR operator.
 189 If the list is empty then \f(CW\*(C`undef\*(C'\fR is returned.
 190 .Sp
 191 .Vb 3
 192 \&    $foo = maxstr \*(AqA\*(Aq..\*(AqZ\*(Aq          # \*(AqZ\*(Aq
 193 \&    $foo = maxstr "hello","world"   # "world"
 194 \&    $foo = maxstr @bar, @baz        # whatever
 195 .Ve
 196 .Sp
 197 This function could be implemented using \f(CW\*(C`reduce\*(C'\fR like this
 198 .Sp
 199 .Vb 1
 200 \&    $foo = reduce { $a gt $b ? $a : $b } \*(AqA\*(Aq..\*(AqZ\*(Aq
 201 .Ve
 202 .IP "min \s-1LIST\s0" 4
 203 .IX Item "min LIST"
 204 Similar to \f(CW\*(C`max\*(C'\fR but returns the entry in the list with the lowest
 205 numerical value. If the list is empty then \f(CW\*(C`undef\*(C'\fR is returned.
 206 .Sp
 207 .Vb 3
 208 \&    $foo = min 1..10                # 1
 209 \&    $foo = min 3,9,12               # 3
 210 \&    $foo = min @bar, @baz           # whatever
 211 .Ve
 212 .Sp
 213 This function could be implemented using \f(CW\*(C`reduce\*(C'\fR like this
 214 .Sp
 215 .Vb 1
 216 \&    $foo = reduce { $a < $b ? $a : $b } 1..10
 217 .Ve
 218 .IP "minstr \s-1LIST\s0" 4
 219 .IX Item "minstr LIST"
 220 Similar to \f(CW\*(C`min\*(C'\fR, but treats all the entries in the list as strings
 221 and returns the lowest string as defined by the \f(CW\*(C`lt\*(C'\fR operator.
 222 If the list is empty then \f(CW\*(C`undef\*(C'\fR is returned.
 223 .Sp
 224 .Vb 3
 225 \&    $foo = minstr \*(AqA\*(Aq..\*(AqZ\*(Aq          # \*(AqA\*(Aq
 226 \&    $foo = minstr "hello","world"   # "hello"
 227 \&    $foo = minstr @bar, @baz        # whatever
 228 .Ve
 229 .Sp
 230 This function could be implemented using \f(CW\*(C`reduce\*(C'\fR like this
 231 .Sp
 232 .Vb 1
 233 \&    $foo = reduce { $a lt $b ? $a : $b } \*(AqA\*(Aq..\*(AqZ\*(Aq
 234 .Ve
 235 .IP "reduce \s-1BLOCK\s0 \s-1LIST\s0" 4
 236 .IX Item "reduce BLOCK LIST"
 237 Reduces \s-1LIST\s0 by calling \s-1BLOCK\s0, in a scalar context, multiple times,
 238 setting \f(CW$a\fR and \f(CW$b\fR each time. The first call will be with \f(CW$a\fR
 239 and \f(CW$b\fR set to the first two elements of the list, subsequent
 240 calls will be done by setting \f(CW$a\fR to the result of the previous
 241 call and \f(CW$b\fR to the next element in the list.
 242 .Sp
 243 Returns the result of the last call to \s-1BLOCK\s0. If \s-1LIST\s0 is empty then
 244 \&\f(CW\*(C`undef\*(C'\fR is returned. If \s-1LIST\s0 only contains one element then that
 245 element is returned and \s-1BLOCK\s0 is not executed.
 246 .Sp
 247 .Vb 4
 248 \&    $foo = reduce { $a < $b ? $a : $b } 1..10       # min
 249 \&    $foo = reduce { $a lt $b ? $a : $b } \*(Aqaa\*(Aq..\*(Aqzz\*(Aq # minstr
 250 \&    $foo = reduce { $a + $b } 1 .. 10               # sum
 251 \&    $foo = reduce { $a . $b } @bar                  # concat
 252 .Ve
 253 .Sp
 254 If your algorithm requires that \f(CW\*(C`reduce\*(C'\fR produce an identity value, then
 255 make sure that you always pass that identity value as the first argument to prevent
 256 \&\f(CW\*(C`undef\*(C'\fR being returned
 257 .Sp
 258 .Vb 1
 259 \&  $foo = reduce { $a + $b } 0, @values;             # sum with 0 identity value
 260 .Ve
 261 .IP "shuffle \s-1LIST\s0" 4
 262 .IX Item "shuffle LIST"
 263 Returns the elements of \s-1LIST\s0 in a random order
 264 .Sp
 265 .Vb 1
 266 \&    @cards = shuffle 0..51      # 0..51 in a random order
 267 .Ve
 268 .IP "sum \s-1LIST\s0" 4
 269 .IX Item "sum LIST"
 270 Returns the sum of all the elements in \s-1LIST\s0. If \s-1LIST\s0 is empty then
 271 \&\f(CW\*(C`undef\*(C'\fR is returned.
 272 .Sp
 273 .Vb 3
 274 \&    $foo = sum 1..10                # 55
 275 \&    $foo = sum 3,9,12               # 24
 276 \&    $foo = sum @bar, @baz           # whatever
 277 .Ve
 278 .Sp
 279 This function could be implemented using \f(CW\*(C`reduce\*(C'\fR like this
 280 .Sp
 281 .Vb 1
 282 \&    $foo = reduce { $a + $b } 1..10
 283 .Ve
 284 .Sp
 285 If your algorithm requires that \f(CW\*(C`sum\*(C'\fR produce an identity of 0, then
 286 make sure that you always pass \f(CW0\fR as the first argument to prevent
 287 \&\f(CW\*(C`undef\*(C'\fR being returned
 288 .Sp
 289 .Vb 1
 290 \&  $foo = sum 0, @values;
 291 .Ve
 292 .SH "KNOWN BUGS"
 293 .IX Header "KNOWN BUGS"
 294 With perl versions prior to 5.005 there are some cases where reduce
 295 will return an incorrect result. This will show up as test 7 of
 296 reduce.t failing.
 297 .SH "SUGGESTED ADDITIONS"
 298 .IX Header "SUGGESTED ADDITIONS"
 299 The following are additions that have been requested, but I have been reluctant
 300 to add due to them being very simple to implement in perl
 301 .PP
 302 .Vb 1
 303 \&  # One argument is true
 304 \&
 305 \&  sub any { $_ && return 1 for @_; 0 }
 306 \&
 307 \&  # All arguments are true
 308 \&
 309 \&  sub all { $_ || return 0 for @_; 1 }
 310 \&
 311 \&  # All arguments are false
 312 \&
 313 \&  sub none { $_ && return 0 for @_; 1 }
 314 \&
 315 \&  # One argument is false
 316 \&
 317 \&  sub notall { $_ || return 1 for @_; 0 }
 318 \&
 319 \&  # How many elements are true
 320 \&
 321 \&  sub true { scalar grep { $_ } @_ }
 322 \&
 323 \&  # How many elements are false
 324 \&
 325 \&  sub false { scalar grep { !$_ } @_ }
 326 .Ve
 327 .SH "SEE ALSO"
 328 .IX Header "SEE ALSO"
 329 Scalar::Util, List::MoreUtils
 330 .SH "COPYRIGHT"
 331 .IX Header "COPYRIGHT"
 332 Copyright (c) 1997\-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
 333 This program is free software; you can redistribute it and/or
 334 modify it under the same terms as Perl itself.