Section 16.3. Character Classification and Conversion

16.3. Character Classification and Conversion

The standard library provides a number of functions to classify characters and to perform conversions on them. The header ctype.h declares such functions for byte characters, with character codes from 0 to 255. The header wctype.h declares similar functions for wide characters, which have the type wchar_t. These functions are commonly implemented as macros.

The results of these functions, except for isdigit( ) and isxdigit( ), depends on the current locale setting for the locale category LC_CTYPE. You can query or change the locale using the setlocale( ) function.

16.3.1. Character Classification

The functions listed in Table 16-12 test whether a character belongs to a certain category. Their return value is nonzero, or true, if the argument is a character code in the given category.

Table 16-12. Character classification functions

Category	Functions in ctype.h	Functions in wctype.h
Letters	isalpha( )	iswalpha( )
Lowercase letters	islower( )	iswlower( )
Uppercase letters	isupper( )	iswupper( )
Decimal digits	isdigit( )	iswdigit( )
Hexadecimal digits	isxdigit( )	iswxdigit( )
Letters and decimal digits	isalnum( )	iswalnum( )
Printable characters (including whitespace)	isprint( )	iswprint( )
Printable, non-whitespace characters	isgraph( )	iswgraph( )
Whitespace characters	isspace( )	iswspace( )
Whitespace characters that separate words in a line of text	isblank( )	iswblank( )
Punctuation marks	ispunct( )	iswpunct( )
Control characters	iscntrl( )	iswcntrl( )

The functions isgraph( ) and iswgraph( ) behave differently if the execution character set contains other byte-coded, printable, whitespace characters (that is, whitespace characters which are not control characters) in addition to the space character (' '). In that case, iswgraph( ) returns false for all such printable whitespace characters, while isgraph( ) returns false only for the space character (' ').

The header wctype.h also declares the two additional functions listed in Table 16-13 to test wide characters. These are called the extensible classification functions, which you can use to test whether a wide-character value belongs to an implementation-defined category designated by a string.

Table 16-13. Extensible character classification functions

Purpose	Function
Map a string argument that designates a character class to a scalar value that can be used as the second argument to iswctype( ).	wctype( )
Test whether a wide character belongs to the class designated by the second argument.	iswctype( )

The two functions in Table 16-13 can be used to perform at least the same tests as the functions listed in Table 16-12. The strings that designate the character classes recognized by wctype( ) are formed from the name of the corresponding test functions, minus the prefix isw. For example, the string "alpha", like the function name iswalpha( ), designates the category "letters." Thus for a wide character value wc, the following tests are equivalent:

     iswalpha( wc )     iswctype( wc, wctype("alpha") ) 

Implementations may also define other such strings to designate locale-specific character classes.

16.3.2. Case Mapping

The functions listed in Table 16-14 yield the uppercase letter that corresponds to a given lowercase letter, and vice versa. All other argument values are returned unchanged.

Table 16-14. Character conversion functions

Conversion	Functions in ctype.h	Functions in wctype.h
Upper- to lowercase	tolower( )	towlower( )
Lower- to uppercase	toupper( )	towupper( )

Here again, as in the previous section, the header wctype.h declares two additional extensible functions to convert wide characters. These are described in Table 16-15. Each kind of character conversion supported by the given implementation is designated by a string.

Table 16-15. Extensible character conversion functions

Purpose	Function
Map a string argument that designates a character conversion to a scalar value that can be used as the second argument to towctrans( ).	wctrans( )
Perform the conversion designated by the second argument on a given wide character.	towctrans( )

The two functions in Table 16-15 can be used to perform at least the same conversions as the functions listed in Table 16-14. The strings that designate those conversions are "tolower" and "toupper". Thus for a wide character wc, the following two calls have the same result:

     towupper( wc );     towctrans( wc, wctrans("toupper") ); 

Implementations may also define other strings to designate locale-specific character conversions.