=encoding utf8

=head1 NAME

=begin original

Sort::Fields - Sort lines containing delimited fields

=end original

Sort::Fields - 区切られたフィールドを持つ行のソート

=head1 SYNOPSIS

  use Sort::Fields;
  @sorted = fieldsort [3, '2n'], @lines;
  @sorted = fieldsort '\+', [-1, -3, 0], @lines;

  $sort_3_2n = make_fieldsort [3, '2n'], @lines;
  @sorted = $sort_3_2n->(@lines);

=head1 DESCRIPTION

=begin original

Sort::Fields provides a general purpose technique for efficiently sorting
lists of lines that contain data separated into fields.

=end original

Sort::Fields はフィールドに分割されるデータを格納している行のリストに対する
汎用的で効果的なソートを提供します.

=begin original

Sort::Fields automatically imports two subroutines, C<fieldsort> and
C<make_fieldsort>, and two variants, C<stable_fieldsort> and 
C<make_stable_fieldsort>.  C<make_fieldsort> generates a sorting subroutine
and returns a reference to it.  C<fieldsort> is a wrapper for
the C<make_fieldsort> subroutine.

=end original

Sort::Fields は２つの関数 C<fieldsort> 及び C<make_fieldsort> と, 
その変形２つ C<stable_fieldsort> 及び C<make_stable_fieldsort> を
自動的にインポートします. C<make_fieldsort> はソート関数を生成して
それへのリファレンスを返します. C<fieldsort> は C<make_fieldsort> 
関数に対するラッピングです.

=begin original

The first argument to make_fieldsort is a delimiter string, which is
used as a regular expression argument for a C<split> operator.  The
delimiter string is optional.  If it is not supplied, make_fieldsort
splits each line using C</\s+/>.

=end original

make_fieldsort への１つ目の引数は区切り文字列です. これは C<split> に
渡す正規表現として使われます. 区切り文字列は省略可能です. 
省略時には make_fieldsort は C</\s+/> を使って各行を分割します.

=begin original

The second argument is an array reference containing one or more 
field specifiers.  The specifiers indicate what fields in the strings
will be used to sort the data.  The specifier "1" indicates the first
field, "2" indicates the second, and so on.  A negative specifier
like "-2" means to sort on the second field in reverse (descending)
order.  To indicate a numeric rather than alphabetic comparison,
append "n" to the specifier.  A specifier of "0" means the entire
string ("-0" means the entire string, in reverse order).

=end original

２つ目の引数は１つ以上のフィールド指定子を含んだ配列へのリファレンスです. 
指定子でデータのソートにどのフィールドを使うのかを指示します. 
"1" が最初のフィールド, "2" が２つ目のフィールドです. 負の数の指定, 
例えば "-2" は２番目のフィールドを逆順(降順)でソートすることを
意味します. 文字列比較ではなく数値比較を行うときには指定子に "n" を追加
します. 指定子 "0" は文字列全体を意味します. そして "-0" は文字列全体の
逆順を意味します.

=begin original

The order in which the specifiers appear is the order in which they
will be used to sort the data.  The primary key is first, the secondary
key is second, and so on.

=end original

指定子の指定順がデータのソートに使う順になります. 主キーが１番目, 
２番目のキーが２番目になります.

=begin original

C<fieldsort [1, 2], @data> is roughly equivalent to
C<make_fieldsort([1, 2])-E<gt>(@data)>.  Avoid calling fieldsort repeatedly
with the same sort specifiers.  If you need to use a particular
sort more than once, it is more efficient to call C<make_fieldsort>
once and reuse the subroutine it returns.

=end original

C<fieldsort [1, 2], @data> は C<make_fieldsort([1, 2])-E<gt>(@data)> 
と大体等価です. fieldsort を呼ぶ場合だと, 同じソート指定で繰り返し
呼び出しに手間がかかる程度です. 特定のソート条件で繰り返しソートを
行うのなら, C<make_fieldsort> を一度だけ呼び出し, それで得た関数を
繰り返し使う方が効果的です.

=begin original

C<stable_fieldsort> and C<make_stable_fieldsort> are like their
"unstable" counterparts, except that the items that compare the same
are maintained in their original order.

=end original

C<stable_fieldsort> 及び C<make_stable_fieldsort> はそれぞれの "安定でない" 
ものと同様です. 違いは順序が同位となる要素に対してソートに使ったそのままの
順序が保たれる事です.

=head1 EXAMPLES

(例)

=begin original

Some sample data (in array C<@data>):

=end original

