Character Handling
******************

Programs that work with characters and strings often need to classify a character---is it alphabetic, is it a digit, is it whitespace, and so on---and perform case conversion operations on characters.  The functions in the header file ctype.h are provided for this purpose.

Since the choice of locale and character set can alter the classifications of particular character codes, all of these functions are affected by the current locale.  (More precisely, they are affected by the locale currently selected for character classification---the LC_CTYPE category; see Locale Categories.)

Classification of Characters
============================

This section explains the library functions for classifying characters. For example, isalpha is the function to test for an alphabetic character.  It takes one argument, the character to test, and returns a nonzero integer if the character is alphabetic, and zero otherwise.  You would use it like this:

     if (isalpha (c))
       printf ("The character `%c' is alphabetic.\n", c);

Each of the functions in this section tests for membership in a particular class of characters; each has a name starting with is. Each of them takes one argument, which is a character to test, and returns an int which is treated as a boolean value.  The character argument is passed as an int, and it may be the constant value EOF instead of a real character.

The attributes of any given character can vary between locales. See Locales, for more information on locales.

These functions are declared in the header file ctype.h.

 -- Function: int islower (int C)
     Returns true if C is a lower-case letter.

 -- Function: int isupper (int C)
     Returns true if C is an upper-case letter.

 -- Function: int isalpha (int C)
     Returns true if C is an alphabetic character (a letter).  If islower or isupper is true of a character, then isalpha is also true.

     In some locales, there may be additional characters for which isalpha is true--letters which are neither upper case nor lower case.  But in the standard "C" locale, there are no such additional characters.

 -- Function: int isdigit (int C)
     Returns true if C is a decimal digit (0 through 9).

 -- Function: int isalnum (int C)
     Returns true if C is an alphanumeric character (a letter or number); in other words, if either isalpha or isdigit is true of a character, then isalnum is also true.

 -- Function: int isxdigit (int C)
     Returns true if C is a hexadecimal digit. Hexadecimal digits include the normal decimal digits 0 through 9 and the letters A through F and a through f.

 -- Function: int ispunct (int C)
     Returns true if C is a punctuation character. This means any printing character that is not alphanumeric or a space character.

 -- Function: int isspace (int C)
     Returns true if C is a whitespace character.  In the standard "C" locale, isspace returns true for only the standard whitespace characters:

     ' '
          space

     '\f'
          formfeed

     '\n'
          newline

     '\r'
          carriage return

     '\t'
          horizontal tab

     '\v'
          vertical tab

 -- Function: int isblank (int C)
     Returns true if C is a blank character; that is, a space or a tab. This function is a GNU extension.

 -- Function: int isgraph (int C)
     Returns true if C is a graphic character; that is, a character that has a glyph associated with it.  The whitespace characters are not considered graphic.

 -- Function: int isprint (int C)
     Returns true if C is a printing character.  Printing characters include all the graphic characters, plus the space ( ) character.

 -- Function: int iscntrl (int C)
     Returns true if C is a control character (that is, a character that is not a printing character).

 -- Function: int isascii (int C)
     Returns true if C is a 7-bit unsigned char value that fits into the US/UK ASCII character set.  This function is a BSD extension and is also an SVID extension.

Case Conversion
===============

This section explains the library functions for performing conversions such as case mappings on characters.  For example, toupper converts any character to upper case if possible.  If the character can't be converted, toupper returns it unchanged.

These functions take one argument of type int, which is the character to convert, and return the converted character as an int.  If the conversion is not applicable to the argument given, the argument is returned unchanged.

Compatibility Note: In pre-ANSI C dialects, instead of returning the argument unchanged, these functions may fail when the argument is not suitable for the conversion.  Thus for portability, you may need to write islower(c) ? toupper(c) : c rather than just toupper(c).

These functions are declared in the header file ctype.h.

 -- Function: int tolower (int C)
     If C is an upper-case letter, tolower returns the corresponding lower-case letter.  If C is not an upper-case letter, C is returned unchanged.

 -- Function: int toupper (int C)
     If C is a lower-case letter, tolower returns the corresponding upper-case letter.  Otherwise C is returned unchanged.

 -- Function: int toascii (int C)
     This function converts C to a 7-bit unsigned char value that fits into the US/UK ASCII character set, by clearing the high-order bits.  This function is a BSD extension and is also an SVID extension.

 -- Function: int _tolower (int C)
     This is identical to tolower, and is provided for compatibility with the SVID.  See SVID.

 -- Function: int _toupper (int C)
     This is identical to toupper, and is provided for compatibility with the SVID.