manual/ctype.texi

   1 @node Character Handling, String and Array Utilities, Memory Allocation, Top
   2 @chapter Character Handling
   3
   4 Programs that work with characters and strings often need to classify a
   5 character---is it alphabetic, is it a digit, is it whitespace, and so
   6 on---and perform case conversion operations on characters.  The
   7 functions in the header file @file{ctype.h} are provided for this
   8 purpose.
   9 @pindex ctype.h
  10
  11 Since the choice of locale and character set can alter the
  12 classifications of particular character codes, all of these functions
  13 are affected by the current locale.  (More precisely, they are affected
  14 by the locale currently selected for character classification---the
  15 @code{LC_CTYPE} category; see @ref{Locale Categories}.)
  16
  17 @menu
  18 * Classification of Characters::   Testing whether characters are
  19                                     letters, digits, punctuation, etc.
  20
  21 * Case Conversion::                Case mapping, and the like.
  22 @end menu
  23
  24 @node Classification of Characters, Case Conversion,  , Character Handling
  25 @section Classification of Characters
  26 @cindex character testing
  27 @cindex classification of characters
  28 @cindex predicates on characters
  29 @cindex character predicates
  30
  31 This section explains the library functions for classifying characters.
  32 For example, @code{isalpha} is the function to test for an alphabetic
  33 character.  It takes one argument, the character to test, and returns a
  34 nonzero integer if the character is alphabetic, and zero otherwise.  You
  35 would use it like this:
  36
  37 @smallexample
  38 if (isalpha (c))
  39   printf ("The character `%c' is alphabetic.\n", c);
  40 @end smallexample
  41
  42 Each of the functions in this section tests for membership in a
  43 particular class of characters; each has a name starting with @samp{is}.
  44 Each of them takes one argument, which is a character to test, and
  45 returns an @code{int} which is treated as a boolean value.  The
  46 character argument is passed as an @code{int}, and it may be the
  47 constant value @code{EOF} instead of a real character.
  48
  49 The attributes of any given character can vary between locales.
  50 @xref{Locales}, for more information on locales.@refill
  51
  52 These functions are declared in the header file @file{ctype.h}.
  53 @pindex ctype.h
  54
  55 @cindex lower-case character
  56 @comment ctype.h
  57 @comment ANSI
  58 @deftypefun int islower (int @var{c})
  59 Returns true if @var{c} is a lower-case letter.
  60 @end deftypefun
  61
  62 @cindex upper-case character
  63 @comment ctype.h
  64 @comment ANSI
  65 @deftypefun int isupper (int @var{c})
  66 Returns true if @var{c} is an upper-case letter.
  67 @end deftypefun
  68
  69 @cindex alphabetic character
  70 @comment ctype.h
  71 @comment ANSI
  72 @deftypefun int isalpha (int @var{c})
  73 Returns true if @var{c} is an alphabetic character (a letter).  If
  74 @code{islower} or @code{isupper} is true of a character, then
  75 @code{isalpha} is also true.
  76
  77 In some locales, there may be additional characters for which
  78 @code{isalpha} is true--letters which are neither upper case nor lower
  79 case.  But in the standard @code{"C"} locale, there are no such
  80 additional characters.
  81 @end deftypefun
  82
  83 @cindex digit character
  84 @cindex decimal digit character
  85 @comment ctype.h
  86 @comment ANSI
  87 @deftypefun int isdigit (int @var{c})
  88 Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
  89 @end deftypefun
  90
  91 @cindex alphanumeric character
  92 @comment ctype.h
  93 @comment ANSI
  94 @deftypefun int isalnum (int @var{c})
  95 Returns true if @var{c} is an alphanumeric character (a letter or
  96 number); in other words, if either @code{isalpha} or @code{isdigit} is
  97 true of a character, then @code{isalnum} is also true.
  98 @end deftypefun
  99
 100 @cindex hexadecimal digit character
 101 @comment ctype.h
 102 @comment ANSI
 103 @deftypefun int isxdigit (int @var{c})
 104 Returns true if @var{c} is a hexadecimal digit.
 105 Hexadecimal digits include the normal decimal digits @samp{0} through
 106 @samp{9} and the letters @samp{A} through @samp{F} and
 107 @samp{a} through @samp{f}.
 108 @end deftypefun
 109
 110 @cindex punctuation character
 111 @comment ctype.h
 112 @comment ANSI
 113 @deftypefun int ispunct (int @var{c})
 114 Returns true if @var{c} is a punctuation character.
 115 This means any printing character that is not alphanumeric or a space
 116 character.
 117 @end deftypefun
 118
 119 @cindex whitespace character
 120 @comment ctype.h
 121 @comment ANSI
 122 @deftypefun int isspace (int @var{c})
 123 Returns true if @var{c} is a @dfn{whitespace} character.  In the standard
 124 @code{"C"} locale, @code{isspace} returns true for only the standard
 125 whitespace characters:
 126
 127 @table @code
 128 @item ' '
 129 space
 130
 131 @item '\f'
 132 formfeed
 133
 134 @item '\n'
 135 newline
 136
 137 @item '\r'
 138 carriage return
 139
 140 @item '\t'
 141 horizontal tab
 142
 143 @item '\v'
 144 vertical tab
 145 @end table
 146 @end deftypefun
 147
 148 @cindex blank character
 149 @comment ctype.h
 150 @comment GNU
 151 @deftypefun int isblank (int @var{c})
 152 Returns true if @var{c} is a blank character; that is, a space or a tab.
 153 This function is a GNU extension.
 154 @end deftypefun
 155
 156 @cindex graphic character
 157 @comment ctype.h
 158 @comment ANSI
 159 @deftypefun int isgraph (int @var{c})
 160 Returns true if @var{c} is a graphic character; that is, a character
 161 that has a glyph associated with it.  The whitespace characters are not
 162 considered graphic.
 163 @end deftypefun
 164
 165 @cindex printing character
 166 @comment ctype.h
 167 @comment ANSI
 168 @deftypefun int isprint (int @var{c})
 169 Returns true if @var{c} is a printing character.  Printing characters
 170 include all the graphic characters, plus the space (@samp{ }) character.
 171 @end deftypefun
 172
 173 @cindex control character
 174 @comment ctype.h
 175 @comment ANSI
 176 @deftypefun int iscntrl (int @var{c})
 177 Returns true if @var{c} is a control character (that is, a character that
 178 is not a printing character).
 179 @end deftypefun
 180
 181 @cindex ASCII character
 182 @comment ctype.h
 183 @comment SVID, BSD
 184 @deftypefun int isascii (int @var{c})
 185 Returns true if @var{c} is a 7-bit @code{unsigned char} value that fits
 186 into the US/UK ASCII character set.  This function is a BSD extension
 187 and is also an SVID extension.
 188 @end deftypefun
 189
 190 @node Case Conversion,  , Classification of Characters, Character Handling
 191 @section Case Conversion
 192 @cindex character case conversion
 193 @cindex case conversion of characters
 194 @cindex converting case of characters
 195
 196 This section explains the library functions for performing conversions
 197 such as case mappings on characters.  For example, @code{toupper}
 198 converts any character to upper case if possible.  If the character
 199 can't be converted, @code{toupper} returns it unchanged.
 200
 201 These functions take one argument of type @code{int}, which is the
 202 character to convert, and return the converted character as an
 203 @code{int}.  If the conversion is not applicable to the argument given,
 204 the argument is returned unchanged.
 205
 206 @strong{Compatibility Note:} In pre-ANSI C dialects, instead of
 207 returning the argument unchanged, these functions may fail when the
 208 argument is not suitable for the conversion.  Thus for portability, you
 209 may need to write @code{islower(c) ? toupper(c) : c} rather than just
 210 @code{toupper(c)}.
 211
 212 These functions are declared in the header file @file{ctype.h}.
 213 @pindex ctype.h
 214
 215 @comment ctype.h
 216 @comment ANSI
 217 @deftypefun int tolower (int @var{c})
 218 If @var{c} is an upper-case letter, @code{tolower} returns the corresponding
 219 lower-case letter.  If @var{c} is not an upper-case letter,
 220 @var{c} is returned unchanged.
 221 @end deftypefun
 222
 223 @comment ctype.h
 224 @comment ANSI
 225 @deftypefun int toupper (int @var{c})
 226 If @var{c} is a lower-case letter, @code{tolower} returns the corresponding
 227 upper-case letter.  Otherwise @var{c} is returned unchanged.
 228 @end deftypefun
 229
 230 @comment ctype.h
 231 @comment SVID, BSD
 232 @deftypefun int toascii (int @var{c})
 233 This function converts @var{c} to a 7-bit @code{unsigned char} value
 234 that fits into the US/UK ASCII character set, by clearing the high-order
 235 bits.  This function is a BSD extension and is also an SVID extension.
 236 @end deftypefun
 237
 238 @comment ctype.h
 239 @comment SVID
 240 @deftypefun int _tolower (int @var{c})
 241 This is identical to @code{tolower}, and is provided for compatibility
 242 with the SVID.  @xref{SVID}.@refill
 243 @end deftypefun
 244
 245 @comment ctype.h
 246 @comment SVID
 247 @deftypefun int _toupper (int @var{c})
 248 This is identical to @code{toupper}, and is provided for compatibility
 249 with the SVID.
 250 @end deftypefun