.\" -*-nroff-*-
.\"
.\" Manual for version number comparison
.\"
.\" (c) 2007, 2009, 2020, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH versioncmp 3mLib "6 January 2007" "Straylight/Edgeware" "mLib utilities library"
.\" @versioncmp
.\" @VERSIONCMP
.
.\"--------------------------------------------------------------------------
.SH NAME
versioncmp \- compare Debian-format version numbers
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/versioncmp.h>"
.PP
.BI "int versioncmp(const char *" va ", const char *" vb ");"
.BI "int VERSIONCMP(const char *" va ", " op ", const char *" vb ");"
.fi
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The
.B versioncmp
function compares version strings.
.PP
The format of version numbers considered is
.IP
.RI [ epoch
.BR : ]
.I main
.RB [ \-
.IR sub ]
.PP
The
.I main
part may contain colons or hyphens if there is an
.I epoch
or
.IR sub ,
respectively.  Version strings are compared componentwise: first epochs,
then main parts, and finally subparts.
.PP
The component comparison is done as follows.  First, the initial
subsequence of nondigit characters is extracted from each string, and
these are compared lexicographically, using ASCII ordering, except that
letters precede non-letters.  If both are the same, an initial sequence
of digits is extracted from the remaining parts of the version strings,
and these are compared numerically (an empty sequence being considered
to have the value zero).  This process is repeated until we have a
winner or until both strings are exhausted.
.PP
The return value is 0 if the two strings are equal, \-1 if
.I va
is older than
.IR vb ,
or +1 if
.I va
is newer than
.IR vb .
.PP
The
.B VERSIONCMP
macro provides a more convenient syntax for the
.B versioncmp
function, by allowing a relational operator to be written between the
operands.
.
.\"--------------------------------------------------------------------------
.SH SEE ALSO
.
.BR mLib (3).
.PP
.IR "Debian Policy Manual" .
.
.\"--------------------------------------------------------------------------
.SH AUTHOR
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------