[RFC v3 3/4] manual: Document streq,memeq,wcseq,wmemeq,strcaseeq,wcscaseeq APIs

[Alejandro Colomar]

The *eq_l() variants remain undocumented, just like their *cmp_l()
counterparts.

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 manual/string.texi | 176 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 168 insertions(+), 8 deletions(-)

diff --git a/manual/string.texi b/manual/string.texi
index feba0b7ae3..998895f6e5 100644
--- a/manual/string.texi
+++ b/manual/string.texi
@@ -15,7 +15,7 @@ become familiar with the library functions and to make use of them,
 since this offers benefits in maintenance, efficiency, and portability.
 
 For instance, you could easily compare one string to another in two
-lines of C code, but if you use the built-in @code{strcmp} function,
+lines of C code, but if you use the built-in @code{streq} function,
 you're less likely to make a mistake.  And, since these library
 functions are typically highly optimized, your program may run faster
 too.
@@ -1209,8 +1209,8 @@ such as @code{strdup} or @code{asprintf} to construct strings.
 @cindex predicates on arrays
 
 You can use the functions in this section to perform comparisons on the
-contents of strings and arrays.  As well as checking for equality, these
-functions can also be used as the ordering functions for sorting
+contents of strings and arrays.
+These functions can be used as the ordering functions for sorting
 operations.  @xref{Searching and Sorting}, for an example of this.
 
 Unlike most comparison operations in C, the string comparison functions
@@ -1221,8 +1221,8 @@ negative value indicates that the first string is ``less'' than the
 second, while a positive value indicates that the first string is
 ``greater''.
 
-The most common use of these functions is to check only for equality.
-This is canonically done with an expression like @w{@samp{! strcmp (s1, s2)}}.
+For determining if two strings are equal,
+there are other functions which are more appropriate.
 
 All of these functions are declared in the header file @file{string.h}.
 @pindex string.h
@@ -1253,8 +1253,7 @@ If the contents of the two blocks are equal, @code{wmemcmp} returns
 @code{0}.
 @end deftypefun
 
-On arbitrary arrays, the @code{memcmp} function is mostly useful for
-testing equality.  It usually isn't meaningful to do byte-wise ordering
+It usually isn't meaningful to do byte-wise ordering
 comparisons on arrays of things other than bytes.  For example, a
 byte-wise comparison on the bytes that make up floating-point numbers
 isn't likely to tell you anything about the relationship between the
@@ -1514,6 +1513,166 @@ strverscmp ("foo.009", "foo.0")
 This is an obsolete alias for @code{memcmp}, derived from BSD.
 @end deftypefun
 
