(grow_heap): When growing bail even if new_size is negative.
[kopensolaris-gnu/glibc.git] / manual / ctype.texi
index de90acb..b275a54 100644 (file)
@@ -1,4 +1,4 @@
-@node Character Handling, String and Array Utilities, Memory Allocation, Top
+@node Character Handling, String and Array Utilities, Memory, Top
 @c %MENU% Character testing and conversion functions
 @chapter Character Handling
 
@@ -17,7 +17,7 @@ by the locale currently selected for character classification---the
 
 The @w{ISO C} standard specifies two different sets of functions.  The
 one set works on @code{char} type characters, the other one on
-@code{wchar_t} wide character (@pxref{Extended Char Intro}).
+@code{wchar_t} wide characters (@pxref{Extended Char Intro}).
 
 @menu
 * Classification of Characters::       Testing whether characters are
@@ -159,10 +159,10 @@ vertical tab
 
 @cindex blank character
 @comment ctype.h
-@comment GNU
+@comment ISO
 @deftypefun int isblank (int @var{c})
 Returns true if @var{c} is a blank character; that is, a space or a tab.
-This function is a GNU extension.
+This function was originally a GNU extension, but was added in @w{ISO C99}.
 @end deftypefun
 
 @cindex graphic character
@@ -265,34 +265,35 @@ with the SVID.
 @node Classification of Wide Characters, Using Wide Char Classes, Case Conversion, Character Handling
 @section Character class determination for wide characters
 
-The second amendment to @w{ISO C89} defines functions to classify wide
-character.  Although the original @w{ISO C89} standard already defined
-the type @code{wchar_t} but no functions operating on them were defined.
+@w{Amendment 1} to @w{ISO C90} defines functions to classify wide
+characters.  Although the original @w{ISO C90} standard already defined
+the type @code{wchar_t}, no functions operating on them were defined.
 
 The general design of the classification functions for wide characters
-is more general.  It allows to extend the set of available
-classification beyond the set which is always available.  The POSIX
-standard specifies a way how the extension can be done and this is
-already implemented in the GNU C library implementation of the
-@code{localedef} program.
-
-The character class functions are normally implemented using bitsets.
-I.e., for the character in question the appropriate bitset is read from
-a table and a test is performed whether a certain bit is set in this
-bitset.  Which bit is tested for is determined by the class.
+is more general.  It allows extensions to the set of available
+classifications, beyond those which are always available.  The POSIX
+standard specifies how extensions can be made, and this is already
+implemented in the GNU C library implementation of the @code{localedef}
+program.
+
+The character class functions are normally implemented with bitsets,
+with a bitset per character.  For a given character, the appropriate
+bitset is read from a table and a test is performed as to whether a
+certain bit is set.  Which bit is tested for is determined by the
+class.
 
 For the wide character classification functions this is made visible.
-There is a type representing the classification, a function to retrieve
-this value for a specific class, and a function to test using the
-classification value whether a given character is in this class.  On top
-of this the normal character classification functions as used for
+There is a type classification type defined, a function to retrieve this
+value for a given class, and a function to test whether a given
+character is in this class, using the classification value.  On top of
+this the normal character classification functions as used for
 @code{char} objects can be defined.
 
 @comment wctype.h
 @comment ISO
 @deftp {Data type} wctype_t
 The @code{wctype_t} can hold a value which represents a character class.
-The ony defined way to generate such a value is by using the
+The only defined way to generate such a value is by using the
 @code{wctype} function.
 
 @pindex wctype.h
@@ -305,8 +306,8 @@ This type is defined in @file{wctype.h}.
 The @code{wctype} returns a value representing a class of wide
 characters which is identified by the string @var{property}.  Beside
 some standard properties each locale can define its own ones.  In case
-no property with the given name is known for the current locale for the
-@code{LC_CTYPE} category the function returns zero.
+no property with the given name is known for the current locale
+selected for the @code{LC_CTYPE} category, the function returns zero.
 
 @noindent
 The properties known in every locale are:
@@ -338,11 +339,11 @@ by a successful call to @code{wctype}.
 This function is declared in @file{wctype.h}.
 @end deftypefun
 
-The make it easier to use the commonly used classification functions
+To make it easier to use the commonly-used classification functions,
 they are defined in the C library.  There is no need to use
-@code{wctype} is the property string is one of the known character
+@code{wctype} if the property string is one of the known character
 classes.  In some situations it is desirable to construct the property
-string and then it gets important that @code{wctype} can also handle the
+strings, and then it is important that @code{wctype} can also handle the
 standard classes.
 
 @cindex alphanumeric character
