lib/filevercmp.h

   1 /* Compare file names containing version numbers.
   2
   3    Copyright (C) 1995 Ian Jackson <iwj10@cus.cam.ac.uk>
   4    Copyright (C) 2001 Anthony Towns <aj@azure.humbug.org.au>
   5    Copyright (C) 2008-2024 Free Software Foundation, Inc.
   6
   7    This file is free software: you can redistribute it and/or modify
   8    it under the terms of the GNU Lesser General Public License as
   9    published by the Free Software Foundation, either version 3 of the
  10    License, or (at your option) any later version.
  11
  12    This file is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU Lesser General Public License for more details.
  16
  17    You should have received a copy of the GNU Lesser General Public License
  18    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  19
  20 #ifndef FILEVERCMP_H
  21 #define FILEVERCMP_H
  22
  23 /* This file uses _GL_ATTRIBUTE_PURE.  */
  24 #if !_GL_CONFIG_H_INCLUDED
  25  #error "Please include config.h first."
  26 #endif
  27
  28 #include <stddef.h>
  29
  30 /* Compare strings A and B as file names containing version numbers,
  31    and return an integer that is negative, zero, or positive depending
  32    on whether A compares less than, equal to, or greater than B.
  33
  34    Use the following version sort algorithm:
  35
  36      1. Compare the strings' maximal-length non-digit prefixes lexically.
  37         If there is a difference return that difference.
  38         Otherwise discard the prefixes and continue with the next step.
  39
  40      2. Compare the strings' maximal-length digit prefixes, using
  41         numeric comparison of the numbers represented by each prefix.
  42         (Treat an empty prefix as zero; this can happen only at string end.)
  43         If there is a difference, return that difference.
  44         Otherwise discard the prefixes and continue with the next step.
  45
  46      3. If both strings are empty, return 0.  Otherwise continue with step 1.
  47
  48    In version sort, lexical comparison is left to right, byte by byte,
  49    using the byte's numeric value (0-255), except that:
  50
  51      1. ASCII letters sort before other bytes.
  52      2. A tilde sorts before anything, even an empty string.
  53
  54    In addition to the version sort rules, the following strings have
  55    special priority and sort before all other strings (listed in order):
  56
  57      1. The empty string.
  58      2. ".".
  59      3. "..".
  60      4. Strings starting with "." sort before other strings.
  61
  62    Before comparing two strings where both begin with non-".",
  63    or where both begin with "." but neither is "." or "..",
  64    suffixes matching the C-locale extended regular expression
  65    (\.[A-Za-z~][A-Za-z0-9~]*)*$ are removed and the strings compared
  66    without them, using version sort without special priority;
  67    if they do not compare equal, this comparison result is used and
  68    the suffixes are effectively ignored.  Otherwise, the entire
  69    strings are compared using version sort.  When removing a suffix
  70    from a nonempty string, remove the maximal-length suffix such that
  71    the remaining string is nonempty.
  72
  73    This function is intended to be a replacement for strverscmp.  */
  74 int filevercmp (char const *a, char const *b) _GL_ATTRIBUTE_PURE;
  75
  76 /* Like filevercmp, except compare the byte arrays A (of length ALEN)
  77    and B (of length BLEN) so that A and B can contain '\0', which
  78    sorts just before '\1'.  But if ALEN is -1 treat A as a string
  79    terminated by '\0', and similarly for BLEN.  */
  80 int filenvercmp (char const *a, ptrdiff_t alen, char const *b, ptrdiff_t blen)
  81   _GL_ATTRIBUTE_PURE;
  82
  83 #endif /* FILEVERCMP_H */