.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sort::Key::Multi 3pm"
.TH Sort::Key::Multi 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sort::Key::Multi \- simple multi\-key sorts
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&    use Sort::Key::Multi qw(sikeysort);
\&    my @data = qw(foo0 foo1 bar34 bar0 bar34 bar33 doz4)
\&    my @sisorted = sikeysort { /(\ew+)(\ed+)/} @data;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Sort::Key::Multi creates multi-key sorting subroutines and exports them
to the caller package.
.PP
The names of the sorters are of the form \f(CW\*(C`xxxkeysort\*(C'\fR or
\&\f(CW\*(C`xxxkeysort_inplace\*(C'\fR, where \f(CW\*(C`xxx\*(C'\fR determines the number and types of
the keys as follows:
.Sp
.RS 4
+ \f(CW\*(C`i\*(C'\fR indicates an integer key, \f(CW\*(C`u\*(C'\fR indicates an unsigned integer
key, \f(CW\*(C`n\*(C'\fR indicates a numeric key, \f(CW\*(C`s\*(C'\fR indicates a string key and
\&\f(CW\*(C`l\*(C'\fR indicates a string key that obeys locale order configuration.
.Sp
+ Type characters can be prefixed by \f(CW\*(C`r\*(C'\fR to indicate reverse order.
.Sp
+ A number following a type character indicates that the key type has
to be repeated as many times (for instance \f(CW\*(C`i3\*(C'\fR is equivalent to
\&\f(CW\*(C`iii\*(C'\fR and \f(CW\*(C`rs2\*(C'\fR is equivalent to \f(CW\*(C`rsrs\*(C'\fR).
.Sp
+ Underscores (\f(CW\*(C`_\*(C'\fR) can be freely used between type indicators.
.RE
.PP
For instance:
.PP
.Vb 4
\&   use Key::Sort::Multi qw(iirskeysort
\&                           i2rskeysort
\&                           i_i_rs_\|_keysort
\&                           i2rs_keysort);
.Ve
.PP
exports to the caller package fourth identical sorting functions that
take two integer keys that are sorted in ascending order and one
string key that is sorted in descending order.
.PP
The generated sorters take as first argument a subroutine that is used
to extract the keys from the values which are passed inside \f(CW$_\fR, for
example:
.PP
.Vb 2
\&  my @data = qw(1.3.foo 1.3.bar 2.3.bar 1.4.bar 1.7.foo);
\&  my @s = i2rs_keysort { split /\e./, $_ } @data;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For a more general multi-key sorter generator see Sort::Key::Maker.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2006, 2014 by Salvador Fandiño
<sfandino@yahoo.com>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.4 or,
at your option, any later version of Perl 5 you may have available.