Update.
[glibc.git] / manual / ctype.texi
blob593f7f3a0b80d3315f726492897cf1c5bfbf43ef
1 @node Character Handling, String and Array Utilities, Memory, 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 The @w{ISO C} standard specifies two different sets of functions.  The
19 one set works on @code{char} type characters, the other one on
20 @code{wchar_t} wide characters (@pxref{Extended Char Intro}).
22 @menu
23 * Classification of Characters::       Testing whether characters are
24                                         letters, digits, punctuation, etc.
26 * Case Conversion::                    Case mapping, and the like.
27 * Classification of Wide Characters::  Character class determination for
28                                         wide characters.
29 * Using Wide Char Classes::            Notes on using the wide character
30                                         classes.
31 * Wide Character Case Conversion::     Mapping of wide characters.
32 @end menu
34 @node Classification of Characters, Case Conversion,  , Character Handling
35 @section Classification of Characters
36 @cindex character testing
37 @cindex classification of characters
38 @cindex predicates on characters
39 @cindex character predicates
41 This section explains the library functions for classifying characters.
42 For example, @code{isalpha} is the function to test for an alphabetic
43 character.  It takes one argument, the character to test, and returns a
44 nonzero integer if the character is alphabetic, and zero otherwise.  You
45 would use it like this:
47 @smallexample
48 if (isalpha (c))
49   printf ("The character `%c' is alphabetic.\n", c);
50 @end smallexample
52 Each of the functions in this section tests for membership in a
53 particular class of characters; each has a name starting with @samp{is}.
54 Each of them takes one argument, which is a character to test, and
55 returns an @code{int} which is treated as a boolean value.  The
56 character argument is passed as an @code{int}, and it may be the
57 constant value @code{EOF} instead of a real character.
59 The attributes of any given character can vary between locales.
60 @xref{Locales}, for more information on locales.@refill
62 These functions are declared in the header file @file{ctype.h}.
63 @pindex ctype.h
65 @cindex lower-case character
66 @comment ctype.h
67 @comment ISO
68 @deftypefun int islower (int @var{c})
69 Returns true if @var{c} is a lower-case letter.  The letter need not be
70 from the Latin alphabet, any alphabet representable is valid.
71 @end deftypefun
73 @cindex upper-case character
74 @comment ctype.h
75 @comment ISO
76 @deftypefun int isupper (int @var{c})
77 Returns true if @var{c} is an upper-case letter.  The letter need not be
78 from the Latin alphabet, any alphabet representable is valid.
79 @end deftypefun
81 @cindex alphabetic character
82 @comment ctype.h
83 @comment ISO
84 @deftypefun int isalpha (int @var{c})
85 Returns true if @var{c} is an alphabetic character (a letter).  If
86 @code{islower} or @code{isupper} is true of a character, then
87 @code{isalpha} is also true.
89 In some locales, there may be additional characters for which
90 @code{isalpha} is true---letters which are neither upper case nor lower
91 case.  But in the standard @code{"C"} locale, there are no such
92 additional characters.
93 @end deftypefun
95 @cindex digit character
96 @cindex decimal digit character
97 @comment ctype.h
98 @comment ISO
99 @deftypefun int isdigit (int @var{c})
100 Returns true if @var{c} is a decimal digit (@samp{0} through @samp{9}).
101 @end deftypefun
103 @cindex alphanumeric character
104 @comment ctype.h
105 @comment ISO
106 @deftypefun int isalnum (int @var{c})
107 Returns true if @var{c} is an alphanumeric character (a letter or
108 number); in other words, if either @code{isalpha} or @code{isdigit} is
109 true of a character, then @code{isalnum} is also true.
110 @end deftypefun
112 @cindex hexadecimal digit character
113 @comment ctype.h
114 @comment ISO
115 @deftypefun int isxdigit (int @var{c})
116 Returns true if @var{c} is a hexadecimal digit.
117 Hexadecimal digits include the normal decimal digits @samp{0} through
118 @samp{9} and the letters @samp{A} through @samp{F} and
119 @samp{a} through @samp{f}.
120 @end deftypefun
122 @cindex punctuation character
123 @comment ctype.h
124 @comment ISO
125 @deftypefun int ispunct (int @var{c})
126 Returns true if @var{c} is a punctuation character.
127 This means any printing character that is not alphanumeric or a space
128 character.
129 @end deftypefun
131 @cindex whitespace character
132 @comment ctype.h
133 @comment ISO
134 @deftypefun int isspace (int @var{c})
135 Returns true if @var{c} is a @dfn{whitespace} character.  In the standard
136 @code{"C"} locale, @code{isspace} returns true for only the standard
137 whitespace characters:
139 @table @code
140 @item ' '
141 space
143 @item '\f'
144 formfeed
146 @item '\n'
147 newline
149 @item '\r'
150 carriage return
152 @item '\t'
153 horizontal tab
155 @item '\v'
156 vertical tab
157 @end table
158 @end deftypefun
160 @cindex blank character
161 @comment ctype.h
162 @comment GNU
163 @deftypefun int isblank (int @var{c})
164 Returns true if @var{c} is a blank character; that is, a space or a tab.
165 This function is a GNU extension.
166 @end deftypefun
168 @cindex graphic character
169 @comment ctype.h
170 @comment ISO
171 @deftypefun int isgraph (int @var{c})
172 Returns true if @var{c} is a graphic character; that is, a character
173 that has a glyph associated with it.  The whitespace characters are not
174 considered graphic.
175 @end deftypefun
177 @cindex printing character
178 @comment ctype.h
179 @comment ISO
180 @deftypefun int isprint (int @var{c})
181 Returns true if @var{c} is a printing character.  Printing characters
182 include all the graphic characters, plus the space (@samp{ }) character.
183 @end deftypefun
185 @cindex control character
186 @comment ctype.h
187 @comment ISO
188 @deftypefun int iscntrl (int @var{c})
189 Returns true if @var{c} is a control character (that is, a character that
190 is not a printing character).
191 @end deftypefun
193 @cindex ASCII character
194 @comment ctype.h
195 @comment SVID, BSD
196 @deftypefun int isascii (int @var{c})
197 Returns true if @var{c} is a 7-bit @code{unsigned char} value that fits
198 into the US/UK ASCII character set.  This function is a BSD extension
199 and is also an SVID extension.
200 @end deftypefun
202 @node Case Conversion, Classification of Wide Characters, Classification of Characters, Character Handling
203 @section Case Conversion
204 @cindex character case conversion
205 @cindex case conversion of characters
206 @cindex converting case of characters
208 This section explains the library functions for performing conversions
209 such as case mappings on characters.  For example, @code{toupper}
210 converts any character to upper case if possible.  If the character
211 can't be converted, @code{toupper} returns it unchanged.
213 These functions take one argument of type @code{int}, which is the
214 character to convert, and return the converted character as an
215 @code{int}.  If the conversion is not applicable to the argument given,
216 the argument is returned unchanged.
218 @strong{Compatibility Note:} In pre-@w{ISO C} dialects, instead of
219 returning the argument unchanged, these functions may fail when the
220 argument is not suitable for the conversion.  Thus for portability, you
221 may need to write @code{islower(c) ? toupper(c) : c} rather than just
222 @code{toupper(c)}.
224 These functions are declared in the header file @file{ctype.h}.
225 @pindex ctype.h
227 @comment ctype.h
228 @comment ISO
229 @deftypefun int tolower (int @var{c})
230 If @var{c} is an upper-case letter, @code{tolower} returns the corresponding
231 lower-case letter.  If @var{c} is not an upper-case letter,
232 @var{c} is returned unchanged.
233 @end deftypefun
235 @comment ctype.h
236 @comment ISO
237 @deftypefun int toupper (int @var{c})
238 If @var{c} is a lower-case letter, @code{toupper} returns the corresponding
239 upper-case letter.  Otherwise @var{c} is returned unchanged.
240 @end deftypefun
242 @comment ctype.h
243 @comment SVID, BSD
244 @deftypefun int toascii (int @var{c})
245 This function converts @var{c} to a 7-bit @code{unsigned char} value
246 that fits into the US/UK ASCII character set, by clearing the high-order
247 bits.  This function is a BSD extension and is also an SVID extension.
248 @end deftypefun
250 @comment ctype.h
251 @comment SVID
252 @deftypefun int _tolower (int @var{c})
253 This is identical to @code{tolower}, and is provided for compatibility
254 with the SVID.  @xref{SVID}.@refill
255 @end deftypefun
257 @comment ctype.h
258 @comment SVID
259 @deftypefun int _toupper (int @var{c})
260 This is identical to @code{toupper}, and is provided for compatibility
261 with the SVID.
262 @end deftypefun
265 @node Classification of Wide Characters, Using Wide Char Classes, Case Conversion, Character Handling
266 @section Character class determination for wide characters
268 @w{Amendment 1} to @w{ISO C90} defines functions to classify wide
269 characters.  Although the original @w{ISO C90} standard already defined
270 the type @code{wchar_t}, no functions operating on them were defined.
272 The general design of the classification functions for wide characters
273 is more general.  It allows extensions to the set of available
274 classifications, beyond those which are always available.  The POSIX
275 standard specifies how extensions can be made, and this is already
276 implemented in the GNU C library implementation of the @code{localedef}
277 program.
279 The character class functions are normally implemented with bitsets,
280 with a bitset per character.  For a given character, the appropriate
281 bitset is read from a table and a test is performed as to whether a
282 certain bit is set.  Which bit is tested for is determined by the
283 class.
285 For the wide character classification functions this is made visible.
286 There is a type classification type defined, a function to retrieve this
287 value for a given class, and a function to test whether a given
288 character is in this class, using the classification value.  On top of
289 this the normal character classification functions as used for
290 @code{char} objects can be defined.
292 @comment wctype.h
293 @comment ISO
294 @deftp {Data type} wctype_t
295 The @code{wctype_t} can hold a value which represents a character class.
296 The only defined way to generate such a value is by using the
297 @code{wctype} function.
299 @pindex wctype.h
300 This type is defined in @file{wctype.h}.
301 @end deftp
303 @comment wctype.h
304 @comment ISO
305 @deftypefun wctype_t wctype (const char *@var{property})
306 The @code{wctype} returns a value representing a class of wide
307 characters which is identified by the string @var{property}.  Beside
308 some standard properties each locale can define its own ones.  In case
309 no property with the given name is known for the current locale
310 selected for the @code{LC_CTYPE} category, the function returns zero.
312 @noindent
313 The properties known in every locale are:
315 @multitable @columnfractions .25 .25 .25 .25
316 @item
317 @code{"alnum"} @tab @code{"alpha"} @tab @code{"cntrl"} @tab @code{"digit"}
318 @item
319 @code{"graph"} @tab @code{"lower"} @tab @code{"print"} @tab @code{"punct"}
320 @item
321 @code{"space"} @tab @code{"upper"} @tab @code{"xdigit"}
322 @end multitable
324 @pindex wctype.h
325 This function is declared in @file{wctype.h}.
326 @end deftypefun
328 To test the membership of a character to one of the non-standard classes
329 the @w{ISO C} standard defines a completely new function.
331 @comment wctype.h
332 @comment ISO
333 @deftypefun int iswctype (wint_t @var{wc}, wctype_t @var{desc})
334 This function returns a nonzero value if @var{wc} is in the character
335 class specified by @var{desc}.  @var{desc} must previously be returned
336 by a successful call to @code{wctype}.
338 @pindex wctype.h
339 This function is declared in @file{wctype.h}.
340 @end deftypefun
342 To make it easier to use the commonly-used classification functions,
343 they are defined in the C library.  There is no need to use
344 @code{wctype} if the property string is one of the known character
345 classes.  In some situations it is desirable to construct the property
346 strings, and then it is important that @code{wctype} can also handle the
347 standard classes.
349 @cindex alphanumeric character
350 @comment wctype.h
351 @comment ISO
352 @deftypefun int iswalnum (wint_t @var{wc})
353 This function returns a nonzero value if @var{wc} is an alphanumeric
354 character (a letter or number); in other words, if either @code{iswalpha}
355 or @code{iswdigit} is true of a character, then @code{iswalnum} is also
356 true.
358 @noindent
359 This function can be implemented using
361 @smallexample
362 iswctype (wc, wctype ("alnum"))
363 @end smallexample
365 @pindex wctype.h
366 It is declared in @file{wctype.h}.
367 @end deftypefun
369 @cindex alphabetic character
370 @comment wctype.h
371 @comment ISO
372 @deftypefun int iswalpha (wint_t @var{wc})
373 Returns true if @var{wc} is an alphabetic character (a letter).  If
374 @code{iswlower} or @code{iswupper} is true of a character, then
375 @code{iswalpha} is also true.
377 In some locales, there may be additional characters for which
378 @code{iswalpha} is true---letters which are neither upper case nor lower
379 case.  But in the standard @code{"C"} locale, there are no such
380 additional characters.
382 @noindent
383 This function can be implemented using
385 @smallexample
386 iswctype (wc, wctype ("alpha"))
387 @end smallexample
389 @pindex wctype.h
390 It is declared in @file{wctype.h}.
391 @end deftypefun
393 @cindex control character
394 @comment wctype.h
395 @comment ISO
396 @deftypefun int iswcntrl (wint_t @var{wc})
397 Returns true if @var{wc} is a control character (that is, a character that
398 is not a printing character).
400 @noindent
401 This function can be implemented using
403 @smallexample
404 iswctype (wc, wctype ("cntrl"))
405 @end smallexample
407 @pindex wctype.h
408 It is declared in @file{wctype.h}.
409 @end deftypefun
411 @cindex digit character
412 @comment wctype.h
413 @comment ISO
414 @deftypefun int iswdigit (wint_t @var{wc})
415 Returns true if @var{wc} is a digit (e.g., @samp{0} through @samp{9}).
416 Please note that this function does not only return a nonzero value for
417 @emph{decimal} digits, but for all kinds of digits.  A consequence is
418 that code like the following will @strong{not} work unconditionally for
419 wide characters:
421 @smallexample
422 n = 0;
423 while (iswdigit (*wc))
424   @{
425     n *= 10;
426     n += *wc++ - L'0';
427   @}
428 @end smallexample
430 @noindent
431 This function can be implemented using
433 @smallexample
434 iswctype (wc, wctype ("digit"))
435 @end smallexample
437 @pindex wctype.h
438 It is declared in @file{wctype.h}.
439 @end deftypefun
441 @cindex graphic character
442 @comment wctype.h
443 @comment ISO
444 @deftypefun int iswgraph (wint_t @var{wc})
445 Returns true if @var{wc} is a graphic character; that is, a character
446 that has a glyph associated with it.  The whitespace characters are not
447 considered graphic.
449 @noindent
450 This function can be implemented using
452 @smallexample
453 iswctype (wc, wctype ("graph"))
454 @end smallexample
456 @pindex wctype.h
457 It is declared in @file{wctype.h}.
458 @end deftypefun
460 @cindex lower-case character
461 @comment ctype.h
462 @comment ISO
463 @deftypefun int iswlower (wint_t @var{wc})
464 Returns true if @var{wc} is a lower-case letter.  The letter need not be
465 from the Latin alphabet, any alphabet representable is valid.
467 @noindent
468 This function can be implemented using
470 @smallexample
471 iswctype (wc, wctype ("lower"))
472 @end smallexample
474 @pindex wctype.h
475 It is declared in @file{wctype.h}.
476 @end deftypefun
478 @cindex printing character
479 @comment wctype.h
480 @comment ISO
481 @deftypefun int iswprint (wint_t @var{wc})
482 Returns true if @var{wc} is a printing character.  Printing characters
483 include all the graphic characters, plus the space (@samp{ }) character.
485 @noindent
486 This function can be implemented using
488 @smallexample
489 iswctype (wc, wctype ("print"))
490 @end smallexample
492 @pindex wctype.h
493 It is declared in @file{wctype.h}.
494 @end deftypefun
496 @cindex punctuation character
497 @comment wctype.h
498 @comment ISO
499 @deftypefun int iswpunct (wint_t @var{wc})
500 Returns true if @var{wc} is a punctuation character.
501 This means any printing character that is not alphanumeric or a space
502 character.
504 @noindent
505 This function can be implemented using
507 @smallexample
508 iswctype (wc, wctype ("punct"))
509 @end smallexample
511 @pindex wctype.h
512 It is declared in @file{wctype.h}.
513 @end deftypefun
515 @cindex whitespace character
516 @comment wctype.h
517 @comment ISO
518 @deftypefun int iswspace (wint_t @var{wc})
519 Returns true if @var{wc} is a @dfn{whitespace} character.  In the standard
520 @code{"C"} locale, @code{iswspace} returns true for only the standard
521 whitespace characters:
523 @table @code
524 @item L' '
525 space
527 @item L'\f'
528 formfeed
530 @item L'\n'
531 newline
533 @item L'\r'
534 carriage return
536 @item L'\t'
537 horizontal tab
539 @item L'\v'
540 vertical tab
541 @end table
543 @noindent
544 This function can be implemented using
546 @smallexample
547 iswctype (wc, wctype ("space"))
548 @end smallexample
550 @pindex wctype.h
551 It is declared in @file{wctype.h}.
552 @end deftypefun
554 @cindex upper-case character
555 @comment wctype.h
556 @comment ISO
557 @deftypefun int iswupper (wint_t @var{wc})
558 Returns true if @var{wc} is an upper-case letter.  The letter need not be
559 from the Latin alphabet, any alphabet representable is valid.
561 @noindent
562 This function can be implemented using
564 @smallexample
565 iswctype (wc, wctype ("upper"))
566 @end smallexample
568 @pindex wctype.h
569 It is declared in @file{wctype.h}.
570 @end deftypefun
572 @cindex hexadecimal digit character
573 @comment wctype.h
574 @comment ISO
575 @deftypefun int iswxdigit (wint_t @var{wc})
576 Returns true if @var{wc} is a hexadecimal digit.
577 Hexadecimal digits include the normal decimal digits @samp{0} through
578 @samp{9} and the letters @samp{A} through @samp{F} and
579 @samp{a} through @samp{f}.
581 @noindent
582 This function can be implemented using
584 @smallexample
585 iswctype (wc, wctype ("xdigit"))
586 @end smallexample
588 @pindex wctype.h
589 It is declared in @file{wctype.h}.
590 @end deftypefun
592 The GNU C library also provides a function which is not defined in the
593 @w{ISO C} standard but which is available as a version for single byte
594 characters as well.
596 @cindex blank character
597 @comment wctype.h
598 @comment GNU
599 @deftypefun int iswblank (wint_t @var{wc})
600 Returns true if @var{wc} is a blank character; that is, a space or a tab.
601 This function is a GNU extension.  It is declared in @file{wchar.h}.
602 @end deftypefun
604 @node Using Wide Char Classes, Wide Character Case Conversion, Classification of Wide Characters, Character Handling
605 @section Notes on using the wide character classes
607 The first note is probably not astonishing but still occasionally a
608 cause of problems.  The @code{isw@var{XXX}} functions can be implemented
609 using macros and in fact, the GNU C library does this.  They are still
610 available as real functions but when the @file{wctype.h} header is
611 included the macros will be used.  This is the same as the
612 @code{char} type versions of these functions.
614 The second note covers something new.  It can be best illustrated by a
615 (real-world) example.  The first piece of code is an excerpt from the
616 original code.  It is truncated a bit but the intention should be clear.
618 @smallexample
620 is_in_class (int c, const char *class)
622   if (strcmp (class, "alnum") == 0)
623     return isalnum (c);
624   if (strcmp (class, "alpha") == 0)
625     return isalpha (c);
626   if (strcmp (class, "cntrl") == 0)
627     return iscntrl (c);
628   ...
629   return 0;
631 @end smallexample
633 Now, with the @code{wctype} and @code{iswctype} you can avoid the
634 @code{if} cascades, but rewriting the code as follows is wrong:
636 @smallexample
638 is_in_class (int c, const char *class)
640   wctype_t desc = wctype (class);
641   return desc ? iswctype ((wint_t) c, desc) : 0;
643 @end smallexample
645 The problem is that it is not guaranteed that the wide character
646 representation of a single-byte character can be found using casting.
647 In fact, usually this fails miserably.  The correct solution to this
648 problem is to write the code as follows:
650 @smallexample
652 is_in_class (int c, const char *class)
654   wctype_t desc = wctype (class);
655   return desc ? iswctype (btowc (c), desc) : 0;
657 @end smallexample
659 @xref{Converting a Character}, for more information on @code{btowc}.
660 Note that this change probably does not improve the performance
661 of the program a lot since the @code{wctype} function still has to make
662 the string comparisons.  It gets really interesting if the
663 @code{is_in_class} function is called more than once for the
664 same class name.  In this case the variable @var{desc} could be computed
665 once and reused for all the calls.  Therefore the above form of the
666 function is probably not the final one.
669 @node Wide Character Case Conversion, , Using Wide Char Classes, Character Handling
670 @section Mapping of wide characters.
672 The classification functions are also generalized by the @w{ISO C}
673 standard.  Instead of just allowing the two standard mappings, a
674 locale can contain others.  Again, the @code{localedef} program
675 already supports generating such locale data files.
677 @comment wctype.h
678 @comment ISO
679 @deftp {Data Type} wctrans_t
680 This data type is defined as a scalar type which can hold a value
681 representing the locale-dependent character mapping.  There is no way to
682 construct such a value apart from using the return value of the
683 @code{wctrans} function.
685 @pindex wctype.h
686 @noindent
687 This type is defined in @file{wctype.h}.
688 @end deftp
690 @comment wctype.h
691 @comment ISO
692 @deftypefun wctrans_t wctrans (const char *@var{property})
693 The @code{wctrans} function has to be used to find out whether a named
694 mapping is defined in the current locale selected for the
695 @code{LC_CTYPE} category.  If the returned value is non-zero, you can use
696 it afterwards in calls to @code{towctrans}.  If the return value is
697 zero no such mapping is known in the current locale.
699 Beside locale-specific mappings there are two mappings which are
700 guaranteed to be available in every locale:
702 @multitable @columnfractions .5 .5
703 @item
704 @code{"tolower"} @tab @code{"toupper"}
705 @end multitable
707 @pindex wctype.h
708 @noindent
709 These functions are declared in @file{wctype.h}.
710 @end deftypefun
712 @comment wctype.h
713 @comment ISO
714 @deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc})
715 @code{towctrans} maps the input character @var{wc}
716 according to the rules of the mapping for which @var{desc} is a
717 descriptor, and returns the value it finds.  @var{desc} must be
718 obtained by a successful call to @code{wctrans}.
720 @pindex wctype.h
721 @noindent
722 This function is declared in @file{wctype.h}.
723 @end deftypefun
725 For the generally available mappings, the @w{ISO C} standard defines
726 convenient shortcuts so that it is not necessary to call @code{wctrans}
727 for them.
729 @comment wctype.h
730 @comment ISO
731 @deftypefun wint_t towlower (wint_t @var{wc})
732 If @var{wc} is an upper-case letter, @code{towlower} returns the corresponding
733 lower-case letter.  If @var{wc} is not an upper-case letter,
734 @var{wc} is returned unchanged.
736 @noindent
737 @code{towlower} can be implemented using
739 @smallexample
740 towctrans (wc, wctrans ("tolower"))
741 @end smallexample
743 @pindex wctype.h
744 @noindent
745 This function is declared in @file{wctype.h}.
746 @end deftypefun
748 @comment wctype.h
749 @comment ISO
750 @deftypefun wint_t towupper (wint_t @var{wc})
751 If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding
752 upper-case letter.  Otherwise @var{wc} is returned unchanged.
754 @noindent
755 @code{towupper} can be implemented using
757 @smallexample
758 towctrans (wc, wctrans ("toupper"))
759 @end smallexample
761 @pindex wctype.h
762 @noindent
763 This function is declared in @file{wctype.h}.
764 @end deftypefun
766 The same warnings given in the last section for the use of the wide
767 character classification functions apply here.  It is not possible to
768 simply cast a @code{char} type value to a @code{wint_t} and use it as an
769 argument to @code{towctrans} calls.