chiark - git - mdw - mLib/blob - versioncmp.3

   1 .\" -*-nroff-*-
   2 .TH versioncmp 3 "6 January 2007" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 versioncmp \- compare Debian-format version numbers
   5 .\" @versioncmp
   6 .SH SYNOPSIS
   7 .nf
   8 .B "#include <mLib/versioncmp.h>"
   9
  10 .BI "int versioncmp(const char *" va ", const char *" vb ");"
  11 .fi
  12 .SH DESCRIPTION
  13 The
  14 .B versioncmp
  15 function compares version strings.
  16 .PP
  17 The format of version numbers considered is
  18 .IP
  19 .RI [ epoch
  20 .BR : ]
  21 .I main
  22 .RB [ \-
  23 .IR sub ]
  24 .PP
  25 The
  26 .I main
  27 part may contain colons or hyphens if there is an
  28 .I epoch
  29 or
  30 .IR sub ,
  31 respectively.  Version strings are compared componentwise: first epochs,
  32 then main parts, and finally subparts.
  33 .PP
  34 The component comparison is done as follows.  First, the initial
  35 subsequence of nondigit characters is extracted from each string, and
  36 these are compared lexicographically, using ASCII ordering, except that
  37 letters precede non-letters.  If both are the same, an initial sequence
  38 of digits is extracted from the remaining parts of the version strings,
  39 and these are compared numerically (an empty sequence being considered
  40 to have the value zero).  This process is repeated until we have a
  41 winner or until both strings are exhausted.
  42 .PP
  43 The return value is 0 if the two strings are equal, \-1 if
  44 .I va
  45 is older than
  46 .IR vb ,
  47 or +1 if
  48 .I va
  49 is newer than
  50 .IR vb .
  51 .SH SEE ALSO
  52 .BR mLib (3).
  53 .PP
  54 .IR "Debian Policy Manual" .
  55 .SH AUTHOR
  56 Mark Wooding, <mdw@distorted.org.uk>