path: root/manual/ctype.texi

@node Character Handling, String and Array Utilities, Memory, Top
@c %MENU% Character testing and conversion functions
@chapter 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 @file{ctype.h} are provided for this
purpose.
@pindex ctype.h

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
@code{LC_CTYPE} category; see @ref{Locale Categories}.)

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 characters (@pxref{Extended Char Intro}).

@menu
* Classification of Characters::       Testing whether characters are
			                letters, digits, punctuation, etc.

* Case Conversion::                    Case mapping, and the like.
* Classification of Wide Characters::  Character class determination for
                                        wide characters.
* Using Wide Char Classes::            Notes on using the wide character
                                        classes.
* Wide Character Case Conversion::     Mapping of wide characters.
@end menu

@node Classification of Characters, Case Conversion,  , Character Handling
@section Classification of Characters
@cindex character testing
@cindex classification of characters
@cindex predicates on characters
@cindex character predicates

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

@smallexample
if (isalpha ((unsigned char) c))
  printf ("The character `%c' is alphabetic.\n", c);
@end smallexample

Each of the functions in this section tests for membership in a
particular class of characters; each has a name starting with @samp{is}.
Each of them takes one argument, which is a character to test.  The
character argument must be in the value range of @code{unsigned char} (0
to 255 for @theglibc{}).  On a machine where the @code{char} type is
signed, it may be necessary to cast the argument to @code{unsigned
char}, or mask it with @samp{& 0xff}.  (On @code{unsigned char}
machines, this step is harmless, so portable code should always perform
it.)  The @samp{is} functions return an @code{int} which is treated as a
boolean value.

All @samp{is} functions accept the special value @code{EOF} and return
zero.  (Note that @code{EOF} must not be cast to @code{unsigned char}
for this to work.)

As an extension, @theglibc{} accepts signed @code{char} values as
@samp{is} functions arguments in the range -128 to -2, and returns the
result for the corresponding unsigned character.  However, as there
might be an actual character corresponding to the @code{EOF} integer
constant, doing so may introduce bugs, and it is recommended to apply
the conversion to the unsigned character range as appropriate.

The attributes of any given character can vary between locales.
@xref{Locales}, for more information on locales.

These functions are declared in the header file @file{ctype.h}.
@pindex ctype.h

@cindex lower-case character
@deftypefun int islower (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c The is* macros call __ctype_b_loc to get the ctype array from the
@c current locale, and then index it by c.  __ctype_b_loc reads from
@c thread-local memory the (indirect) pointer to the ctype array, which
@c may involve one word access to the global locale object, if that's
@c the active locale for the thread, and the array, being part of the
@c locale data, is undeletable, so there's no thread-safety issue.  We
@c might want to mark these with @mtslocale to flag to callers that
@c changing locales might affect them, even if not these simpler
@c functions.
Returns true if @var{c} is a lower-case letter.  The letter need not be
from the Latin alphabet, any alphabet representable is valid.
@end deftypefun

@cindex upper-case character
@deftypefun int isupper (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is an upper-case letter.  The letter need not be
from the Latin alphabet, any alphabet representable is valid.
@end deftypefun

@cindex alphabetic character
@deftypefun int isalpha (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is an alphabetic character (a letter).  If
@code{islower} or @code{isupper} is true of a character, then
@code{isalpha} is also true.

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

@cindex digit character
@cindex decimal digit character
@deftypefun int isdigit (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
@end deftypefun

@cindex alphanumeric character
@deftypefun int isalnum (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is an alphanumeric character (a letter or
number); in other words, if either @code{isalpha} or @code{isdigit} is
true of a character, then @code{isalnum} is also true.
@end deftypefun

@cindex hexadecimal digit character
@deftypefun int isxdigit (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a hexadecimal digit.
Hexadecimal digits include the normal decimal digits @samp{0} through
@samp{9} and the letters @samp{A} through @samp{F} and
@samp{a} through @samp{f}.
@end deftypefun

@cindex punctuation character
@deftypefun int ispunct (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a punctuation character.
This means any printing character that is not alphanumeric or a space
character.
@end deftypefun

@cindex whitespace character
@deftypefun int isspace (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a @dfn{whitespace} character.  In the standard
@code{"C"} locale, @code{isspace} returns true for only the standard
whitespace characters:

@table @code
@item ' '
space

@item '\f'
formfeed

@item '\n'
newline

@item '\r'
carriage return

@item '\t'
horizontal tab

@item '\v'
vertical tab
@end table
@end deftypefun

@cindex blank character
@deftypefun int isblank (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a blank character; that is, a space or a tab.
This function was originally a GNU extension, but was added in @w{ISO C99}.
@end deftypefun

@cindex graphic character
@deftypefun int isgraph (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a graphic character; that is, a character
that has a glyph associated with it.  The whitespace characters are not
considered graphic.
@end deftypefun

@cindex printing character
@deftypefun int isprint (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a printing character.  Printing characters
include all the graphic characters, plus the space (@samp{ }) character.
@end deftypefun

@cindex control character
@deftypefun int iscntrl (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a control character (that is, a character that
is not a printing character).
@end deftypefun

@cindex ASCII character
@deftypefun int isascii (int @var{c})
@standards{SVID, ctype.h}
@standards{BSD, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Returns true if @var{c} is a 7-bit @code{unsigned char} value that fits
into the US/UK ASCII character set.  This function is a BSD extension
and is also an SVID extension.
@end deftypefun

@node Case Conversion, Classification of Wide Characters, Classification of Characters, Character Handling
@section Case Conversion
@cindex character case conversion
@cindex case conversion of characters
@cindex converting case of characters

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

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

@strong{Compatibility Note:} In pre-@w{ISO 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 @code{islower(c) ? toupper(c) : c} rather than just
@code{toupper(c)}.

These functions are declared in the header file @file{ctype.h}.
@pindex ctype.h

@deftypefun int tolower (int @var{c})
@standards{ISO, ctype.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c The to* macros/functions call different functions that use different
@c arrays than those of__ctype_b_lo