45668760ab1bd23426e2c0f8c9dd231f89a7e34b
[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.)
15 @xref{Locales}.
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 @example
38 if (isalpha (c))
39   printf ("The character `%c' is alphabetic.\n", c);
40 @end example
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
182 @cindex ASCII character
183 @comment ctype.h
184 @comment SVID, GNU
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.
188 @end deftypefun
189
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-ANSI 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 ANSI
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 ANSI
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, GNU
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
236 high-order bits.
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