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