local-lib5/lib/perl5/i486-linux-gnu-thread-multi/List/Util.pm

   1 # List::Util.pm
   2 #
   3 # Copyright (c) 1997-2009 Graham Barr <gbarr@pobox.com>. All rights reserved.
   4 # This program is free software; you can redistribute it and/or
   5 # modify it under the same terms as Perl itself.
   6 #
   7 # This module is normally only loaded if the XS module is not available
   8
   9 package List::Util;
  10
  11 use strict;
  12 use vars qw(@ISA @EXPORT_OK $VERSION $XS_VERSION $TESTING_PERL_ONLY);
  13 require Exporter;
  14
  15 @ISA        = qw(Exporter);
  16 @EXPORT_OK  = qw(first min max minstr maxstr reduce sum shuffle);
  17 $VERSION    = "1.22";
  18 $XS_VERSION = $VERSION;
  19 $VERSION    = eval $VERSION;
  20
  21 eval {
  22   # PERL_DL_NONLAZY must be false, or any errors in loading will just
  23   # cause the perl code to be tested
  24   local $ENV{PERL_DL_NONLAZY} = 0 if $ENV{PERL_DL_NONLAZY};
  25   eval {
  26     require XSLoader;
  27     XSLoader::load('List::Util', $XS_VERSION);
  28     1;
  29   } or do {
  30     require DynaLoader;
  31     local @ISA = qw(DynaLoader);
  32     bootstrap List::Util $XS_VERSION;
  33   };
  34 } unless $TESTING_PERL_ONLY;
  35
  36
  37 if (!defined &sum) {
  38   require List::Util::PP;
  39   List::Util::PP->import;
  40 }
  41
  42 1;
  43
  44 __END__
  45
  46 =head1 NAME
  47
  48 List::Util - A selection of general-utility list subroutines
  49
  50 =head1 SYNOPSIS
  51
  52     use List::Util qw(first max maxstr min minstr reduce shuffle sum);
  53
  54 =head1 DESCRIPTION
  55
  56 C<List::Util> contains a selection of subroutines that people have
  57 expressed would be nice to have in the perl core, but the usage would
  58 not really be high enough to warrant the use of a keyword, and the size
  59 so small such that being individual extensions would be wasteful.
  60
  61 By default C<List::Util> does not export any subroutines. The
  62 subroutines defined are
  63
  64 =over 4
  65
  66 =item first BLOCK LIST
  67
  68 Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
  69 of LIST in turn. C<first> returns the first element where the result from
  70 BLOCK is a true value. If BLOCK never returns true or LIST was empty then
  71 C<undef> is returned.
  72
  73     $foo = first { defined($_) } @list    # first defined value in @list
  74     $foo = first { $_ > $value } @list    # first value in @list which
  75                                           # is greater than $value
  76
  77 This function could be implemented using C<reduce> like this
  78
  79     $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list
  80
  81 for example wanted() could be defined() which would return the first
  82 defined value in @list
  83
  84 =item max LIST
  85
  86 Returns the entry in the list with the highest numerical value. If the
  87 list is empty then C<undef> is returned.
  88
  89     $foo = max 1..10                # 10
  90     $foo = max 3,9,12               # 12
  91     $foo = max @bar, @baz           # whatever
  92
  93 This function could be implemented using C<reduce> like this
  94
  95     $foo = reduce { $a > $b ? $a : $b } 1..10
  96
  97 =item maxstr LIST
  98
  99 Similar to C<max>, but treats all the entries in the list as strings
 100 and returns the highest string as defined by the C<gt> operator.
 101 If the list is empty then C<undef> is returned.
 102
 103     $foo = maxstr 'A'..'Z'          # 'Z'
 104     $foo = maxstr "hello","world"   # "world"
 105     $foo = maxstr @bar, @baz        # whatever
 106
 107 This function could be implemented using C<reduce> like this
 108
 109     $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'
 110
 111 =item min LIST
 112
 113 Similar to C<max> but returns the entry in the list with the lowest
 114 numerical value. If the list is empty then C<undef> is returned.
 115
 116     $foo = min 1..10                # 1
 117     $foo = min 3,9,12               # 3
 118     $foo = min @bar, @baz           # whatever
 119
 120 This function could be implemented using C<reduce> like this
 121
 122     $foo = reduce { $a < $b ? $a : $b } 1..10
 123
 124 =item minstr LIST
 125
 126 Similar to C<min>, but treats all the entries in the list as strings
 127 and returns the lowest string as defined by the C<lt> operator.
 128 If the list is empty then C<undef> is returned.
 129
 130     $foo = minstr 'A'..'Z'          # 'A'
 131     $foo = minstr "hello","world"   # "hello"
 132     $foo = minstr @bar, @baz        # whatever
 133
 134 This function could be implemented using C<reduce> like this
 135
 136     $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'
 137
 138 =item reduce BLOCK LIST
 139
 140 Reduces LIST by calling BLOCK, in a scalar context, multiple times,
 141 setting C<$a> and C<$b> each time. The first call will be with C<$a>
 142 and C<$b> set to the first two elements of the list, subsequent
 143 calls will be done by setting C<$a> to the result of the previous
 144 call and C<$b> to the next element in the list.
 145
 146 Returns the result of the last call to BLOCK. If LIST is empty then
 147 C<undef> is returned. If LIST only contains one element then that
 148 element is returned and BLOCK is not executed.
 149
 150     $foo = reduce { $a < $b ? $a : $b } 1..10       # min
 151     $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
 152     $foo = reduce { $a + $b } 1 .. 10               # sum
 153     $foo = reduce { $a . $b } @bar                  # concat
 154
 155 If your algorithm requires that C<reduce> produce an identity value, then
 156 make sure that you always pass that identity value as the first argument to prevent
 157 C<undef> being returned
 158
 159   $foo = reduce { $a + $b } 0, @values;             # sum with 0 identity value
 160
 161 =item shuffle LIST
 162
 163 Returns the elements of LIST in a random order
 164
 165     @cards = shuffle 0..51      # 0..51 in a random order
 166
 167 =item sum LIST
 168
 169 Returns the sum of all the elements in LIST. If LIST is empty then
 170 C<undef> is returned.
 171
 172     $foo = sum 1..10                # 55
 173     $foo = sum 3,9,12               # 24
 174     $foo = sum @bar, @baz           # whatever
 175
 176 This function could be implemented using C<reduce> like this
 177
 178     $foo = reduce { $a + $b } 1..10
 179
 180 If your algorithm requires that C<sum> produce an identity of 0, then
 181 make sure that you always pass C<0> as the first argument to prevent
 182 C<undef> being returned
 183
 184   $foo = sum 0, @values;
 185
 186 =back
 187
 188 =head1 KNOWN BUGS
 189
 190 With perl versions prior to 5.005 there are some cases where reduce
 191 will return an incorrect result. This will show up as test 7 of
 192 reduce.t failing.
 193
 194 =head1 SUGGESTED ADDITIONS
 195
 196 The following are additions that have been requested, but I have been reluctant
 197 to add due to them being very simple to implement in perl
 198
 199   # One argument is true
 200
 201   sub any { $_ && return 1 for @_; 0 }
 202
 203   # All arguments are true
 204
 205   sub all { $_ || return 0 for @_; 1 }
 206
 207   # All arguments are false
 208
 209   sub none { $_ && return 0 for @_; 1 }
 210
 211   # One argument is false
 212
 213   sub notall { $_ || return 1 for @_; 0 }
 214
 215   # How many elements are true
 216
 217   sub true { scalar grep { $_ } @_ }
 218
 219   # How many elements are false
 220
 221   sub false { scalar grep { !$_ } @_ }
 222
 223 =head1 SEE ALSO
 224
 225 L<Scalar::Util>, L<List::MoreUtils>
 226
 227 =head1 COPYRIGHT
 228
 229 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
 230 This program is free software; you can redistribute it and/or
 231 modify it under the same terms as Perl itself.
 232
 233 =cut