+@node String/Array Equality
+@section String/Array Equality
+@cindex string equality functions
+@cindex array equality functions
+
+You can use the functions in this section
+to check strings and arrays for equality.
+These functions return a boolean value
+indicating equality of both inputs.
+
+Some of these functions are declared in the header file @file{string.h},
+and others are declared in the header file @file{strings.h}.
+@pindex string.h
+@pindex strings.h
+
+@deftypefun bool memeq (const void *@var{a1}, const void *@var{a2}, size_t @var{size})
+@standards{GNU, string.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{memeq} determines
+whether the @var{size} bytes of memory beginning at @var{a1}
+and the @var{size} bytes of memory beginning at @var{a2}
+are equal.
+
+If and only if the contents of the two blocks are equal,
+@code{memeq} returns @code{true}.
+
+You should be careful about using @code{memeq} to compare objects
+that can contain ``holes'', such as the padding inserted into structure
+objects to enforce alignment requirements, extra space at the end of
+unions, and extra bytes at the ends of strings whose length is less
+than their allocated size.  The contents of these ``holes'' are
+indeterminate and may cause strange behavior when performing byte-wise
+comparisons.  For more predictable results, perform an explicit
+component-wise comparison.
+
+For example, given a structure type definition like:
+
+@smallexample
+struct foo
+  @{
+    unsigned char tag;
+    union
+      @{
+        double f;
+        long i;
+        char *p;
+      @} value;
+  @};
+@end smallexample
+
+@noindent
+you are better off writing a specialized comparison function to compare
+@code{struct foo} objects instead of comparing them with @code{memeq}.
+
+@noindent
+@code{memeq} is a GNU extension.
+@end deftypefun
+
+@deftypefun bool wmemeq (const wchar_t *@var{a1}, const wchar_t *@var{a2}, size_t @var{size})
+@standards{GNU, wchar.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The function @code{wmemeq} determines
+whether the @var{size} wide characters beginning at @var{a1}
+and the @var{size} wide characters beginning at @var{a2}
+aer equal.
+
+If and only if the contents of the two blocks are equal,
+@code{wmemeq} returns @code{true}.
+
+@code{wmemeq} is really only useful to compare arrays of type
+@code{wchar_t} since the function looks at @code{sizeof (wchar_t)} bytes
+at a time and this number of bytes is system dependent.
+
+@noindent
+@code{wmemeq} is a GNU extension.
+@end deftypefun
+
+@deftypefun bool streq (const char *@var{s1}, const char *@var{s2})
+@standards{GNU, string.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{streq} function determines
+whether the strings @var{s1} and @var{s2} are equal.
+
+If and only if the two strings are equal,
+@code{streq} returns @code{true}.
+
+@code{streq} does not take sorting conventions
+of the language the strings are written in
+into account.
+
+@noindent
+@code{streq} is a GNU extension.
+@end deftypefun
+
+@deftypefun bool wcseq (const wchar_t *@var{ws1}, const wchar_t *@var{ws2})
+@standards{GNU, wchar.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The @code{wcseq} function determines
+whether the wide strings @var{ws1} and @var{ws2} are equal.
+
+If and only if the two strings are equal,
+@code{wcseq} returns @code{true}.
+
+@code{wcseq} does not take sorting conventions
+of the language the strings are written in
+into account.
+
+@noindent
+@code{wcseq} is a GNU extension.
+@end deftypefun
+
+@deftypefun bool strcaseeq (const char *@var{s1}, const char *@var{s2})
+@standards{GNU, strings.h}
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function is like @code{streq},
+except that differences in case are ignored,
+and its arguments must be multibyte strings.
+How uppercase and lowercase characters are related
+is determined by the currently selected locale.
+In the standard @code{"C"} locale,
+the characters @"A and @"a do not match,
+but in a locale which regards these characters as parts of the alphabet,
+they do match.
+
+@noindent
+@code{strcaseeq} is a GNU extension.
+@end deftypefun
+
+@deftypefun bool wcscaseeq (const wchar_t *@var{ws1}, const wchar_t *@var{ws2})
+@standards{GNU, wchar.h}
+@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
+This function is like @code{wcseq},
+except that differences in case are ignored.
+How uppercase and lowercase characters are related
+is determined by the currently selected locale.
+In the standard @code{"C"} locale,
+the characters @"A and @"a do not match,
+but in a locale which regards these characters as parts of the alphabet,
+they do match.
+
+@noindent
+@code{wcscaseeq} is a GNU extension.
+@end deftypefun
+
+Here are some examples showing the use of @code{streq}
+(equivalent examples can be constructed
+for the wide character functions).
+
+@smallexample
+streq ("hello", "hello")
+    @result{} true    /* @r{These two strings are the same.} */
+streq ("hello", "Hello")
+    @result{} false
+streq ("hello", "world")
+    @result{} false
+streq ("hello", "hello, world")
+    @result{} false
+@end smallexample
+
 @node Collation Functions
 @section Collation Functions
 
@@ -1996,7 +2155,7 @@ name originally used in the X/Open Portability Guide before the
 @c There may be multiple calls of strncasecmp, each accessing the locale
 @c object independently.
 This is like @code{strstr}, except that it ignores case in searching for
-the substring.   Like @code{strcasecmp}, it is locale dependent how
+the substring.   Like @code{strcaseeq}, it is locale dependent how
 uppercase and lowercase characters are related, and arguments are
 multibyte strings.
 
@@ -2993,3 +3152,4 @@ The @code{envz_remove} function removes an entry named @var{name} from
 
 @c FIXME this are undocumented:
 @c strcasecmp_l @safety{@mtsafe{}@assafe{}@acsafe{}} see strcasecmp
+@c strcaseeq_l @safety{@mtsafe{}@assafe{}@acsafe{}} see strcaseeq
-- 
2.50.1