=encoding euc-jp

=head1 NAME

=begin original

List::Util - A selection of general-utility list subroutines

=end original

List::Util - 一般的に有用なリストサブルーチン集

=head1 SYNOPSIS

    use List::Util qw(first max maxstr min minstr reduce shuffle sum);

=head1 DESCRIPTION

=begin original

C<List::Util> contains a selection of subroutines that people have
expressed would be nice to have in the perl core, but the usage would
not really be high enough to warrant the use of a keyword, and the size
so small such that being individual extensions would be wasteful.

=end original

C<List::Util> は、人々が perl コアにあればいいのにと表明するけれども、
キーワードの使用を保証し、独立した拡張にするのが無駄なほどサイズが小さい、と
いうほど実際の使用頻度が高くないサブルーチン集です。

=begin original

By default C<List::Util> does not export any subroutines. The
subroutines defined are

=end original

デフォルトでは C<List::Util> は何のサブルーチンもエクスポートしません。
定義されているサブルーチンは:

=over 4

=item first BLOCK LIST

=begin original

Similar to C<grep> in that it evaluates BLOCK setting C<$_> to each element
of LIST in turn. C<first> returns the first element where the result from
BLOCK is a true value. If BLOCK never returns true or LIST was empty then
C<undef> is returned.

=end original

LIST のそれぞれの要素を順に C<$_> 設定して BLOCK を評価するという意味で
C<grep> と似ています。
C<first> は、BLOCK の結果が真の値になった最初の値を返します。
BLOCK が真を返さなかったり、LIST が空の場合は、C<undef> が返されます。

    $foo = first { defined($_) } @list    # first defined value in @list
    $foo = first { $_ > $value } @list    # first value in @list which
                                          # is greater than $value

=begin original

This function could be implemented using C<reduce> like this

=end original

この関数は、C<reduce> を使って次のようにして実装できます:

    $foo = reduce { defined($a) ? $a : wanted($b) ? $b : undef } undef, @list

=begin original

for example wanted() could be defined() which would return the first
defined value in @list

=end original

例えば、wanted() が defined() なら @list の中で最初の定義された値を返します。

=item max LIST

=begin original

Returns the entry in the list with the highest numerical value. If the
list is empty then C<undef> is returned.

=end original

リストのエントリの中で最大の数値を返します。
リストが空の場合、C<undef> が返されます。

    $foo = max 1..10                # 10
    $foo = max 3,9,12               # 12
    $foo = max @bar, @baz           # whatever

=begin original

This function could be implemented using C<reduce> like this

=end original

この関数は、C<reduce> を使って次のようにして実装できます:

    $foo = reduce { $a > $b ? $a : $b } 1..10

=item maxstr LIST

=begin original

Similar to C<max>, but treats all the entries in the list as strings
and returns the highest string as defined by the C<gt> operator.
If the list is empty then C<undef> is returned.

=end original

C<max> と同様ですが、リストの中の全てのエントリを文字列として扱い、
C<gt> 演算子で定義される最大の文字列を返します。
リストが空の場合、C<undef> が返されます。

    $foo = maxstr 'A'..'Z'          # 'Z'
    $foo = maxstr "hello","world"   # "world"
    $foo = maxstr @bar, @baz        # whatever

=begin original

This function could be implemented using C<reduce> like this

=end original

この関数は、C<reduce> を使って次のようにして実装できます:

    $foo = reduce { $a gt $b ? $a : $b } 'A'..'Z'

=item min LIST

=begin original

Similar to C<max> but returns the entry in the list with the lowest
numerical value. If the list is empty then C<undef> is returned.

=end original

C<max> と同様ですが、リストのエントリの中で最小の数値を返します。
リストが空の場合、C<undef> が返されます。

    $foo = min 1..10                # 1
    $foo = min 3,9,12               # 3
    $foo = min @bar, @baz           # whatever

=begin original

This function could be implemented using C<reduce> like this

=end original

この関数は、C<reduce> を使って次のようにして実装できます:

    $foo = reduce { $a < $b ? $a : $b } 1..10

=item minstr LIST

=begin original

Similar to C<min>, but treats all the entries in the list as strings
and returns the lowest string as defined by the C<lt> operator.
If the list is empty then C<undef> is returned.

=end original

C<min> と同様ですが、リストの中の全てのエントリを文字列として扱い、
C<lt> 演算子で定義される最小の文字列を返します。
リストが空の場合、C<undef> が返されます。

    $foo = minstr 'A'..'Z'          # 'A'
    $foo = minstr "hello","world"   # "hello"
    $foo = minstr @bar, @baz        # whatever

