cpan/Scalar-List-Utils/lib/List/Util.pm

   1 # Copyright (c) 1997-2009 Graham Barr <gbarr@pobox.com>. All rights reserved.
   2 # This program is free software; you can redistribute it and/or
   3 # modify it under the same terms as Perl itself.
   4 #
   5 # Maintained since 2013 by Paul Evans <leonerd@leonerd.org.uk>
   6
   7 package List::Util;
   8
   9 use strict;
  10 require Exporter;
  11
  12 our @ISA        = qw(Exporter);
  13 our @EXPORT_OK  = qw(
  14   all any first min max minstr maxstr none notall product reduce sum sum0 shuffle
  15   pairmap pairgrep pairfirst pairs pairkeys pairvalues
  16 );
  17 our $VERSION    = "1.37";
  18 our $XS_VERSION = $VERSION;
  19 $VERSION    = eval $VERSION;
  20
  21 require XSLoader;
  22 XSLoader::load('List::Util', $XS_VERSION);
  23
  24 sub import
  25 {
  26   my $pkg = caller;
  27
  28   # (RT88848) Touch the caller's $a and $b, to avoid the warning of
  29   #   Name "main::a" used only once: possible typo" warning
  30   no strict 'refs';
  31   ${"${pkg}::a"} = ${"${pkg}::a"};
  32   ${"${pkg}::b"} = ${"${pkg}::b"};
  33
  34   goto &Exporter::import;
  35 }
  36
  37 1;
  38
  39 __END__
  40
  41 =head1 NAME
  42
  43 List::Util - A selection of general-utility list subroutines
  44
  45 =head1 SYNOPSIS
  46
  47     use List::Util qw(first max maxstr min minstr reduce shuffle sum);
  48
  49 =head1 DESCRIPTION
  50
  51 C<List::Util> contains a selection of subroutines that people have expressed
  52 would be nice to have in the perl core, but the usage would not really be high
  53 enough to warrant the use of a keyword, and the size so small such that being
  54 individual extensions would be wasteful.
  55
  56 By default C<List::Util> does not export any subroutines.
  57
  58 =cut
  59
  60 =head1 LIST-REDUCTION FUNCTIONS
  61
  62 The following set of functions all reduce a list down to a single value.
  63
  64 =cut
  65
  66 =head2 $result = reduce { BLOCK } @list
  67
  68 Reduces C<@list> by calling C<BLOCK> in a scalar context multiple times,
  69 setting C<$a> and C<$b> each time. The first call will be with C<$a> and C<$b>
  70 set to the first two elements of the list, subsequent calls will be done by
  71 setting C<$a> to the result of the previous call and C<$b> to the next element
  72 in the list.
  73
  74 Returns the result of the last call to the C<BLOCK>. If C<@list> is empty then
  75 C<undef> is returned. If C<@list> only contains one element then that element
  76 is returned and C<BLOCK> is not executed.
  77
  78 The following examples all demonstrate how C<reduce> could be used to implement
  79 the other list-reduction functions in this module. (They are not in fact
  80 implemented like this, but instead in a more efficient manner in individual C
  81 functions).
  82
  83     $foo = reduce { defined($a)            ? $a :
  84                     $code->(local $_ = $b) ? $b :
  85                                              undef } undef, @list # first
  86
  87     $foo = reduce { $a > $b ? $a : $b } 1..10       # max
  88     $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'   # maxstr
  89     $foo = reduce { $a < $b ? $a : $b } 1..10       # min
  90     $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
  91     $foo = reduce { $a + $b } 1 .. 10               # sum
  92     $foo = reduce { $a . $b } @bar                  # concat
  93
  94     $foo = reduce { $a || $code->(local $_ = $b) } 0, @bar   # any
  95     $foo = reduce { $a && $code->(local $_ = $b) } 1, @bar   # all
  96     $foo = reduce { $a && !$code->(local $_ = $b) } 1, @bar  # none
  97     $foo = reduce { $a || !$code->(local $_ = $b) } 0, @bar  # notall
  98        # Note that these implementations do not fully short-circuit
  99
 100 If your algorithm requires that C<reduce> produce an identity value, then make
 101 sure that you always pass that identity value as the first argument to prevent
 102 C<undef> being returned
 103
 104   $foo = reduce { $a + $b } 0, @values;             # sum with 0 identity value
 105
 106 The remaining list-reduction functions are all specialisations of this generic
 107 idea.
 108
 109 =head2 $b = any { BLOCK } @list
 110
 111 Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element
 112 of C<@list> in turn. C<any> returns true if any element makes the C<BLOCK>
 113 return a true value. If C<BLOCK> never returns true or C<@list> was empty then
 114 it returns false.
 115
 116 Many cases of using C<grep> in a conditional can be written using C<any>
 117 instead, as it can short-circuit after the first true result.
 118
 119     if( any { length > 10 } @strings ) {
 120         # at least one string has more than 10 characters
 121     }
 122
 123 =head2 $b = all { BLOCK } @list
 124
 125 Similar to C<any>, except that it requires all elements of the C<@list> to make
 126 the C<BLOCK> return true. If any element returns false, then it returns false.
 127 If the C<BLOCK> never returns false or the C<@list> was empty then it returns
 128 true.
 129
 130 =head2 $b = none { BLOCK } @list
 131
 132 =head2 $b = notall { BLOCK } @list
 133
 134 Similar to C<any> and C<all>, but with the return sense inverted. C<none>
 135 returns true only if no value in the LIST causes the BLOCK to return true, and
 136 C<notall> returns true only if not all of the values do.
 137
 138 =head2 $val = first { BLOCK } @list
 139
 140 Similar to C<grep> in that it evaluates C<BLOCK> setting C<$_> to each element
 141 of C<@list> in turn. C<first> returns the first element where the result from
 142 C<BLOCK> is a true value. If C<BLOCK> never returns true or C<@list> was empty
 143 then C<undef> is returned.
 144
 145     $foo = first { defined($_) } @list    # first defined value in @list
 146     $foo = first { $_ > $value } @list    # first value in @list which
 147                                           # is greater than $value
 148
 149 =head2 $num = max @list
 150
 151 Returns the entry in the list with the highest numerical value. If the list is
 152 empty then C<undef> is returned.
 153
 154     $foo = max 1..10                # 10
 155     $foo = max 3,9,12               # 12
 156     $foo = max @bar, @baz           # whatever
 157
 158 =head2 $str = maxstr @list
 159
 160 Similar to C<max>, but treats all the entries in the list as strings and
 161 returns the highest string as defined by the C<gt> operator. If the list is
 162 empty then C<undef> is returned.
 163
 164     $foo = maxstr 'A'..'Z'          # 'Z'
 165     $foo = maxstr "hello","world"   # "world"
 166     $foo = maxstr @bar, @baz        # whatever
 167
 168 =head2 $num = min @list
 169
 170 Similar to C<max> but returns the entry in the list with the lowest numerical
 171 value. If the list is empty then C<undef> is returned.
 172
 173     $foo = min 1..10                # 1
 174     $foo = min 3,9,12               # 3
 175     $foo = min @bar, @baz           # whatever
 176
 177 =head2 $str = minstr @list
 178
 179 Similar to C<min>, but treats all the entries in the list as strings and
 180 returns the lowest string as defined by the C<lt> operator. If the list is
 181 empty then C<undef> is returned.
 182
 183     $foo = minstr 'A'..'Z'          # 'A'
 184     $foo = minstr "hello","world"   # "hello"
 185     $foo = minstr @bar, @baz        # whatever
 186
 187 =head2 $num = product @list
 188
 189 Returns the numerical product of all the elements in C<@list>. If C<@list> is
 190 empty then C<1> is returned.
 191
 192     $foo = product 1..10            # 3628800
 193     $foo = product 3,9,12           # 324
 194
 195 =head2 $num_or_undef = sum @list
 196
 197 Returns the numerical sum of all the elements in C<@list>. For backwards
 198 compatibility, if C<@list> is empty then C<undef> is returned.
 199
 200     $foo = sum 1..10                # 55
 201     $foo = sum 3,9,12               # 24
 202     $foo = sum @bar, @baz           # whatever
 203
 204 =head2 $num = sum0 @list
 205
 206 Similar to C<sum>, except this returns 0 when given an empty list, rather than
 207 C<undef>.
 208
 209 =cut
 210
 211 =head1 KEY/VALUE PAIR LIST FUNCTIONS
 212
 213 The following set of functions, all inspired by L<List::Pairwise>, consume an
 214 even-sized list of pairs. The pairs may be key/value associations from a hash,
 215 or just a list of values. The functions will all preserve the original ordering
 216 of the pairs, and will not be confused by multiple pairs having the same "key"
 217 value - nor even do they require that the first of each pair be a plain string.
 218
 219 =cut
 220
 221 =head2 @kvlist = pairgrep { BLOCK } @kvlist
 222
 223 =head2 $count = pairgrep { BLOCK } @kvlist
 224
 225 Similar to perl's C<grep> keyword, but interprets the given list as an
 226 even-sized list of pairs. It invokes the C<BLOCK> multiple times, in scalar
 227 context, with C<$a> and C<$b> set to successive pairs of values from the
 228 C<@kvlist>.
 229
 230 Returns an even-sized list of those pairs for which the C<BLOCK> returned true
 231 in list context, or the count of the B<number of pairs> in scalar context.
 232 (Note, therefore, in scalar context that it returns a number half the size of
 233 the count of items it would have returned in list context).
 234
 235     @subset = pairgrep { $a =~ m/^[[:upper:]]+$/ } @kvlist
 236
 237 As with C<grep> aliasing C<$_> to list elements, C<pairgrep> aliases C<$a> and
 238 C<$b> to elements of the given list. Any modifications of it by the code block
 239 will be visible to the caller.
 240
 241 =head2 ( $key, $val ) = pairfirst { BLOCK } @kvlist
 242
 243 =head2 $found = pairfirst { BLOCK } @kvlist
 244
 245 Similar to the C<first> function, but interprets the given list as an
 246 even-sized list of pairs. It invokes the C<BLOCK> multiple times, in scalar
 247 context, with C<$a> and C<$b> set to successive pairs of values from the
 248 C<@kvlist>.
 249
 250 Returns the first pair of values from the list for which the C<BLOCK> returned
 251 true in list context, or an empty list of no such pair was found. In scalar
 252 context it returns a simple boolean value, rather than either the key or the
 253 value found.
 254
 255     ( $key, $value ) = pairfirst { $a =~ m/^[[:upper:]]+$/ } @kvlist
 256
 257 As with C<grep> aliasing C<$_> to list elements, C<pairfirst> aliases C<$a> and
 258 C<$b> to elements of the given list. Any modifications of it by the code block
 259 will be visible to the caller.
 260
 261 =head2 @list = pairmap { BLOCK } @kvlist
 262
 263 =head2 $count = pairmap { BLOCK } @kvlist
 264
 265 Similar to perl's C<map> keyword, but interprets the given list as an
 266 even-sized list of pairs. It invokes the C<BLOCK> multiple times, in list
 267 context, with C<$a> and C<$b> set to successive pairs of values from the
 268 C<@kvlist>.
 269
 270 Returns the concatenation of all the values returned by the C<BLOCK> in list
 271 context, or the count of the number of items that would have been returned in
 272 scalar context.
 273
 274     @result = pairmap { "The key $a has value $b" } @kvlist
 275
 276 As with C<map> aliasing C<$_> to list elements, C<pairmap> aliases C<$a> and
 277 C<$b> to elements of the given list. Any modifications of it by the code block
 278 will be visible to the caller.
 279
 280 =head2 @pairs = pairs @kvlist
 281
 282 A convenient shortcut to operating on even-sized lists of pairs, this function
 283 returns a list of ARRAY references, each containing two items from the given
 284 list. It is a more efficient version of
 285
 286     @pairs = pairmap { [ $a, $b ] } @kvlist
 287
 288 It is most convenient to use in a C<foreach> loop, for example:
 289
 290     foreach ( pairs @KVLIST ) {
 291        my ( $key, $value ) = @$_;
 292        ...
 293     }
 294
 295 =head2 @keys = pairkeys @kvlist
 296
 297 A convenient shortcut to operating on even-sized lists of pairs, this function
 298 returns a list of the the first values of each of the pairs in the given list.
 299 It is a more efficient version of
 300
 301     @keys = pairmap { $a } @kvlist
 302
 303 =head2 @values = pairvalues @kvlist
 304
 305 A convenient shortcut to operating on even-sized lists of pairs, this function
 306 returns a list of the the second values of each of the pairs in the given list.
 307 It is a more efficient version of
 308
 309     @values = pairmap { $b } @kvlist
 310
 311 =cut
 312
 313 =head1 OTHER FUNCTIONS
 314
 315 =cut
 316
 317 =head2 @values = shuffle @values
 318
 319 Returns the values of the input in a random order
 320
 321     @cards = shuffle 0..51      # 0..51 in a random order
 322
 323 =cut
 324
 325 =head1 KNOWN BUGS
 326
 327 With perl versions prior to 5.005 there are some cases where reduce will return
 328 an incorrect result. This will show up as test 7 of reduce.t failing.
 329
 330 =head1 SUGGESTED ADDITIONS
 331
 332 The following are additions that have been requested, but I have been reluctant
 333 to add due to them being very simple to implement in perl
 334
 335   # How many elements are true
 336
 337   sub true { scalar grep { $_ } @_ }
 338
 339   # How many elements are false
 340
 341   sub false { scalar grep { !$_ } @_ }
 342
 343 =head1 SEE ALSO
 344
 345 L<Scalar::Util>, L<List::MoreUtils>
 346
 347 =head1 COPYRIGHT
 348
 349 Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
 350 This program is free software; you can redistribute it and/or
 351 modify it under the same terms as Perl itself.
 352
 353 Recent additions and current maintenance by
 354 Paul Evans, <leonerd@leonerd.org.uk>.
 355
 356 =cut