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

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "List::MoreUtils 3"
 132 .TH List::MoreUtils 3 "2006-07-02" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 List::MoreUtils \- Provide the stuff missing in List::Util
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 5
 138 \&    use List::MoreUtils qw(any all none notall true false firstidx first_index
 139 \&                           lastidx last_index insert_after insert_after_string
 140 \&                           apply after after_incl before before_incl indexes
 141 \&                           firstval first_value lastval last_value each_array
 142 \&                           each_arrayref pairwise natatime mesh zip uniq minmax);
 143 .Ve
 144 .SH "DESCRIPTION"
 145 .IX Header "DESCRIPTION"
 146 \&\f(CW\*(C`List::MoreUtils\*(C'\fR provides some trivial but commonly needed functionality on lists
 147 which is not going to go into \f(CW\*(C`List::Util\*(C'\fR.
 148 .PP
 149 All of the below functions are implementable in only a couple of lines of Perl
 150 code. Using the functions from this module however should give slightly better
 151 performance as everything is implemented in C. The pure-Perl implementation of
 152 these functions only serves as a fallback in case the C portions of this module
 153 couldn't be compiled on this machine.
 154 .IP "any \s-1BLOCK\s0 \s-1LIST\s0" 4
 155 .IX Item "any BLOCK LIST"
 156 Returns a true value if any item in \s-1LIST\s0 meets the criterion given through
 157 \&\s-1BLOCK\s0. Sets \f(CW$_\fR for each item in \s-1LIST\s0 in turn:
 158 .Sp
 159 .Vb 2
 160 \&    print "At least one value undefined"
 161 \&        if any { !defined($_) } @list;
 162 .Ve
 163 .Sp
 164 Returns false otherwise, or \f(CW\*(C`undef\*(C'\fR if \s-1LIST\s0 is empty.
 165 .IP "all \s-1BLOCK\s0 \s-1LIST\s0" 4
 166 .IX Item "all BLOCK LIST"
 167 Returns a true value if all items in \s-1LIST\s0 meet the criterion given through
 168 \&\s-1BLOCK\s0. Sets \f(CW$_\fR for each item in \s-1LIST\s0 in turn:
 169 .Sp
 170 .Vb 2
 171 \&    print "All items defined"
 172 \&        if all { defined($_) } @list;
 173 .Ve
 174 .Sp
 175 Returns false otherwise, or \f(CW\*(C`undef\*(C'\fR if \s-1LIST\s0 is empty.
 176 .IP "none \s-1BLOCK\s0 \s-1LIST\s0" 4
 177 .IX Item "none BLOCK LIST"
 178 Logically the negation of \f(CW\*(C`any\*(C'\fR. Returns a true value if no item in \s-1LIST\s0 meets the
 179 criterion given through \s-1BLOCK\s0. Sets \f(CW$_\fR for each item in \s-1LIST\s0 in turn:
 180 .Sp
 181 .Vb 2
 182 \&    print "No value defined"
 183 \&        if none { defined($_) } @list;
 184 .Ve
 185 .Sp
 186 Returns false otherwise, or \f(CW\*(C`undef\*(C'\fR if \s-1LIST\s0 is empty.
 187 .IP "notall \s-1BLOCK\s0 \s-1LIST\s0" 4
 188 .IX Item "notall BLOCK LIST"
 189 Logically the negation of \f(CW\*(C`all\*(C'\fR. Returns a true value if not all items in \s-1LIST\s0 meet
 190 the criterion given through \s-1BLOCK\s0. Sets \f(CW$_\fR for each item in \s-1LIST\s0 in turn:
 191 .Sp
 192 .Vb 2
 193 \&    print "Not all values defined"
 194 \&        if notall { defined($_) } @list;
 195 .Ve
 196 .Sp
 197 Returns false otherwise, or \f(CW\*(C`undef\*(C'\fR if \s-1LIST\s0 is empty.
 198 .IP "true \s-1BLOCK\s0 \s-1LIST\s0" 4
 199 .IX Item "true BLOCK LIST"
 200 Counts the number of elements in \s-1LIST\s0 for which the criterion in \s-1BLOCK\s0 is true. Sets \f(CW$_\fR for
 201 each item in \s-1LIST\s0 in turn:
 202 .Sp
 203 .Vb 1
 204 \&    printf "%i item(s) are defined", true { defined($_) } @list;
 205 .Ve
 206 .IP "false \s-1BLOCK\s0 \s-1LIST\s0" 4
 207 .IX Item "false BLOCK LIST"
 208 Counts the number of elements in \s-1LIST\s0 for which the criterion in \s-1BLOCK\s0 is false. Sets \f(CW$_\fR for
 209 each item in \s-1LIST\s0 in turn:
 210 .Sp
 211 .Vb 1
 212 \&    printf "%i item(s) are not defined", false { defined($_) } @list;
 213 .Ve
 214 .IP "firstidx \s-1BLOCK\s0 \s-1LIST\s0" 4
 215 .IX Item "firstidx BLOCK LIST"
 216 .PD 0
 217 .IP "first_index \s-1BLOCK\s0 \s-1LIST\s0" 4
 218 .IX Item "first_index BLOCK LIST"
 219 .PD
 220 Returns the index of the first element in \s-1LIST\s0 for which the criterion in \s-1BLOCK\s0 is true. Sets \f(CW$_\fR
 221 for each item in \s-1LIST\s0 in turn:
 222 .Sp
 223 .Vb 4
 224 \&    my @list = (1, 4, 3, 2, 4, 6);
 225 \&    printf "item with index %i in list is 4", firstidx { $_ == 4 } @list;
 226 \&    __END__
 227 \&    item with index 1 in list is 4
 228 .Ve
 229 .Sp
 230 Returns \f(CW\*(C`\-1\*(C'\fR if no such item could be found.
 231 .Sp
 232 \&\f(CW\*(C`first_index\*(C'\fR is an alias for \f(CW\*(C`firstidx\*(C'\fR.
 233 .IP "lastidx \s-1BLOCK\s0 \s-1LIST\s0" 4
 234 .IX Item "lastidx BLOCK LIST"
 235 .PD 0
 236 .IP "last_index \s-1BLOCK\s0 \s-1LIST\s0" 4
 237 .IX Item "last_index BLOCK LIST"
 238 .PD
 239 Returns the index of the last element in \s-1LIST\s0 for which the criterion in \s-1BLOCK\s0 is true. Sets \f(CW$_\fR
 240 for each item in \s-1LIST\s0 in turn:
 241 .Sp
 242 .Vb 4
 243 \&    my @list = (1, 4, 3, 2, 4, 6);
 244 \&    printf "item with index %i in list is 4", lastidx { $_ == 4 } @list;
 245 \&    __END__
 246 \&    item with index 4 in list is 4
 247 .Ve
 248 .Sp
 249 Returns \f(CW\*(C`\-1\*(C'\fR if no such item could be found.
 250 .Sp
 251 \&\f(CW\*(C`last_index\*(C'\fR is an alias for \f(CW\*(C`lastidx\*(C'\fR.
 252 .IP "insert_after \s-1BLOCK\s0 \s-1VALUE\s0 \s-1LIST\s0" 4
 253 .IX Item "insert_after BLOCK VALUE LIST"
 254 Inserts \s-1VALUE\s0 after the first item in \s-1LIST\s0 for which the criterion in \s-1BLOCK\s0 is true. Sets \f(CW$_\fR for
 255 each item in \s-1LIST\s0 in turn.
 256 .Sp
 257 .Vb 5
 258 \&    my @list = qw/This is a list/;
 259 \&    insert_after { $_ eq "a" } "longer" => @list;
 260 \&    print "@list";
 261 \&    __END__
 262 \&    This is a longer list
 263 .Ve
 264 .IP "insert_after_string \s-1STRING\s0 \s-1VALUE\s0 \s-1LIST\s0" 4
 265 .IX Item "insert_after_string STRING VALUE LIST"
 266 Inserts \s-1VALUE\s0 after the first item in \s-1LIST\s0 which is equal to \s-1STRING\s0.
 267 .Sp
 268 .Vb 5
 269 \&    my @list = qw/This is a list/;
 270 \&    insert_after_string "a", "longer" => @list;
 271 \&    print "@list";
 272 \&    __END__
 273 \&    This is a longer list
 274 .Ve
 275 .IP "apply \s-1BLOCK\s0 \s-1LIST\s0" 4
 276 .IX Item "apply BLOCK LIST"
 277 Applies \s-1BLOCK\s0 to each item in \s-1LIST\s0 and returns a list of the values after \s-1BLOCK\s0
 278 has been applied. In scalar context, the last element is returned.  This
 279 function is similar to \f(CW\*(C`map\*(C'\fR but will not modify the elements of the input
 280 list:
 281 .Sp
 282 .Vb 7
 283 \&    my @list = (1 .. 4);
 284 \&    my @mult = apply { $_ *= 2 } @list;
 285 \&    print "\e@list = @list\en";
 286 \&    print "\e@mult = @mult\en";
 287 \&    __END__
 288 \&    @list = 1 2 3 4
 289 \&    @mult = 2 4 6 8
 290 .Ve
 291 .Sp
 292 Think of it as syntactic sugar for
 293 .Sp
 294 .Vb 1
 295 \&    for (my @mult = @list) { $_ *= 2 }
 296 .Ve
 297 .IP "after \s-1BLOCK\s0 \s-1LIST\s0" 4
 298 .IX Item "after BLOCK LIST"
 299 Returns a list of the values of \s-1LIST\s0 after (and not including) the point
 300 where \s-1BLOCK\s0 returns a true value. Sets \f(CW$_\fR for each element in \s-1LIST\s0 in turn.
 301 .Sp
 302 .Vb 1
 303 \&    @x = after { $_ % 5 == 0 } (1..9);    # returns 6, 7, 8, 9
 304 .Ve
 305 .IP "after_incl \s-1BLOCK\s0 \s-1LIST\s0" 4
 306 .IX Item "after_incl BLOCK LIST"
 307 Same as \f(CW\*(C`after\*(C'\fR but also inclues the element for which \s-1BLOCK\s0 is true.
 308 .IP "before \s-1BLOCK\s0 \s-1LIST\s0" 4
 309 .IX Item "before BLOCK LIST"
 310 Returns a list of values of \s-1LIST\s0 upto (and not including) the point where \s-1BLOCK\s0
 311 returns a true value. Sets \f(CW$_\fR for each element in \s-1LIST\s0 in turn.
 312 .IP "before_incl \s-1BLOCK\s0 \s-1LIST\s0" 4
 313 .IX Item "before_incl BLOCK LIST"
 314 Same as \f(CW\*(C`before\*(C'\fR but also includes the element for which \s-1BLOCK\s0 is true.
 315 .IP "indexes \s-1BLOCK\s0 \s-1LIST\s0" 4
 316 .IX Item "indexes BLOCK LIST"
 317 Evaluates \s-1BLOCK\s0 for each element in \s-1LIST\s0 (assigned to \f(CW$_\fR) and returns a list
 318 of the indices of those elements for which \s-1BLOCK\s0 returned a true value. This is
 319 just like \f(CW\*(C`grep\*(C'\fR only that it returns indices instead of values:
 320 .Sp
 321 .Vb 1
 322 \&    @x = indexes { $_ % 2 == 0 } (1..10);   # returns 1, 3, 5, 7, 9
 323 .Ve
 324 .IP "firstval \s-1BLOCK\s0 \s-1LIST\s0" 4
 325 .IX Item "firstval BLOCK LIST"
 326 .PD 0
 327 .IP "first_value \s-1BLOCK\s0 \s-1LIST\s0" 4
 328 .IX Item "first_value BLOCK LIST"
 329 .PD
 330 Returns the first element in \s-1LIST\s0 for which \s-1BLOCK\s0 evaluates to true. Each
 331 element of \s-1LIST\s0 is set to \f(CW$_\fR in turn. Returns \f(CW\*(C`undef\*(C'\fR if no such element
 332 has been found.
 333 .Sp
 334 \&\f(CW\*(C`first_val\*(C'\fR is an alias for \f(CW\*(C`firstval\*(C'\fR.
 335 .IP "lastval \s-1BLOCK\s0 \s-1LIST\s0" 4
 336 .IX Item "lastval BLOCK LIST"
 337 .PD 0
 338 .IP "last_value \s-1BLOCK\s0 \s-1LIST\s0" 4
 339 .IX Item "last_value BLOCK LIST"
 340 .PD
 341 Returns the last value in \s-1LIST\s0 for which \s-1BLOCK\s0 evaluates to true. Each element
 342 of \s-1LIST\s0 is set to \f(CW$_\fR in turn. Returns \f(CW\*(C`undef\*(C'\fR if no such element has been
 343 found.
 344 .Sp
 345 \&\f(CW\*(C`last_val\*(C'\fR is an alias for \f(CW\*(C`lastval\*(C'\fR.
 346 .IP "pairwise \s-1BLOCK\s0 \s-1ARRAY1\s0 \s-1ARRAY2\s0" 4
 347 .IX Item "pairwise BLOCK ARRAY1 ARRAY2"
 348 Evaluates \s-1BLOCK\s0 for each pair of elements in \s-1ARRAY1\s0 and \s-1ARRAY2\s0 and returns a
 349 new list consisting of \s-1BLOCK\s0's return values. The two elements are set to \f(CW$a\fR
 350 and \f(CW$b\fR.  Note that those two are aliases to the original value so changing
 351 them will modify the input arrays.
 352 .Sp
 353 .Vb 3
 354 \&    @a = (1 .. 5);
 355 \&    @b = (11 .. 15);
 356 \&    @x = pairwise { $a + $b } @a, @b;   # returns 12, 14, 16, 18, 20
 357 .Ve
 358 .Sp
 359 .Vb 4
 360 \&    # mesh with pairwise
 361 \&    @a = qw/a b c/;
 362 \&    @b = qw/1 2 3/;
 363 \&    @x = pairwise { ($a, $b) } @a, @b;  # returns a, 1, b, 2, c, 3
 364 .Ve
 365 .IP "each_array \s-1ARRAY1\s0 \s-1ARRAY2\s0 ..." 4
 366 .IX Item "each_array ARRAY1 ARRAY2 ..."
 367 Creates an array iterator to return the elements of the list of arrays \s-1ARRAY1\s0,
 368 \&\s-1ARRAY2\s0 throughout ARRAYn in turn.  That is, the first time it is called, it
 369 returns the first element of each array.  The next time, it returns the second
 370 elements.  And so on, until all elements are exhausted.
 371 .Sp
 372 This is useful for looping over more than one array at once:
 373 .Sp
 374 .Vb 2
 375 \&    my $ea = each_array(@a, @b, @c);
 376 \&    while ( my ($a, $b, $c) = $ea\->() )   { .... }
 377 .Ve
 378 .Sp
 379 The iterator returns the empty list when it reached the end of all arrays.
 380 .Sp
 381 If the iterator is passed an argument of '\f(CW\*(C`index\*(C'\fR', then it retuns
 382 the index of the last fetched set of values, as a scalar.
 383 .IP "each_arrayref \s-1LIST\s0" 4
 384 .IX Item "each_arrayref LIST"
 385 Like each_array, but the arguments are references to arrays, not the
 386 plain arrays.
 387 .IP "natatime \s-1BLOCK\s0 \s-1LIST\s0" 4
 388 .IX Item "natatime BLOCK LIST"
 389 Creates an array iterator, for looping over an array in chunks of
 390 \&\f(CW$n\fR items at a time.  (n at a time, get it?).  An example is
 391 probably a better explanation than I could give in words.
 392 .Sp
 393 Example:
 394 .Sp
 395 .Vb 6
 396 \&    my @x = ('a' .. 'g');
 397 \&    my $it = natatime 3, @x;
 398 \&    while (my @vals = $it\->())
 399 \&    {
 400 \&        print "@vals\en";
 401 \&    }
 402 .Ve
 403 .Sp
 404 This prints
 405 .Sp
 406 .Vb 3
 407 \&    a b c
 408 \&    d e f
 409 \&    g
 410 .Ve
 411 .IP "mesh \s-1ARRAY1\s0 \s-1ARRAY2\s0 [ \s-1ARRAY3\s0 ... ]" 4
 412 .IX Item "mesh ARRAY1 ARRAY2 [ ARRAY3 ... ]"
 413 .PD 0
 414 .IP "zip \s-1ARRAY1\s0 \s-1ARRAY2\s0 [ \s-1ARRAY3\s0 ... ]" 4
 415 .IX Item "zip ARRAY1 ARRAY2 [ ARRAY3 ... ]"
 416 .PD
 417 Returns a list consisting of the first elements of each array, then
 418 the second, then the third, etc, until all arrays are exhausted.
 419 .Sp
 420 Examples:
 421 .Sp
 422 .Vb 3
 423 \&    @x = qw/a b c d/;
 424 \&    @y = qw/1 2 3 4/;
 425 \&    @z = mesh @x, @y;       # returns a, 1, b, 2, c, 3, d, 4
 426 .Ve
 427 .Sp
 428 .Vb 4
 429 \&    @a = ('x');
 430 \&    @b = ('1', '2');
 431 \&    @c = qw/zip zap zot/;
 432 \&    @d = mesh @a, @b, @c;   # x, 1, zip, undef, 2, zap, undef, undef, zot
 433 .Ve
 434 .Sp
 435 \&\f(CW\*(C`zip\*(C'\fR is an alias for \f(CW\*(C`mesh\*(C'\fR.
 436 .IP "uniq \s-1LIST\s0" 4
 437 .IX Item "uniq LIST"
 438 Returns a new list by stripping duplicate values in \s-1LIST\s0. The order of
 439 elements in the returned list is the same as in \s-1LIST\s0. In scalar context,
 440 returns the number of unique elements in \s-1LIST\s0.
 441 .Sp
 442 .Vb 2
 443 \&    my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
 444 \&    my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
 445 .Ve
 446 .IP "minmax \s-1LIST\s0" 4
 447 .IX Item "minmax LIST"
 448 Calculates the minimum and maximum of \s-1LIST\s0 and returns a two element list with
 449 the first element being the minimum and the second the maximum. Returns the empty
 450 list if \s-1LIST\s0 was empty.
 451 .Sp
 452 The minmax algorithm differs from a naive iteration over the list where each element
 453 is compared to two values being the so far calculated min and max value in that it
 454 only requires 3n/2 \- 2 comparisons. Thus it is the most efficient possible algorithm.
 455 .Sp
 456 However, the Perl implementation of it has some overhead simply due to the fact
 457 that there are more lines of Perl code involved. Therefore, \s-1LIST\s0 needs to be
 458 fairly big in order for minmax to win over a naive implementation. This
 459 limitation does not apply to the \s-1XS\s0 version.
 460 .IP "part \s-1BLOCK\s0 \s-1LIST\s0" 4
 461 .IX Item "part BLOCK LIST"
 462 Partitions \s-1LIST\s0 based on the return value of \s-1BLOCK\s0 which denotes into which partition
 463 the current value is put.
 464 .Sp
 465 Returns a list of the partitions thusly created. Each partition created is a
 466 reference to an array.
 467 .Sp
 468 .Vb 2
 469 \&    my $i = 0;
 470 \&    my @part = part { $i++ % 2 } 1 .. 8;   # returns [1, 3, 5, 7], [2, 4, 6, 8]
 471 .Ve
 472 .Sp
 473 You can have a sparse list of partitions as well where non-set partitions will
 474 be undef:
 475 .Sp
 476 .Vb 1
 477 \&    my @part = part { 2 } 1 .. 10;          # returns undef, undef, [ 1 .. 10 ]
 478 .Ve
 479 .Sp
 480 Be careful with negative values, though:
 481 .Sp
 482 .Vb 3
 483 \&    my @part = part { \-1 } 1 .. 10;
 484 \&    __END__
 485 \&    Modification of non\-creatable array value attempted, subscript \-1 ...
 486 .Ve
 487 .Sp
 488 Negative values are only ok when they refer to a partition previously created:
 489 .Sp
 490 .Vb 3
 491 \&    my @idx = (0, 1, \-1);
 492 \&    my $i = 0;
 493 \&    my @part = part { $idx[$++ % 3] } 1 .. 8;   # [1, 4, 7], [2, 3, 5, 6, 8]
 494 .Ve
 495 .SH "EXPORTS"
 496 .IX Header "EXPORTS"
 497 Nothing by default. To import all of this module's symbols, do the conventional
 498 .PP
 499 .Vb 1
 500 \&    use List::MoreUtils qw/:all/;
 501 .Ve
 502 .PP
 503 It may make more sense though to only import the stuff your program actually needs:
 504 .PP
 505 .Vb 1
 506 \&    use List::MoreUtils qw/any firstidx/;
 507 .Ve
 508 .SH "ENVIRONMENT"
 509 .IX Header "ENVIRONMENT"
 510 When \f(CW\*(C`LIST_MOREUTILS_PP\*(C'\fR is set, the module will always use the pure-Perl
 511 implementation and not the \s-1XS\s0 one. This environment variable is really just
 512 there for the test-suite to force testing the Perl implementation, and possibly
 513 for reporting of bugs. I don't see any reason to use it in a production
 514 environment.
 515 .SH "VERSION"
 516 .IX Header "VERSION"
 517 This is version 0.22.
 518 .SH "BUGS"
 519 .IX Header "BUGS"
 520 There is a problem with a bug in 5.6.x perls. It is a syntax error to write
 521 things like:
 522 .PP
 523 .Vb 1
 524 \&    my @x = apply { s/foo/bar/ } qw/foo bar baz/;
 525 .Ve
 526 .PP
 527 It has to be written as either
 528 .PP
 529 .Vb 1
 530 \&    my @x = apply { s/foo/bar/ } 'foo', 'bar', 'baz';
 531 .Ve
 532 .PP
 533 or
 534 .PP
 535 .Vb 1
 536 \&    my @x = apply { s/foo/bar/ } my @dummy = qw/foo bar baz/;
 537 .Ve
 538 .PP
 539 Perl5.5.x and perl5.8.x don't suffer from this limitation.
 540 .PP
 541 If you have a functionality that you could imagine being in this module, please
 542 drop me a line. This module's policy will be less strict than \f(CW\*(C`List::Util\*(C'\fR's when
 543 it comes to additions as it isn't a core module.
 544 .PP
 545 When you report bugs, it would be nice if you could additionally give me the
 546 output of your program with the environment variable \f(CW\*(C`LIST_MOREUTILS_PP\*(C'\fR set
 547 to a true value. That way I know where to look for the problem (in \s-1XS\s0,
 548 pure-Perl or possibly both).
 549 .SH "THANKS"
 550 .IX Header "THANKS"
 551 Credits go to a number of people: Steve Purkis for giving me namespace advice
 552 and James Keenan and Terrence Branno for their effort of keeping the \s-1CPAN\s0
 553 tidier by making List::Utils obsolete.
 554 .PP
 555 Brian McCauley suggested the inclusion of \fIapply()\fR and provided the pure-Perl
 556 implementation for it.
 557 .PP
 558 Eric J. Roode asked me to add all functions from his module \f(CW\*(C`List::MoreUtil\*(C'\fR
 559 into this one. With minor modifications, the pure-Perl implementations of those
 560 are by him.
 561 .PP
 562 The bunch of people who almost immediately pointed out the many problems with
 563 the glitchy 0.07 release (Slaven Rezic, Ron Savage, \s-1CPAN\s0 testers).
 564 .PP
 565 A particularly nasty memory leak was spotted by Thomas A. Lowery.
 566 .PP
 567 Lars Thegler made me aware of problems with older Perl versions.
 568 .PP
 569 Anno Siegel de-orphaned \fIeach_arrayref()\fR.
 570 .PP
 571 David Filmer made me aware of a problem in each_arrayref that could ultimately
 572 lead to a segfault.
 573 .PP
 574 Ricardo Signes suggested the inclusion of \fIpart()\fR and provided the
 575 Perl\-implementation.
 576 .PP
 577 Robin Huston kindly fixed a bug in perl's \s-1MULTICALL\s0 \s-1API\s0 to make the
 578 XS-implementation of \fIpart()\fR work.
 579 .SH "TODO"
 580 .IX Header "TODO"
 581 A pile of requests from other people is still pending further processing in my
 582 mailbox. This includes:
 583 .IP "* uniq_by(&@)" 4
 584 .IX Item "uniq_by(&@)"
 585 Use code-reference to extract a key based on which the uniqueness is
 586 determined. Suggested by Aaron Crane.
 587 .IP "* delete_index" 4
 588 .IX Item "delete_index"
 589 .PD 0
 590 .IP "* random_item" 4
 591 .IX Item "random_item"
 592 .IP "* random_item_delete_index" 4
 593 .IX Item "random_item_delete_index"
 594 .IP "* list_diff_hash" 4
 595 .IX Item "list_diff_hash"
 596 .IP "* list_diff_inboth" 4
 597 .IX Item "list_diff_inboth"
 598 .IP "* list_diff_infirst" 4
 599 .IX Item "list_diff_infirst"
 600 .IP "* list_diff_insecond" 4
 601 .IX Item "list_diff_insecond"
 602 .PD
 603 These were all suggested by Dan Muey.
 604 .IP "* listify" 4
 605 .IX Item "listify"
 606 Always return a flat list when either a simple scalar value was passed or an array\-reference.
 607 Suggested by Mark Summersault.
 608 .SH "SEE ALSO"
 609 .IX Header "SEE ALSO"
 610 List::Util
 611 .SH "AUTHOR"
 612 .IX Header "AUTHOR"
 613 Tassilo von Parseval, <tassilo.von.parseval@rwth\-aachen.de>
 614 .SH "COPYRIGHT AND LICENSE"
 615 .IX Header "COPYRIGHT AND LICENSE"
 616 Copyright (C) 2004\-2006 by Tassilo von Parseval
 617 .PP
 618 This library is free software; you can redistribute it and/or modify
 619 it under the same terms as Perl itself, either Perl version 5.8.4 or,
 620 at your option, any later version of Perl 5 you may have available.