Update from translation team.
[glibc.git] / manual / ctype.texi
blobb275a54c57b06de94f3e7383669b052ec475516d
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 ISO
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 was originally a GNU extension, but was added in @w{ISO C99}.
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 ISO
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 was originally a GNU extension, but was added in @w{ISO C99}.
602 It is declared in @file{wchar.h}.
603 @end deftypefun
605 @node Using Wide Char Classes, Wide Character Case Conversion, Classification of Wide Characters, Character Handling
606 @section Notes on using the wide character classes
608 The first note is probably not astonishing but still occasionally a
609 cause of problems.  The @code{isw@var{XXX}} functions can be implemented
610 using macros and in fact, the GNU C library does this.  They are still
611 available as real functions but when the @file{wctype.h} header is
612 included the macros will be used.  This is the same as the
613 @code{char} type versions of these functions.
615 The second note covers something new.  It can be best illustrated by a
616 (real-world) example.  The first piece of code is an excerpt from the
617 original code.  It is truncated a bit but the intention should be clear.
619 @smallexample
621 is_in_class (int c, const char *class)
623   if (strcmp (class, "alnum") == 0)
624     return isalnum (c);
625   if (strcmp (class, "alpha") == 0)
626     return isalpha (c);
627   if (strcmp (class, "cntrl") == 0)
628     return iscntrl (c);
629   @dots{}
630   return 0;
632 @end smallexample
634 Now, with the @code{wctype} and @code{iswctype} you can avoid the
635 @code{if} cascades, but rewriting the code as follows is wrong:
637 @smallexample
639 is_in_class (int c, const char *class)
641   wctype_t desc = wctype (class);
642   return desc ? iswctype ((wint_t) c, desc) : 0;
644 @end smallexample
646 The problem is that it is not guaranteed that the wide character
647 representation of a single-byte character can be found using casting.
648 In fact, usually this fails miserably.  The correct solution to this
649 problem is to write the code as follows:
651 @smallexample
653 is_in_class (int c, const char *class)
655   wctype_t desc = wctype (class);
656   return desc ? iswctype (btowc (c), desc) : 0;
658 @end smallexample
660 @xref{Converting a Character}, for more information on @code{btowc}.
661 Note that this change probably does not improve the performance
662 of the program a lot since the @code{wctype} function still has to make
663 the string comparisons.  It gets really interesting if the
664 @code{is_in_class} function is called more than once for the
665 same class name.  In this case the variable @var{desc} could be computed
666 once and reused for all the calls.  Therefore the above form of the
667 function is probably not the final one.
670 @node Wide Character Case Conversion, , Using Wide Char Classes, Character Handling
671 @section Mapping of wide characters.
673 The classification functions are also generalized by the @w{ISO C}
674 standard.  Instead of just allowing the two standard mappings, a
675 locale can contain others.  Again, the @code{localedef} program
676 already supports generating such locale data files.
678 @comment wctype.h
679 @comment ISO
680 @deftp {Data Type} wctrans_t
681 This data type is defined as a scalar type which can hold a value
682 representing the locale-dependent character mapping.  There is no way to
683 construct such a value apart from using the return value of the
684 @code{wctrans} function.
686 @pindex wctype.h
687 @noindent
688 This type is defined in @file{wctype.h}.
689 @end deftp
691 @comment wctype.h
692 @comment ISO
693 @deftypefun wctrans_t wctrans (const char *@var{property})
694 The @code{wctrans} function has to be used to find out whether a named
695 mapping is defined in the current locale selected for the
696 @code{LC_CTYPE} category.  If the returned value is non-zero, you can use
697 it afterwards in calls to @code{towctrans}.  If the return value is
698 zero no such mapping is known in the current locale.
700 Beside locale-specific mappings there are two mappings which are
701 guaranteed to be available in every locale:
703 @multitable @columnfractions .5 .5
704 @item
705 @code{"tolower"} @tab @code{"toupper"}
706 @end multitable
708 @pindex wctype.h
709 @noindent
710 These functions are declared in @file{wctype.h}.
711 @end deftypefun
713 @comment wctype.h
714 @comment ISO
715 @deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc})
716 @code{towctrans} maps the input character @var{wc}
717 according to the rules of the mapping for which @var{desc} is a
718 descriptor, and returns the value it finds.  @var{desc} must be
719 obtained by a successful call to @code{wctrans}.
721 @pindex wctype.h
722 @noindent
723 This function is declared in @file{wctype.h}.
724 @end deftypefun
726 For the generally available mappings, the @w{ISO C} standard defines
727 convenient shortcuts so that it is not necessary to call @code{wctrans}
728 for them.
730 @comment wctype.h
731 @comment ISO
732 @deftypefun wint_t towlower (wint_t @var{wc})
733 If @var{wc} is an upper-case letter, @code{towlower} returns the corresponding
734 lower-case letter.  If @var{wc} is not an upper-case letter,
735 @var{wc} is returned unchanged.
737 @noindent
738 @code{towlower} can be implemented using
740 @smallexample
741 towctrans (wc, wctrans ("tolower"))
742 @end smallexample
744 @pindex wctype.h
745 @noindent
746 This function is declared in @file{wctype.h}.
747 @end deftypefun
749 @comment wctype.h
750 @comment ISO
751 @deftypefun wint_t towupper (wint_t @var{wc})
752 If @var{wc} is a lower-case letter, @code{towupper} returns the corresponding
753 upper-case letter.  Otherwise @var{wc} is returned unchanged.
755 @noindent
756 @code{towupper} can be implemented using
758 @smallexample
759 towctrans (wc, wctrans ("toupper"))
760 @end smallexample
762 @pindex wctype.h
763 @noindent
764 This function is declared in @file{wctype.h}.
765 @end deftypefun
767 The same warnings given in the last section for the use of the wide
768 character classification functions apply here.  It is not possible to
769 simply cast a @code{char} type value to a @code{wint_t} and use it as an
770 argument to @code{towctrans} calls.