=begin original

This function could be implemented using C<reduce> like this

=end original

この関数は、C<reduce> を使って次のようにして実装できます:

    $foo = reduce { $a lt $b ? $a : $b } 'A'..'Z'

=item reduce BLOCK LIST

=begin original

Reduces LIST by calling BLOCK, in a scalar context, multiple times,
setting C<$a> and C<$b> each time. The first call will be with C<$a>
and C<$b> set to the first two elements of the list, subsequent
calls will be done by setting C<$a> to the result of the previous
call and C<$b> to the next element in the list.

=end original

BLOCK をスカラコンテキストで複数回、毎回 C<$a> と C<$b> を設定して
呼び出すことで LIST を縮小(reduce)します。
最初の呼び出しでは C<$a> と C<$b> はリストの最初の二つの要素を設定し、
引き続く呼び出しでは C<$a> に前回の呼び出しの結果を、
C<$b> にリストの次の要素を設定して呼び出します。

=begin original

Returns the result of the last call to BLOCK. If LIST is empty then
C<undef> is returned. If LIST only contains one element then that
element is returned and BLOCK is not executed.

=end original

BLOCK の最後の呼び出しの結果を返します。
LIST が空の場合、C<undef> が返されます。
LIST が 1 要素しか持たない場合、その要素が返され、BLOCK は実行されません。

    $foo = reduce { $a < $b ? $a : $b } 1..10       # min
    $foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # minstr
    $foo = reduce { $a + $b } 1 .. 10               # sum
    $foo = reduce { $a . $b } @bar                  # concat

=begin original

If your algorithm requires that C<reduce> produce an identity value, then
make sure that you always pass that identity value as the first argument to prevent
C<undef> being returned

=end original

C<reduce> が単位元を出力することがあなたのアルゴリズムにとって必要な場合、
C<undef> を返すのを避けるために常に最初の要素として単位元を
渡すようにしてください:

  $foo = reduce { $a + $b } 0, @values;             # sum with 0 identity value

=item shuffle LIST

=begin original

Returns the elements of LIST in a random order

=end original

LIST の要素をランダムな順序で返します:

    @cards = shuffle 0..51      # 0..51 in a random order

=item sum LIST

=begin original

Returns the sum of all the elements in LIST. If LIST is empty then
C<undef> is returned.

=end original

LIST の全ての要素の合計を返します。
LIST が空の場合、C<undef> が返されます。

    $foo = sum 1..10                # 55
    $foo = sum 3,9,12               # 24
    $foo = sum @bar, @baz           # whatever

=begin original

This function could be implemented using C<reduce> like this

=end original

この関数は、C<reduce> を使って次のようにして実装できます:

    $foo = reduce { $a + $b } 1..10

=begin original

If your algorithm requires that C<sum> produce an identity of 0, then
make sure that you always pass C<0> as the first argument to prevent
C<undef> being returned

=end original

C<sum> が単位元の 0 を出力することがあなたのアルゴリズムにとって
必要な場合、
C<undef> を返すのを避けるために常に最初の要素として C<0> を
渡すようにしてください:

  $foo = sum 0, @values;

=back

=head1 KNOWN BUGS

(既知のバグ)

=begin original

With perl versions prior to 5.005 there are some cases where reduce
will return an incorrect result. This will show up as test 7 of
reduce.t failing.

=end original

バージョン 5.005 より前の perl では、場合によっては reduce が
間違った結果を返すことがありました。
これは reduce.t のテスト 7 の失敗として現れます。

=head1 SUGGESTED ADDITIONS

(提案された拡張)

=begin original

The following are additions that have been requested, but I have been reluctant
to add due to them being very simple to implement in perl

=end original

以下のものは要望された拡張ですが、私は追加するのに気乗りしません;
perl で実装するのがとても簡単だからです:

  # One argument is true

  sub any { $_ && return 1 for @_; 0 }

  # All arguments are true

  sub all { $_ || return 0 for @_; 1 }

  # All arguments are false

  sub none { $_ && return 0 for @_; 1 }

  # One argument is false

  sub notall { $_ || return 1 for @_; 0 }

  # How many elements are true

  sub true { scalar grep { $_ } @_ }

  # How many elements are false

  sub false { scalar grep { !$_ } @_ }

=head1 SEE ALSO

L<Scalar::Util>, L<List::MoreUtils>

=head1 COPYRIGHT

Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=begin meta

Translate: Kentaro Shirakata <argrath@ub32.org>
Status: completed

=end meta

=cut