diff options
Diffstat (limited to 'manual/string.texi')
-rw-r--r-- | manual/string.texi | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/manual/string.texi b/manual/string.texi index 8f09ac9728..e358b2015f 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -609,6 +609,56 @@ strncmp ("hello, world", "hello, stupid world!!!", 5) @end smallexample @comment string.h +@comment GNU +@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) +The @code{strverscmp} function compares the string @var{s1} against +@var{s2}, considering them as holding indices/version numbers. Return +value follows the same conventions as found in the @code{strverscmp} +function. In fact, if @var{s1} and @var{s2} contain no digits, +@code{strverscmp} behaves like @code{strcmp}. + +Basically, we compare strings normaly (character by character), until +we find a digit in each string - then we enter a special comparison +mode, where each sequence of digit is taken as a whole. If we reach the +end of these two parts without noticing a difference, we return to the +standard comparison mode. There are two types of numeric parts: +"integral" and "fractionnal" (these laters begins with a '0'). The types +of the numeric parts affect the way we sort them: + +@itemize @bullet +@item +integral/integral: we compare values as you would expect. + +@item +fractionnal/integral: the fractionnal part is less than the integral one. +Again, no surprise. + +@item +fractionnal/fractionnal: the things become a bit more complex. +if the common prefix contains only leading zeroes, the longest part is less +than the other one; else the comparison behaves normaly. +@end itemize + +@smallexample +strverscmp ("no digit", "no digit") + @result{} 0 /* @r{same behaviour as strverscmp.} */ +strverscmp ("item#99", "item#100") + @result{} <0 /* @r{same prefix, but 99 < 100.} */ +strverscmp ("alpha1", "alpha001") + @result{} >0 /* @r{fractionnal part inferior to integral one.} */ +strverscmp ("part1_f012", "part1_f01") + @result{} >0 /* @r{two fractionnal parts.} */ +strverscmp ("foo.009", "foo.0") + @result{} <0 /* @r{idem, but with leading zeroes only.} */ +@end smallexample + +This function is especially usefull when dealing with filename sorting, +because filenames frequently hold indices/version numbers. + +@code{strverscmp} is a GNU extension. +@end deftypefun + +@comment string.h @comment BSD @deftypefun int bcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size}) This is an obsolete alias for @code{memcmp}, derived from BSD. |