Update.
[glibc.git] / manual / ctype.texi
blob26e40a1c53dc00c8e273f56b0b8b5cc4baac26bc
1 @node Character Handling, String and Array Utilities, Memory Allocation, Top
2 @c %MENU% Character testing and conversion functions
3 @chapter Character Handling
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 @pindex ctype.h
12 Since the choice of locale and character set can alter the
13 classifications of particular character codes, all of these functions
14 are affected by the current locale.  (More precisely, they are affected
15 by the locale currently selected for character classification---the
16 @code{LC_CTYPE} category; see @ref{Locale Categories}.)
18 @menu
19 * Classification of Characters::   Testing whether characters are
20                                     letters, digits, punctuation, etc.
22 * Case Conversion::                Case mapping, and the like.
23 @end menu
25 @node Classification of Characters, Case Conversion,  , Character Handling
26 @section Classification of Characters
27 @cindex character testing
28 @cindex classification of characters
29 @cindex predicates on characters
30 @cindex character predicates
32 This section explains the library functions for classifying characters.
33 For example, @code{isalpha} is the function to test for an alphabetic
34 character.  It takes one argument, the character to test, and returns a
35 nonzero integer if the character is alphabetic, and zero otherwise.  You
36 would use it like this:
38 @smallexample
39 if (isalpha (c))
40   printf ("The character `%c' is alphabetic.\n", c);
41 @end smallexample
43 Each of the functions in this section tests for membership in a
44 particular class of characters; each has a name starting with @samp{is}.
45 Each of them takes one argument, which is a character to test, and
46 returns an @code{int} which is treated as a boolean value.  The
47 character argument is passed as an @code{int}, and it may be the
48 constant value @code{EOF} instead of a real character.
50 The attributes of any given character can vary between locales.
51 @xref{Locales}, for more information on locales.@refill
53 These functions are declared in the header file @file{ctype.h}.
54 @pindex ctype.h
56 @cindex lower-case character
57 @comment ctype.h
58 @comment ISO
59 @deftypefun int islower (int @var{c})
60 Returns true if @var{c} is a lower-case letter.
61 @end deftypefun
63 @cindex upper-case character
64 @comment ctype.h
65 @comment ISO
66 @deftypefun int isupper (int @var{c})
67 Returns true if @var{c} is an upper-case letter.
68 @end deftypefun
70 @cindex alphabetic character
71 @comment ctype.h
72 @comment ISO
73 @deftypefun int isalpha (int @var{c})
74 Returns true if @var{c} is an alphabetic character (a letter).  If
75 @code{islower} or @code{isupper} is true of a character, then
76 @code{isalpha} is also true.
78 In some locales, there may be additional characters for which
79 @code{isalpha} is true---letters which are neither upper case nor lower
80 case.  But in the standard @code{"C"} locale, there are no such
81 additional characters.
82 @end deftypefun
84 @cindex digit character
85 @cindex decimal digit character
86 @comment ctype.h
87 @comment ISO
88 @deftypefun int isdigit (int @var{c})
89 Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
90 @end deftypefun
92 @cindex alphanumeric character
93 @comment ctype.h
94 @comment ISO
95 @deftypefun int isalnum (int @var{c})
96 Returns true if @var{c} is an alphanumeric character (a letter or
97 number); in other words, if either @code{isalpha} or @code{isdigit} is
98 true of a character, then @code{isalnum} is also true.
99 @end deftypefun
101 @cindex hexadecimal digit character
102 @comment ctype.h
103 @comment ISO
104 @deftypefun int isxdigit (int @var{c})
105 Returns true if @var{c} is a hexadecimal digit.
106 Hexadecimal digits include the normal decimal digits @samp{0} through
107 @samp{9} and the letters @samp{A} through @samp{F} and
108 @samp{a} through @samp{f}.
109 @end deftypefun
111 @cindex punctuation character
112 @comment ctype.h
113 @comment ISO
114 @deftypefun int ispunct (int @var{c})
115 Returns true if @var{c} is a punctuation character.
116 This means any printing character that is not alphanumeric or a space
117 character.
118 @end deftypefun
120 @cindex whitespace character
121 @comment ctype.h
122 @comment ISO
123 @deftypefun int isspace (int @var{c})
124 Returns true if @var{c} is a @dfn{whitespace} character.  In the standard
125 @code{"C"} locale, @code{isspace} returns true for only the standard
126 whitespace characters:
128 @table @code
129 @item ' '
130 space
132 @item '\f'
133 formfeed
135 @item '\n'
136 newline
138 @item '\r'
139 carriage return
141 @item '\t'
142 horizontal tab
144 @item '\v'
145 vertical tab
146 @end table
147 @end deftypefun
149 @cindex blank character
150 @comment ctype.h
151 @comment GNU
152 @deftypefun int isblank (int @var{c})
153 Returns true if @var{c} is a blank character; that is, a space or a tab.
154 This function is a GNU extension.
155 @end deftypefun
157 @cindex graphic character
158 @comment ctype.h
159 @comment ISO
160 @deftypefun int isgraph (int @var{c})
161 Returns true if @var{c} is a graphic character; that is, a character
162 that has a glyph associated with it.  The whitespace characters are not
163 considered graphic.
164 @end deftypefun
166 @cindex printing character
167 @comment ctype.h
168 @comment ISO
169 @deftypefun int isprint (int @var{c})
170 Returns true if @var{c} is a printing character.  Printing characters
171 include all the graphic characters, plus the space (@samp{ }) character.
172 @end deftypefun
174 @cindex control character
175 @comment ctype.h
176 @comment ISO
177 @deftypefun int iscntrl (int @var{c})
178 Returns true if @var{c} is a control character (that is, a character that
179 is not a printing character).
180 @end deftypefun
182 @cindex ASCII character
183 @comment ctype.h
184 @comment SVID, BSD
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.  This function is a BSD extension
188 and is also an SVID extension.
189 @end deftypefun
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
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.
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.
207 @strong{Compatibility Note:} In pre-@w{ISO 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)}.
213 These functions are declared in the header file @file{ctype.h}.
214 @pindex ctype.h
216 @comment ctype.h
217 @comment ISO
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
224 @comment ctype.h
225 @comment ISO
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
231 @comment ctype.h
232 @comment SVID, BSD
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 high-order
236 bits.  This function is a BSD extension and is also an SVID extension.
237 @end deftypefun
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
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