From 4a3dfbf40eba25a6d355db2ae5ac721f862a0557 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Fri, 11 Jan 2008 03:42:54 +0100 Subject: [PATCH] Add documentation for the c-* modules. --- ChangeLog | 11 +++++++++++ doc/c-ctype.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++ doc/c-strcase.texi | 29 ++++++++++++++++++++++++++++ doc/c-strcaseeq.texi | 28 +++++++++++++++++++++++++++ doc/c-strcasestr.texi | 27 ++++++++++++++++++++++++++ doc/c-strstr.texi | 24 +++++++++++++++++++++++ doc/c-strtod.texi | 23 ++++++++++++++++++++++ doc/c-strtold.texi | 23 ++++++++++++++++++++++ doc/gnulib.texi | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++ 9 files changed, 265 insertions(+) create mode 100644 doc/c-ctype.texi create mode 100644 doc/c-strcase.texi create mode 100644 doc/c-strcaseeq.texi create mode 100644 doc/c-strcasestr.texi create mode 100644 doc/c-strstr.texi create mode 100644 doc/c-strtod.texi create mode 100644 doc/c-strtold.texi diff --git a/ChangeLog b/ChangeLog index d50d64942..ba7728df2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2008-01-10 Bruno Haible + + * doc/gnulib.texi (String Functions in C Locale): New section. + * doc/c-ctype.texi: New file. + * doc/c-strcase.texi: New file. + * doc/c-strcaseeq.texi: New file. + * doc/c-strcasestr.texi: New file. + * doc/c-strstr.texi: New file. + * doc/c-strtod.texi: New file. + * doc/c-strtold.texi: New file. + 2008-01-10 Eric Blake * lib/relocatable.h: Fix a comment. diff --git a/doc/c-ctype.texi b/doc/c-ctype.texi new file mode 100644 index 000000000..2140b6bd8 --- /dev/null +++ b/doc/c-ctype.texi @@ -0,0 +1,47 @@ +@c Documentation of gnulib module 'c-ctype'. + +@c Copyright (C) 2008 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +The @code{c-ctype} module contains functions operating on single-byte +characters, like the functions in @code{}, that operate as if the +locale encoding was ASCII. (The "C" locale on many systems has the locale +encoding "ASCII".) + +The functions are: +@smallexample +extern bool c_isascii (int c); + +extern bool c_isalnum (int c); +extern bool c_isalpha (int c); +extern bool c_isblank (int c); +extern bool c_iscntrl (int c); +extern bool c_isdigit (int c); +extern bool c_islower (int c); +extern bool c_isgraph (int c); +extern bool c_isprint (int c); +extern bool c_ispunct (int c); +extern bool c_isspace (int c); +extern bool c_isupper (int c); +extern bool c_isxdigit (int c); + +extern int c_tolower (int c); +extern int c_toupper (int c); +@end smallexample + +These functions assign properties only to ASCII characters. + +The @var{c} argument can be a @code{char} or @code{unsigned char} value, +whereas the corresponding functions in @code{} take an argument +that is actually an @code{unsigned char} value. + +The @code{c_is*} functions return @samp{bool}, where the corresponding +functions in @code{} return @samp{int} for historical reasons. + +Note: The @code{} functions support only unibyte locales. diff --git a/doc/c-strcase.texi b/doc/c-strcase.texi new file mode 100644 index 000000000..e14383fd9 --- /dev/null +++ b/doc/c-strcase.texi @@ -0,0 +1,29 @@ +@c Documentation of gnulib module 'c-strcase'. + +@c Copyright (C) 2008 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +The @code{c-strcase} module contains case-insensitive string comparison +functions operating on single-byte character strings, like the functions in +@code{}, that operate as if the locale encoding was ASCII. +(The "C" locale on many systems has the locale encoding "ASCII".) + +The functions are: +@smallexample +extern int c_strcasecmp (const char *s1, const char *s2); +extern int c_strncasecmp (const char *s1, const char *s2, size_t n); +@end smallexample + +For case conversion here, only ASCII characters are considered to be +upper case or lower case. + +Note: The functions @code{strcasecmp}, @code{strncasecmp} from +@code{} support only unibyte locales; for multibyte locales, +you need the functions @code{mbscasecmp}, @code{mbsncasecmp}, +@code{mbspcasecmp}. diff --git a/doc/c-strcaseeq.texi b/doc/c-strcaseeq.texi new file mode 100644 index 000000000..42e23600d --- /dev/null +++ b/doc/c-strcaseeq.texi @@ -0,0 +1,28 @@ +@c Documentation of gnulib module 'c-strcaseeq'. + +@c Copyright (C) 2008 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +The @code{c-strcaseeq} module contains an optimized case-insensitive +string comparison function operating on single-byte character strings, that +operate as if the locale encoding was ASCII. +(The "C" locale on many systems has the locale encoding "ASCII".) + +The functions is actually implemented as a macro: +@smallexample +extern int STRCASEEQ (const char *s1, const char *s2, + int s20, int s21, int s22, int s23, int s24, int s25, + int s26, int s27, int s28); +@end smallexample + +@var{s2} should be a short literal ASCII string, and @var{s20}, @var{s21}, ... +the individual characters of @var{s2}. + +For case conversion here, only ASCII characters are considered to be +upper case or lower case. diff --git a/doc/c-strcasestr.texi b/doc/c-strcasestr.texi new file mode 100644 index 000000000..5ff1f88b9 --- /dev/null +++ b/doc/c-strcasestr.texi @@ -0,0 +1,27 @@ +@c Documentation of gnulib module 'c-strcasestr'. + +@c Copyright (C) 2008 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +The @code{c-strcasestr} module contains a case-insensitive string search +function operating on single-byte character strings, that operate as if the +locale encoding was ASCII. +(The "C" locale on many systems has the locale encoding "ASCII".) + +The function is: +@smallexample +extern char *c_strcasestr (const char *haystack, const char *needle); +@end smallexample + +For case conversion here, only ASCII characters are considered to be +upper case or lower case. + +Note: The function @code{strcasestr} from @code{} supports only +unibyte locales; for multibyte locales, you need the function +@code{mbscasestr}. diff --git a/doc/c-strstr.texi b/doc/c-strstr.texi new file mode 100644 index 000000000..08a672864 --- /dev/null +++ b/doc/c-strstr.texi @@ -0,0 +1,24 @@ +@c Documentation of gnulib module 'c-strstr'. + +@c Copyright (C) 2008 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +The @code{c-strstr} module contains a substring search function operating +on single-byte character strings, that operate as if the locale encoding +was ASCII. +(The "C" locale on many systems has the locale encoding "ASCII".) + +The function is: +@smallexample +extern char *c_strstr (const char *haystack, const char *needle); +@end smallexample + +Note: The function @code{strstr} from @code{} supports only +unibyte locales; for multibyte locales, you need the function +@code{mbsstr}. diff --git a/doc/c-strtod.texi b/doc/c-strtod.texi new file mode 100644 index 000000000..f4f196f56 --- /dev/null +++ b/doc/c-strtod.texi @@ -0,0 +1,23 @@ +@c Documentation of gnulib module 'c-strtod'. + +@c Copyright (C) 2008 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +The @code{c-strtod} module contains a string to number (@samp{double}) +conversion function operating on single-byte character strings, that operates +as if the locale encoding was ASCII. +(The "C" locale on many systems has the locale encoding "ASCII".) + +The function is: +@smallexample +extern double c_strtod (const char *string, char **endp); +@end smallexample + +In particular, only a period @samp{.} is accepted as decimal point, even +when the current locale's notion of decimal point is a comma @samp{,}. diff --git a/doc/c-strtold.texi b/doc/c-strtold.texi new file mode 100644 index 000000000..70fd7c9c1 --- /dev/null +++ b/doc/c-strtold.texi @@ -0,0 +1,23 @@ +@c Documentation of gnulib module 'c-strtold'. + +@c Copyright (C) 2008 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +The @code{c-strtold} module contains a string to number (@samp{long double}) +conversion function operating on single-byte character strings, that operates +as if the locale encoding was ASCII. +(The "C" locale on many systems has the locale encoding "ASCII".) + +The function is: +@smallexample +extern long double c_strtold (const char *string, char **endp); +@end smallexample + +In particular, only a period @samp{.} is accepted as decimal point, even +when the current locale's notion of decimal point is a comma @samp{,}. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index deaf52823..e68ca2934 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -2895,6 +2895,7 @@ If you need this particular function, you may write to @menu * alloca:: * alloca-opt:: +* String Functions in C Locale:: * Quoting:: * error and progname:: * gcd:: @@ -2912,6 +2913,58 @@ If you need this particular function, you may write to @findex alloca @include alloca-opt.texi +@node String Functions in C Locale +@section Character and String Functions in C Locale + +The functions in this section are similar to the generic string functions +from the standard C library, except that +@itemize +@item +They behave as if the locale was set to the "C" locale, even when the +locale is different, and/or +@item +They are specially optimized for the case where all characters are plain +ASCII characters. +@end itemize + +@menu +* c-ctype:: +* c-strcase:: +* c-strcaseeq:: +* c-strcasestr:: +* c-strstr:: +* c-strtod:: +* c-strtold:: +@end menu + +@node c-ctype +@subsection c-ctype +@include c-ctype.texi + +@node c-strcase +@subsection c-strcase +@include c-strcase.texi + +@node c-strcaseeq +@subsection c-strcaseeq +@include c-strcaseeq.texi + +@node c-strcasestr +@subsection c-strcasestr +@include c-strcasestr.texi + +@node c-strstr +@subsection c-strstr +@include c-strstr.texi + +@node c-strtod +@subsection c-strtod +@include c-strtod.texi + +@node c-strtold +@subsection c-strtold +@include c-strtold.texi + @include quote.texi @include error.texi @include gcd.texi -- 2.11.0