サンプルデータ(C<@data> 配列の中身):

  123   asd   1.22   asdd
  32    ewq   2.32   asdd
  43    rewq  2.12   ewet
  51    erwt  34.2   ewet
  23    erww  4.21   ewet
  91    fdgs  3.43   ewet
  123   refs  3.22   asdd
  123   refs  4.32   asdd

  # alpha sort on column 1
  # 列 1 での文字列ソート
  print fieldsort [1], @data;

  123   asd   1.22   asdd
  123   refs  3.22   asdd
  123   refs  4.32   asdd
  23    erww  4.21   ewet
  32    ewq   2.32   asdd
  43    rewq  2.12   ewet
  51    erwt  34.2   ewet
  91    fdgs  3.43   ewet

  # numeric sort on column 1
  # 列 1 での数値ソート
  print fieldsort ['1n'], @data;

  23    erww  4.21   ewet
  32    ewq   2.32   asdd
  43    rewq  2.12   ewet
  51    erwt  34.2   ewet
  91    fdgs  3.43   ewet
  123   asd   1.22   asdd
  123   refs  3.22   asdd
  123   refs  4.32   asdd

  # reverse numeric sort on column 1
  # 列 1 での逆順数値ソート
  print fieldsort ['-1n'], @data;

  123   asd   1.22   asdd
  123   refs  3.22   asdd
  123   refs  4.32   asdd
  91    fdgs  3.43   ewet
  51    erwt  34.2   ewet
  43    rewq  2.12   ewet
  32    ewq   2.32   asdd
  23    erww  4.21   ewet

  # alpha sort on column 2, then alpha on entire line
  # 列 2 で文字列ソートし, その中で列全体でソート
  print fieldsort [2, 0], @data;

  123   asd   1.22   asdd
  51    erwt  34.2   ewet
  23    erww  4.21   ewet
  32    ewq   2.32   asdd
  91    fdgs  3.43   ewet
  123   refs  3.22   asdd
  123   refs  4.32   asdd
  43    rewq  2.12   ewet

  # alpha sort on column 4, then numeric on column 1, then reverse
  # numeric on column 3
  # 列 4 で文字列ソート, 列 1 で数値ソート, 列 3 で逆順数値ソート
  print fieldsort [4, '1n', '-3n'], @data;

  32    ewq   2.32   asdd
  123   refs  4.32   asdd
  123   refs  3.22   asdd
  123   asd   1.22   asdd
  23    erww  4.21   ewet
  43    rewq  2.12   ewet
  51    erwt  34.2   ewet
  91    fdgs  3.43   ewet

  # now, splitting on either literal period or whitespace
  # sort numeric on column 4 (fractional part of decimals) then
  # numeric on column 3 (whole part of decimals)
  # ピリオドもしくは空白でフィールドを分割
  # 列 4 (数値の小数部分)を数値ソート, 列 3 で数値ソート(整数部分)
  print fieldsort '(?:\.|\s+)', ['4n', '3n'], @data;

  51    erwt  34.2   ewet
  43    rewq  2.12   ewet
  23    erww  4.21   ewet
  123   asd   1.22   asdd
  123   refs  3.22   asdd
  32    ewq   2.32   asdd
  123   refs  4.32   asdd
  91    fdgs  3.43   ewet

  # alpha sort on column 4, then numeric on the entire line
  # NOTE: produces warnings under -w
  # 列 4 で文字列ソート, 列全体で数値ソート
  # 注意: -w 環境下では警告が出力されます
  print fieldsort [4, '0n'], @data;

  32    ewq   2.32   asdd
  123   asd   1.22   asdd
  123   refs  3.22   asdd
  123   refs  4.32   asdd
  23    erww  4.21   ewet
  43    rewq  2.12   ewet
  51    erwt  34.2   ewet
  91    fdgs  3.43   ewet

  # stable alpha sort on column 4 (maintains original relative order
  # among items that compare the same)
  # 列 4 で安定文字列ソート(同位の要素に対して元の前後関係を維持します)
  print stable_fieldsort [4], @data;

  123   asd   1.22   asdd
  32    ewq   2.32   asdd
  123   refs  3.22   asdd
  123   refs  4.32   asdd
  43    rewq  2.12   ewet
  51    erwt  34.2   ewet
  23    erww  4.21   ewet
  91    fdgs  3.43   ewet

=head1 BUGS

(バグ)

=begin original

Some rudimentary tests now.

=end original

基本的なテストを行っています.

=begin original

Perhaps something should be done to catch things like:

=end original

恐らく行っておくべき事は次のような事を捕まえることでしょう:

  fieldsort '.', [1, 2], @lines;

=begin original

C<'.'> translates to C<split /./> -- probably not what you want.

=end original

C<'.'> は C<split /./> となります -- これは恐らく行いたかったことでは
ないでしょう.

=begin original

Passing blank lines and/or lines containing the wrong kind of
data (alphas instead of numbers) can result in copious warning messages
under C<-w>.

=end original

空行を処理したときや間違った種類のデータ(数値のつもりが文字列だった)ときには
C<-w> 環境下ではたくさんの警告メッセージが出てくるでしょう.

=begin original

If the regexp contains memory parentheses (C<(...)> rather than C<(?:...)>),
split will function in "delimiter retention" mode, capturing the
contents of the parentheses as well as the stuff between the delimiters.
I could imagine how this could be useful, but on the other hand I
could also imagine how it could be confusing if encountered unexpectedly.
Caveat sortor.

=end original

正規表現が記憶括弧(C<(?:...)> ではなく C<(...)>)を含んでいるのなら, 
split は "区切り文字保持" モードで機能します. これは括弧の内容を
区切り文字の間の要素と同じように抽出します. これは便利であると同時に, 
意図せずに使ってしまっていたときには混乱を招きます. 
十分に注意してください.

=begin original

Not really a bug, but if you are planning to sort a large text file,
consider using sort(1).  Unless, of course, your operating system
doesn't have sort(1).

=end original

バグではありませんが大きなテキストファイルのソートを行おうとしているのなら, 
sort(1) を使うことを考えた方が良いかもしれません. もちろんあなたのOSが
sort(1) を持っているのならですが.

=head1 AUTHOR

Joseph N. Hall, joseph@5sigma.com


=head1 SEE ALSO

perl(1).