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-2023 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 */