Put a @table around @include summary.out.
[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.  (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 * Case Conversion::                     Case mapping, and the like.
21 @end menu
22
23 @node Classification of Characters
24 @section Classification of Characters
25 @cindex character testing
26 @cindex classification of characters
27 @cindex predicates on characters
28 @cindex character predicates
29
30 This section explains the library functions for classifying characters.
31 For example, @code{isalpha} is the function to test for an alphabetic
32 character.  It takes one argument, the character to test, and returns a
33 nonzero integer if the character is alphabetic, and zero otherwise.  You
34 would use it like this:
35
36 @example
37 if (isalpha (c))
38   printf ("The character `%c' is alphabetic.\n", c);
39 @end example
40
41 Each of the functions in this section tests for membership in a
42 particular class of characters; each has a name starting with @samp{is}.
43 Each of them takes one argument, which is a character to test, and
44 returns an @code{int} which is treated as a boolean value.  The
45 character argument is passed as an @code{int}, and it may be the
46 constant value @code{EOF} instead of a real character.  
47
48 The attributes of any given character can vary between locales.
49 @xref{Locales}, for more information on locales.@refill
50
51 These functions are declared in the header file @file{ctype.h}.
52 @pindex ctype.h
53
54 @cindex lower-case character
55 @comment ctype.h
56 @comment ANSI
57 @deftypefun int islower (int @var{c})
58 Returns true if @var{c} is a lower-case letter.
59 @end deftypefun
60
61 @cindex upper-case character
62 @comment ctype.h
63 @comment ANSI
64 @deftypefun int isupper (int @var{c})
65 Returns true if @var{c} is an upper-case letter.
66 @end deftypefun
67
68 @cindex alphabetic character
69 @comment ctype.h
70 @comment ANSI
71 @deftypefun int isalpha (int @var{c})
72 Returns true if @var{c} is an alphabetic character (a letter).  If
73 @code{islower} or @code{isupper} is true of a character, then
74 @code{isalpha} is also true.
75
76 In some locales, there may be additional characters for which
77 @code{isalpha} is true--letters which are neither upper case nor lower
78 case.  But in the standard @code{"C"} locale, there are no such
79 additional characters.
80 @end deftypefun
81
82 @cindex digit character
83 @cindex decimal digit character
84 @comment ctype.h
85 @comment ANSI
86 @deftypefun int isdigit (int @var{c})
87 Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
88 @end deftypefun
89
90 @cindex alphanumeric character
91 @comment ctype.h
92 @comment ANSI
93 @deftypefun int isalnum (int @var{c})
94 Returns true if @var{c} is an alphanumeric character (a letter or
95 number); in other words, if either @code{isalpha} or @code{isdigit} is
96 true of a character, then @code{isalnum} is also true.
97 @end deftypefun
98
99 @cindex hexadecimal digit character
100 @comment ctype.h
101 @comment ANSI
102 @deftypefun int isxdigit (int @var{c})
103 Returns true if @var{c} is a hexadecimal digit.
104 Hexadecimal digits include the normal decimal digits @samp{0} through
105 @samp{9} and the letters @samp{A} through @samp{F} and
106 @samp{a} through @samp{f}.
107 @end deftypefun
108
109 @cindex punctuation character
110 @comment ctype.h
111 @comment ANSI
112 @deftypefun int ispunct (int @var{c})
113 Returns true if @var{c} is a punctuation character.
114 This means any printing character that is not alphanumeric or a space
115 character.
116 @end deftypefun
117
118 @cindex whitespace character
119 @comment ctype.h
120 @comment ANSI
121 @deftypefun int isspace (int @var{c})
122 Returns true if @var{c} is a @dfn{whitespace} character.  In the standard
123 @code{"C"} locale, @code{isspace} returns true for only the standard
124 whitespace characters:
125
126 @table @code
127 @item ' '
128 space
129
130 @item '\f'
131 formfeed
132
133 @item '\n'
134 newline
135
136 @item '\r'
137 carriage return
138
139 @item '\t'
140 horizontal tab
141
142 @item '\v'
143 vertical tab
144 @end table
145 @end deftypefun
146
147 @cindex blank character
148 @comment ctype.h
149 @comment GNU
150 @deftypefun int isblank (int @var{c})
151 Returns true if @var{c} is a blank character; that is, a space or a tab.
152 This function is a GNU extension.
153 @end deftypefun
154
155 @cindex graphic character
156 @comment ctype.h
157 @comment ANSI
158 @deftypefun int isgraph (int @var{c})
159 Returns true if @var{c} is a graphic character; that is, a character
160 that has a glyph associated with it.  The whitespace characters are not
161 considered graphic.
162 @end deftypefun
163
164 @cindex printing character
165 @comment ctype.h
166 @comment ANSI
167 @deftypefun int isprint (int @var{c})
168 Returns true if @var{c} is a printing character.  Printing characters
169 include all the graphic characters, plus the space (@samp{ }) character.
170 @end deftypefun
171
172 @cindex control character
173 @comment ctype.h
174 @comment ANSI
175 @deftypefun int iscntrl (int @var{c})
176 Returns true if @var{c} is a control character (that is, a character that
177 is not a printing character).
178 @end deftypefun
179
180
181 @cindex ASCII character
182 @comment ctype.h
183 @comment SVID, GNU
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.
187 @end deftypefun
188
189
190 @node Case Conversion
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, GNU
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
235 high-order bits.
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