Update.
[kopensolaris-gnu/glibc.git] / 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 ISO
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 ISO
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 ISO
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 ISO
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 ISO
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 ISO
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 ISO
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 ISO
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 ISO
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 ISO
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 ISO
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-@w{ISO 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 ISO
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 ISO
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