@@ -362,7 +363,7 @@ iswctype (wc, wctype ("alnum"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex alphabetic character
@@ -386,7 +387,7 @@ iswctype (wc, wctype ("alpha"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex control character
@@ -404,7 +405,7 @@ iswctype (wc, wctype ("cntrl"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex digit character
@@ -419,7 +420,7 @@ wide characters:
 
 @smallexample
 n = 0;
-while (iswctype (*wc))
+while (iswdigit (*wc))
   @{
     n *= 10;
     n += *wc++ - L'0';
@@ -434,7 +435,7 @@ iswctype (wc, wctype ("digit"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex graphic character
@@ -453,7 +454,7 @@ iswctype (wc, wctype ("graph"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex lower-case character
@@ -471,7 +472,7 @@ iswctype (wc, wctype ("lower"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex printing character
@@ -489,7 +490,7 @@ iswctype (wc, wctype ("print"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex punctuation character
@@ -508,7 +509,7 @@ iswctype (wc, wctype ("punct"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex whitespace character
@@ -547,7 +548,7 @@ iswctype (wc, wctype ("space"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex upper-case character
@@ -565,7 +566,7 @@ iswctype (wc, wctype ("upper"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
 @cindex hexadecimal digit character
@@ -585,35 +586,35 @@ iswctype (wc, wctype ("xdigit"))
 @end smallexample
 
 @pindex wctype.h
-This function is declared in @file{wctype.h}.
+It is declared in @file{wctype.h}.
 @end deftypefun
 
-The GNu C library provides also a function which is not defined in the
+The GNU C library also provides a function which is not defined in the
 @w{ISO C} standard but which is available as a version for single byte
 characters as well.
 
 @cindex blank character
 @comment wctype.h
-@comment GNU
+@comment ISO
 @deftypefun int iswblank (wint_t @var{wc})
 Returns true if @var{wc} is a blank character; that is, a space or a tab.
-This function is a GNU extension.  It is declared in @file{wchar.h}.
+This function was originally a GNU extension, but was added in @w{ISO C99}.
+It is declared in @file{wchar.h}.
 @end deftypefun
 
 @node Using Wide Char Classes, Wide Character Case Conversion, Classification of Wide Characters, Character Handling
 @section Notes on using the wide character classes
 
-The first note is probably nothing astonishing but still occasionally a
+The first note is probably not astonishing but still occasionally a
 cause of problems.  The @code{isw@var{XXX}} functions can be implemented
 using macros and in fact, the GNU C library does this.  They are still
 available as real functions but when the @file{wctype.h} header is
-included the macros will be used.  This is nothing new compared to the
+included the macros will be used.  This is the same as the
 @code{char} type versions of these functions.
 
-The second notes covers something which is new.  It can be best
-illustrated by a (real-world) example.  The first piece of code is an
-excerpt from the original code.  It is truncated a bit but the intention
-should be clear.
+The second note covers something new.  It can be best illustrated by a
+(real-world) example.  The first piece of code is an excerpt from the
+original code.  It is truncated a bit but the intention should be clear.
 
 @smallexample
 int
@@ -625,13 +626,13 @@ is_in_class (int c, const char *class)
     return isalpha (c);
   if (strcmp (class, "cntrl") == 0)
     return iscntrl (c);
-  ...
+  @dots{}
   return 0;
 @}
 @end smallexample
 
-Now with the @code{wctype} and @code{iswctype} one could avoid the
-@code{if} cascades.  But rewriting the code as follows is wrong:
+Now, with the @code{wctype} and @code{iswctype} you can avoid the
+@code{if} cascades, but rewriting the code as follows is wrong:
 
 @smallexample
 int
@@ -642,9 +643,9 @@ is_in_class (int c, const char *class)
 @}
 @end smallexample
 
-The problem is that it is not guarateed that the wide character
+The problem is that it is not guaranteed that the wide character
 representation of a single-byte character can be found using casting.
-In fact, usually this fails miserably.  The correct solution for this
+In fact, usually this fails miserably.  The correct solution to this
 problem is to write the code as follows:
 
 @smallexample
@@ -656,11 +657,11 @@ is_in_class (int c, const char *class)
 @}
 @end smallexample
 
-See @xref{Converting a Character} for more information on @code{btowc}.
-Please note that this change probably does not improve the performance
+@xref{Converting a Character}, for more information on @code{btowc}.
+Note that this change probably does not improve the performance
 of the program a lot since the @code{wctype} function still has to make
-the string comparisons.  But it gets really interesting if the
-@code{is_in_class} function would be called more than once using the
+the string comparisons.  It gets really interesting if the
+@code{is_in_class} function is called more than once for the
 same class name.  In this case the variable @var{desc} could be computed
 once and reused for all the calls.  Therefore the above form of the
 function is probably not the final one.
@@ -669,18 +670,17 @@ function is probably not the final one.
 @node Wide Character Case Conversion, , Using Wide Char Classes, Character Handling
 @section Mapping of wide characters.
 
-As for the classification functions the @w{ISO C} standard also
-generalizes the mapping functions.  Instead of only allowing the two
-standard mappings the locale can contain others.  Again, the
-@code{localedef} program already supports generating such locale data
-files.
+The classification functions are also generalized by the @w{ISO C}
+standard.  Instead of just allowing the two standard mappings, a
+locale can contain others.  Again, the @code{localedef} program
+already supports generating such locale data files.
 
 @comment wctype.h
 @comment ISO
 @deftp {Data Type} wctrans_t
 This data type is defined as a scalar type which can hold a value
 representing the locale-dependent character mapping.  There is no way to
-construct such a value beside using the return value of the
+construct such a value apart from using the return value of the
 @code{wctrans} function.
 
 @pindex wctype.h
@@ -690,11 +690,11 @@ This type is defined in @file{wctype.h}.
 
 @comment wctype.h
 @comment ISO
-@deftypefun wctrans_t wctrans (const char *@var{property}
+@deftypefun wctrans_t wctrans (const char *@var{property})
 The @code{wctrans} function has to be used to find out whether a named
 mapping is defined in the current locale selected for the
-@code{LC_CTYPE} category.  If the returned value is non-zero it can
-afterwards be used in calls to @code{towctrans}.  If the return value is
+@code{LC_CTYPE} category.  If the returned value is non-zero, you can use
+it afterwards in calls to @code{towctrans}.  If the return value is
 zero no such mapping is known in the current locale.
 
 Beside locale-specific mappings there are two mappings which are
@@ -707,15 +707,15 @@ guaranteed to be available in every locale:
 
 @pindex wctype.h
 @noindent
-This function is declared in @file{wctype.h}.
+These functions are declared in @file{wctype.h}.
 @end deftypefun
 
 @comment wctype.h
 @comment ISO
 @deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc})
-The @code{towctrans} function maps the input character @var{wc}
-according to the rules of the mapping for which @var{desc} is an
-descriptor and returns the so found value.  The @var{desc} value must be
+@code{towctrans} maps the input character @var{wc}
+according to the rules of the mapping for which @var{desc} is a
+descriptor, and returns the value it finds.  @var{desc} must be
 obtained by a successful call to @code{wctrans}.
 
 @pindex wctype.h
@@ -723,8 +723,8 @@ obtained by a successful call to @code{wctrans}.
 This function is declared in @file{wctype.h}.
 @end deftypefun
 
-The @w{ISO C} standard also defines for the generally available mappings
-convenient shortcuts so that it is not necesary to call @code{wctrans}
+For the generally available mappings, the @w{ISO C} standard defines
+convenient shortcuts so that it is not necessary to call @code{wctrans}
 for them.
 
 @comment wctype.h
@@ -734,6 +734,13 @@ If @var{wc} is an upper-case letter, @code{towlower} returns the corresponding
 lower-case letter.  If @var{wc} is not an upper-case letter,
 @var{wc} is returned unchanged.
 
+@noindent
+@code{towlower} can be implemented using
+
+@smallexample
+towctrans (wc, wctrans ("tolower"))
+@end smallexample
+
 @pindex wctype.h
 @noindent
 This function is declared in @file{wctype.h}.
@@ -745,12 +752,19 @@ This function is declared in @file{wctype.h}.
 If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding
 upper-case letter.  Otherwise @var{wc} is returned unchanged.
 
+@noindent
+@code{towupper} can be implemented using
+
+@smallexample
+towctrans (wc, wctrans ("toupper"))
+@end smallexample
+
 @pindex wctype.h
 @noindent
 This function is declared in @file{wctype.h}.
 @end deftypefun
 
 The same warnings given in the last section for the use of the wide
-character classiffication function applies here.  It is not possible to
+character classification functions apply here.  It is not possible to
 simply cast a @code{char} type value to a @code{wint_t} and use it as an
-argument for @code{towctrans} calls.
+argument to @code{towctrans} calls.