.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Fields 3pm"
.TH Fields 3pm "2008-03-25" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Sort::Fields \- Sort lines containing delimited fields
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Sort::Fields;
\&  @sorted = fieldsort [3, \(aq2n\(aq], @lines;
\&  @sorted = fieldsort \(aq\e+\(aq, [\-1, \-3, 0], @lines;
.Ve
.PP
.Vb 2
\&  $sort_3_2n = make_fieldsort [3, \(aq2n\(aq], @lines;
\&  @sorted = $sort_3_2n\->(@lines);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Sort::Fields provides a general purpose technique for efficiently sorting
lists of lines that contain data separated into fields.
.PP
Sort::Fields automatically imports two subroutines, \f(CW\*(C`fieldsort\*(C'\fR and
\&\f(CW\*(C`make_fieldsort\*(C'\fR, and two variants, \f(CW\*(C`stable_fieldsort\*(C'\fR and 
\&\f(CW\*(C`make_stable_fieldsort\*(C'\fR.  \f(CW\*(C`make_fieldsort\*(C'\fR generates a sorting subroutine
and returns a reference to it.  \f(CW\*(C`fieldsort\*(C'\fR is a wrapper for
the \f(CW\*(C`make_fieldsort\*(C'\fR subroutine.
.PP
The first argument to make_fieldsort is a delimiter string, which is
used as a regular expression argument for a \f(CW\*(C`split\*(C'\fR operator.  The
delimiter string is optional.  If it is not supplied, make_fieldsort
splits each line using \f(CW\*(C`/\es+/\*(C'\fR.
.PP
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 \*(L"1\*(R" indicates the first
field, \*(L"2\*(R" indicates the second, and so on.  A negative specifier
like \*(L"\-2\*(R" means to sort on the second field in reverse (descending)
order.  To indicate a numeric rather than alphabetic comparison,
append \*(L"n\*(R" to the specifier.  A specifier of \*(L"0\*(R" means the entire
string (\*(L"\-0\*(R" means the entire string, in reverse order).
.PP
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.
.PP
\&\f(CW\*(C`fieldsort [1, 2], @data\*(C'\fR is roughly equivalent to
\&\f(CW\*(C`make_fieldsort([1, 2])\->(@data)\*(C'\fR.  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 \f(CW\*(C`make_fieldsort\*(C'\fR
once and reuse the subroutine it returns.
.PP
\&\f(CW\*(C`stable_fieldsort\*(C'\fR and \f(CW\*(C`make_stable_fieldsort\*(C'\fR are like their
\&\*(L"unstable\*(R" counterparts, except that the items that compare the same
are maintained in their original order.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Some sample data (in array \f(CW@data\fR):
.PP
.Vb 8
\&  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
.Ve
.PP
.Vb 2
\&  # alpha sort on column 1
\&  print fieldsort [1], @data;
.Ve
.PP
.Vb 8
\&  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
.Ve
.PP
.Vb 2
\&  # numeric sort on column 1
\&  print fieldsort [\(aq1n\(aq], @data;
.Ve
.PP
.Vb 8
\&  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
.Ve
.PP
.Vb 2
\&  # reverse numeric sort on column 1
\&  print fieldsort [\(aq\-1n\(aq], @data;
.Ve
.PP
.Vb 8
\&  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
.Ve
.PP
.Vb 2
\&  # alpha sort on column 2, then alpha on entire line
\&  print fieldsort [2, 0], @data;
.Ve
.PP
.Vb 8
\&  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
.Ve
.PP
.Vb 3
\&  # alpha sort on column 4, then numeric on column 1, then reverse
\&  # numeric on column 3
\&  print fieldsort [4, \(aq1n\(aq, \(aq\-3n\(aq], @data;
.Ve
.PP
.Vb 8
\&  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
.Ve
.PP
.Vb 4
\&  # 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)
\&  print fieldsort \(aq(?:\e.|\es+)\(aq, [\(aq4n\(aq, \(aq3n\(aq], @data;
.Ve
.PP
.Vb 8
\&  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
.Ve
.PP
.Vb 3
\&  # alpha sort on column 4, then numeric on the entire line
\&  # NOTE: produces warnings under \-w
\&  print fieldsort [4, \(aq0n\(aq], @data;
.Ve
.PP
.Vb 8
\&  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
.Ve
.PP
.Vb 3
\&  # stable alpha sort on column 4 (maintains original relative order
\&  # among items that compare the same)
\&  print stable_fieldsort [4], @data;
.Ve
.PP
.Vb 8
\&  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
.Ve
.SH "BUGS"
.IX Header "BUGS"
Some rudimentary tests now.
.PP
Perhaps something should be done to catch things like:
.PP
.Vb 1
\&  fieldsort \(aq.\(aq, [1, 2], @lines;
.Ve
.PP
\&\f(CW'.'\fR translates to \f(CW\*(C`split /./\*(C'\fR \*(-- probably not what you want.
.PP
Passing blank lines and/or lines containing the wrong kind of
data (alphas instead of numbers) can result in copious warning messages
under \f(CW\*(C`\-w\*(C'\fR.
.PP
If the regexp contains memory parentheses (\f(CW\*(C`(...)\*(C'\fR rather than \f(CW\*(C`(?:...)\*(C'\fR),
split will function in \*(L"delimiter retention\*(R" 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.
.PP
Not really a bug, but if you are planning to sort a large text file,
consider using \fIsort\fR\|(1).  Unless, of course, your operating system
doesn't have \fIsort\fR\|(1).
.SH "AUTHOR"
.IX Header "AUTHOR"
Joseph N. Hall, joseph@5sigma.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1).