Merge 'master' into noverlay

1 files changed, 61 insertions, 25 deletions

diff --git a/lib/filevercmp.h b/lib/filevercmp.h
index 25cc6f624cd..57949760b25 100644
--- a/lib/filevercmp.h
+++ b/lib/filevercmp.h
@@ -1,42 +1,78 @@
-/*
+/* Compare file names containing version numbers.
+
    Copyright (C) 1995 Ian Jackson <iwj10@cus.cam.ac.uk>
    Copyright (C) 2001 Anthony Towns <aj@azure.humbug.org.au>
-   Copyright (C) 2008-2017 Free Software Foundation, Inc.
+   Copyright (C) 2008-2022 Free Software Foundation, Inc.
 
-   This program is free software: you can redistribute it and/or modify
-   it under the terms of the GNU General Public License as published by
-   the Free Software Foundation, either version 3 of the License, or
-   (at your option) any later version.
+   This file is free software: you can redistribute it and/or modify
+   it under the terms of the GNU Lesser General Public License as
+   published by the Free Software Foundation, either version 3 of the
+   License, or (at your option) any later version.
 
-   This program is distributed in the hope that it will be useful,
+   This file 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 General Public License for more details.
+   GNU Lesser General Public License for more details.
 
-   You should have received a copy of the GNU General Public License
-   along with this program.  If not, see <https://www.gnu.org/licenses/>. */
+   You should have received a copy of the GNU Lesser General Public License
+   along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
 
 #ifndef FILEVERCMP_H
 #define FILEVERCMP_H
 
-/* Compare version strings:
+#include <stddef.h>
+
+/* Compare strings A and B as file names containing version numbers,
+   and return an integer that is negative, zero, or positive depending
+   on whether A compares less than, equal to, or greater than B.
+
+   Use the following version sort algorithm:
+
+     1. Compare the strings' maximal-length non-digit prefixes lexically.
+        If there is a difference return that difference.
+        Otherwise discard the prefixes and continue with the next step.
+
+     2. Compare the strings' maximal-length digit prefixes, using
+        numeric comparison of the numbers represented by each prefix.
+        (Treat an empty prefix as zero; this can happen only at string end.)
+        If there is a difference, return that difference.
+        Otherwise discard the prefixes and continue with the next step.
+
+     3. If both strings are empty, return 0.  Otherwise continue with step 1.
+
+   In version sort, lexical comparison is left to right, byte by byte,
+   using the byte's numeric value (0-255), except that:
+
+     1. ASCII letters sort before other bytes.
+     2. A tilde sorts before anything, even an empty string.
+
+   In addition to the version sort rules, the following strings have
+   special priority and sort before all other strings (listed in order):
 
-   This function compares strings S1 and S2:
-   1) By PREFIX in the same way as strcmp.
-   2) Then by VERSION (most similarly to version compare of Debian's dpkg).
-      Leading zeros in version numbers are ignored.
-   3) If both (PREFIX and  VERSION) are equal, strcmp function is used for
-      comparison. So this function can return 0 if (and only if) strings S1
-      and S2 are identical.
+     1. The empty string.
+     2. ".".
+     3. "..".
+     4. Strings starting with "." sort before other strings.
 
-   It returns number >0 for S1 > S2, 0 for S1 == S2 and number <0 for S1 < S2.
+   Before comparing two strings where both begin with non-".",
+   or where both begin with "." but neither is "." or "..",
+   suffixes matching the C-locale extended regular expression
+   (\.[A-Za-z~][A-Za-z0-9~]*)*$ are removed and the strings compared
+   without them, using version sort without special priority;
+   if they do not compare equal, this comparison result is used and
+   the suffixes are effectively ignored.  Otherwise, the entire
+   strings are compared using version sort.  When removing a suffix
+   from a nonempty string, remove the maximal-length suffix such that
+   the remaining string is nonempty.
 
-   This function compares strings, in a way that if VER1 and VER2 are version
-   numbers and PREFIX and SUFFIX (SUFFIX defined as (\.[A-Za-z~][A-Za-z0-9~]*)*)
-   are strings then VER1 < VER2 implies filevercmp (PREFIX VER1 SUFFIX,
-   PREFIX VER2 SUFFIX) < 0.
+   This function is intended to be a replacement for strverscmp.  */
+int filevercmp (char const *a, char const *b) _GL_ATTRIBUTE_PURE;
 
-   This function is intended to be a replacement for strverscmp. */
-int filevercmp (const char *s1, const char *s2) _GL_ATTRIBUTE_PURE;
+/* Like filevercmp, except compare the byte arrays A (of length ALEN)
+   and B (of length BLEN) so that A and B can contain '\0', which
+   sorts just before '\1'.  But if ALEN is -1 treat A as a string
+   terminated by '\0', and similarly for BLEN.  */
+int filenvercmp (char const *a, ptrdiff_t alen, char const *b, ptrdiff_t blen)
+  _GL_ATTRIBUTE_PURE;
 
 #endif /* FILEVERCMP_H */