ext/List/Util/lib/List/Util.pm

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