9.3. Character handling

There are a variety of functions provided for testing and mapping characters. The testing functions, which are described first, allow you to test if a character is of a particular type, such as alphabetic, upper or lower case, numeric, a control character, a punctuation mark, printable or not and so on. The character testing functions return an integer, either zero if the character supplied is not of the category specified, or non-zero if it was. The functions all take an integer argument, which should either be an int, the value of which should be representable as unsigned char, or the integer constant EOF, as returned from functions such as getchar(). The behaviour is undefined if it is not.

These functions depend on the program's locale setting.

A printing character is a member of an implementation defined character set. Each printing character occupies one printing position. A control character is a member of an implementation defined character set, each of which is not a printing character. If the 7-bit ASCII character set is used, the printing characters are those that lie between space (0x20) and tilde (0x7e), the control characters are those between NUL (0x0) and US (0x1f), and the character DEL (0x7f).

The following is a summary of all the character testing functions. The header <ctype.h> must be included before any of them is used.

isalnum(int c)

True if c is alphabetic or a digit; specifically (isalpha(c)||isdigit(c)).

isalpha(int c)

True if (isupper(c)||islower(c)).

Also true for an implementation-defined set of characters which do not return true results from any of iscntrl, isdigit, ispunct or isspace. In the C locale, this extra set of characters is empty.

iscntrl(int c)

True if c is a control character.

isdigit(int c)

True if c is a decimal digit.

isgraph(int c)

True if c is any printing character except space.

islower(int c)

True if c is a lower case alphabetic letter. Also true for an implementation defined set of characters which do not return true results from any of iscntrl, isdigit, ispunct or isspace. In the C locale, this extra set of characters is empty.

isprint(int c)

True if c is a printing character (including space).

ispunct(int c)

True if c is any printing character that is neither a space nor a character which would return true from isalnum.

isspace(int c)

True if c is either a white space character (one of ' ' '\f' '\n' '\r' '\t' '\v') or, in other than the C locale, characters which would not return true from isalnum

isupper(int c)

True if c is an upper case alphabetic character.

Also true for an implementation-defined set of characters which do not return true results from any of iscntrl, isdigit, ispunct or isspace. In the C locale, this extra set of characters is empty.

isxdigit(int c)

True if c is a valid hexadecimal digit.

Two additional functions map characters from one set into another. The function tolower will, if given a upper case character as its argument, return the lower case equivalent. For example,

tolower('A') == 'a'

If tolower is given any character other than an upper case letter, it will return that character.

The converse function toupper maps lower case alphabetic letters onto their upper case equivalent.

For each, the conversion is only performed if there is a corresponding character in the alternate case. In some locales, not all upper case characters have lower case equivalents, and vice versa.