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