manual/ctype.texi

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