| Current File : //home/strato/chroot/opt/RZperl536/man/man3/Sort::Versions.3 |
.\" Automatically generated by Pod::Man 4.14 (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
..
.\" 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" ''
. 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::Versions 3"
.TH Sort::Versions 3 "2015-12-13" "perl v5.36.1" "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::Versions \- a perl 5 module for sorting of revision\-like numbers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Sort::Versions;
\& @l = sort { versioncmp($a, $b) } qw( 1.2 1.2.0 1.2a.0 1.2.a 1.a 02.a );
\&
\& ...
\&
\& use Sort::Versions;
\& print \*(Aqlower\*(Aq if versioncmp(\*(Aq1.2\*(Aq, \*(Aq1.2a\*(Aq) == \-1;
\&
\& ...
\&
\& use Sort::Versions;
\& %h = (1 => \*(Aqd\*(Aq, 2 => \*(Aqc\*(Aq, 3 => \*(Aqb\*(Aq, 4 => \*(Aqa\*(Aq);
\& @h = sort { versioncmp($h{$a}, $h{$b}) } keys %h;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Sort::Versions allows easy sorting of mixed non-numeric and numeric strings,
like the 'version numbers' that many shared library systems and revision
control packages use. This is quite useful if you are trying to deal with
shared libraries. It can also be applied to applications that intersperse
variable-width numeric fields within text. Other applications can
undoubtedly be found.
.PP
For an explanation of the algorithm, it's simplest to look at these examples:
.PP
.Vb 10
\& 1.1 < 1.2
\& 1.1a < 1.2
\& 1.1 < 1.1.1
\& 1.1 < 1.1a
\& 1.1.a < 1.1a
\& 1 < a
\& a < b
\& 1 < 2
\& 1.1\-3 < 1.1\-4
\& 1.1\-5 < 1.1.6
.Ve
.PP
More precisely (but less comprehensibly), the two strings are treated
as subunits delimited by periods or hyphens. Each subunit can contain
any number of groups of digits or non-digits. If digit groups are
being compared on both sides, a numeric comparison is used, otherwise
a \s-1ASCII\s0 ordering is used. A group or subgroup with more units will win
if all comparisons are equal. A period binds digit groups together
more tightly than a hyphen.
.PP
Some packages use a different style of version numbering: a simple
real number written as a decimal. Sort::Versions has limited support
for this style: when comparing two subunits which are both digit
groups, if either subunit has a leading zero, then both are treated
like digits after a decimal point. So for example:
.PP
.Vb 2
\& 0002 < 1
\& 1.06 < 1.5
.Ve
.PP
This won't always work, because there won't always be a leading zero
in real-number style version numbers. There is no way for
Sort::Versions to know which style was intended. But a lot of the time
it will do the right thing. If you are making up version numbers, the
style with (possibly) more than one dot is the style to use.
.SH "USAGE"
.IX Header "USAGE"
The function \f(CW\*(C`versioncmp()\*(C'\fR takes two arguments and compares them like \f(CW\*(C`cmp\*(C'\fR.
With perl 5.6 or later, you can also use this function directly in sorting:
.PP
.Vb 1
\& @l = sort versioncmp qw(1.1 1.2 1.0.3);
.Ve
.PP
The function \f(CW\*(C`versions()\*(C'\fR can be used directly as a sort function even on
perl 5.005 and earlier, but its use is deprecated.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
version, CPAN::Version which is part of the \s-1CPAN\s0 distribution.
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/neilb/Sort\-Versions>
.SH "AUTHOR"
.IX Header "AUTHOR"
Ed Avis <ed@membled.com> and Matt Johnson <mwj99@doc.ic.ac.uk> for
recent releases; the original author is Kenneth J. Albanowski
<kjahds@kjahds.com>. Thanks to Hack Kampbjørn and Slaven Rezic for
patches and bug reports.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 1996 by Kenneth J. Albanowski.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.