(Using Wide Char Classes): Add comma.
[kopensolaris-gnu/glibc.git] / manual / ctype.texi
1 @node Character Handling, String and Array Utilities, Memory Allocation, Top
2 @c %MENU% Character testing and conversion functions
3 @chapter Character Handling
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 @pindex ctype.h
11
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}.)
17
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 character (@pxref{Extended Char Intro}).
21
22 @menu
23 * Classification of Characters::       Testing whether characters are
24                                         letters, digits, punctuation, etc.
25
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
33
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
40
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:
46
47 @smallexample
48 if (isalpha (c))
49   printf ("The character `%c' is alphabetic.\n", c);
50 @end smallexample
51
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.
58
59 The attributes of any given character can vary between locales.
60 @xref{Locales}, for more information on locales.@refill
61
62 These functions are declared in the header file @file{ctype.h}.
63 @pindex ctype.h
64
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
72
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
80
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.
88
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
94
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
102
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
111
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
121
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
130
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:
138
139 @table @code
140 @item ' '
141 space
142
143 @item '\f'
144 formfeed
145
146 @item '\n'
147 newline
148
149 @item '\r'
150 carriage return
151
152 @item '\t'
153 horizontal tab
154
155 @item '\v'
156 vertical tab
157 @end table
158 @end deftypefun
159
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
167
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
176
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
184
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
192
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
201
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
207
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.
212
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.
217
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)}.
223
224 These functions are declared in the header file @file{ctype.h}.
225 @pindex ctype.h
226
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
234
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
241
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
249
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
256
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
263
264
265 @node Classification of Wide Characters, Using Wide Char Classes, Case Conversion, Character Handling
266 @section Character class determination for wide characters
267
268 The second amendment to @w{ISO C89} defines functions to classify wide
269 character.  Although the original @w{ISO C89} standard already defined
270 the type @code{wchar_t} but no functions operating on them were defined.
271
272 The general design of the classification functions for wide characters
273 is more general.  It allows to extend the set of available
274 classification beyond the set which is always available.  The POSIX
275 standard specifies a way how the extension can be done and this is
276 already implemented in the GNU C library implementation of the
277 @code{localedef} program.
278
279 The character class functions are normally implemented using bitsets.
280 I.e., for the character in question the appropriate bitset is read from
281 a table and a test is performed whether a certain bit is set in this
282 bitset.  Which bit is tested for is determined by the class.
283
284 For the wide character classification functions this is made visible.
285 There is a type representing the classification, a function to retrieve
286 this value for a specific class, and a function to test using the
287 classification value whether a given character is in this class.  On top
288 of this the normal character classification functions as used for
289 @code{char} objects can be defined.
290
291 @comment wctype.h
292 @comment ISO
293 @deftp {Data type} wctype_t
294 The @code{wctype_t} can hold a value which represents a character class.
295 The ony defined way to generate such a value is by using the
296 @code{wctype} function.
297
298 @pindex wctype.h
299 This type is defined in @file{wctype.h}.
300 @end deftp
301
302 @comment wctype.h
303 @comment ISO
304 @deftypefun wctype_t wctype (const char *@var{property})
305 The @code{wctype} returns a value representing a class of wide
306 characters which is identified by the string @var{property}.  Beside
307 some standard properties each locale can define its own ones.  In case
308 no property with the given name is known for the current locale for the
309 @code{LC_CTYPE} category the function returns zero.
310
311 @noindent
312 The properties known in every locale are:
313
314 @multitable @columnfractions .25 .25 .25 .25
315 @item
316 @code{"alnum"} @tab @code{"alpha"} @tab @code{"cntrl"} @tab @code{"digit"}
317 @item
318 @code{"graph"} @tab @code{"lower"} @tab @code{"print"} @tab @code{"punct"}
319 @item
320 @code{"space"} @tab @code{"upper"} @tab @code{"xdigit"}
321 @end multitable
322
323 @pindex wctype.h
324 This function is declared in @file{wctype.h}.
325 @end deftypefun
326
327 To test the membership of a character to one of the non-standard classes
328 the @w{ISO C} standard defines a completely new function.
329
330 @comment wctype.h
331 @comment ISO
332 @deftypefun int iswctype (wint_t @var{wc}, wctype_t @var{desc})
333 This function returns a nonzero value if @var{wc} is in the character
334 class specified by @var{desc}.  @var{desc} must previously be returned
335 by a successful call to @code{wctype}.
336
337 @pindex wctype.h
338 This function is declared in @file{wctype.h}.
339 @end deftypefun
340
341 The make it easier to use the commonly used classification functions
342 they are defined in the C library.  There is no need to use
343 @code{wctype} is the property string is one of the known character
344 classes.  In some situations it is desirable to construct the property
345 string and then it gets important that @code{wctype} can also handle the
346 standard classes.
347
348 @cindex alphanumeric character
349 @comment wctype.h
350 @comment ISO
351 @deftypefun int iswalnum (wint_t @var{wc})
352 This function returns a nonzero value if @var{wc} is an alphanumeric
353 character (a letter or number); in other words, if either @code{iswalpha}
354 or @code{iswdigit} is true of a character, then @code{iswalnum} is also
355 true.
356
357 @noindent
358 This function can be implemented using
359
360 @smallexample
361 iswctype (wc, wctype ("alnum"))
362 @end smallexample
363
364 @pindex wctype.h
365 It is declared in @file{wctype.h}.
366 @end deftypefun
367
368 @cindex alphabetic character
369 @comment wctype.h
370 @comment ISO
371 @deftypefun int iswalpha (wint_t @var{wc})
372 Returns true if @var{wc} is an alphabetic character (a letter).  If
373 @code{iswlower} or @code{iswupper} is true of a character, then
374 @code{iswalpha} is also true.
375
376 In some locales, there may be additional characters for which
377 @code{iswalpha} is true---letters which are neither upper case nor lower
378 case.  But in the standard @code{"C"} locale, there are no such
379 additional characters.
380
381 @noindent
382 This function can be implemented using
383
384 @smallexample
385 iswctype (wc, wctype ("alpha"))
386 @end smallexample
387
388 @pindex wctype.h
389 It is declared in @file{wctype.h}.
390 @end deftypefun
391
392 @cindex control character
393 @comment wctype.h
394 @comment ISO
395 @deftypefun int iswcntrl (wint_t @var{wc})
396 Returns true if @var{wc} is a control character (that is, a character that
397 is not a printing character).
398
399 @noindent
400 This function can be implemented using
401
402 @smallexample
403 iswctype (wc, wctype ("cntrl"))
404 @end smallexample
405
406 @pindex wctype.h
407 It is declared in @file{wctype.h}.
408 @end deftypefun
409
410 @cindex digit character
411 @comment wctype.h
412 @comment ISO
413 @deftypefun int iswdigit (wint_t @var{wc})
414 Returns true if @var{wc} is a digit (e.g., @samp{0} through @samp{9}).
415 Please note that this function does not only return a nonzero value for
416 @emph{decimal} digits, but for all kinds of digits.  A consequence is
417 that code like the following will @strong{not} work unconditionally for
418 wide characters:
419
420 @smallexample
421 n = 0;
422 while (iswctype (*wc))
423   @{
424     n *= 10;
425     n += *wc++ - L'0';
426   @}
427 @end smallexample
428
429 @noindent
430 This function can be implemented using
431
432 @smallexample
433 iswctype (wc, wctype ("digit"))
434 @end smallexample
435
436 @pindex wctype.h
437 It is declared in @file{wctype.h}.
438 @end deftypefun
439
440 @cindex graphic character
441 @comment wctype.h
442 @comment ISO
443 @deftypefun int iswgraph (wint_t @var{wc})
444 Returns true if @var{wc} is a graphic character; that is, a character
445 that has a glyph associated with it.  The whitespace characters are not
446 considered graphic.
447
448 @noindent
449 This function can be implemented using
450
451 @smallexample
452 iswctype (wc, wctype ("graph"))
453 @end smallexample
454
455 @pindex wctype.h
456 It is declared in @file{wctype.h}.
457 @end deftypefun
458
459 @cindex lower-case character
460 @comment ctype.h
461 @comment ISO
462 @deftypefun int iswlower (wint_t @var{wc})
463 Returns true if @var{wc} is a lower-case letter.  The letter need not be
464 from the Latin alphabet, any alphabet representable is valid.
465
466 @noindent
467 This function can be implemented using
468
469 @smallexample
470 iswctype (wc, wctype ("lower"))
471 @end smallexample
472
473 @pindex wctype.h
474 It is declared in @file{wctype.h}.
475 @end deftypefun
476
477 @cindex printing character
478 @comment wctype.h
479 @comment ISO
480 @deftypefun int iswprint (wint_t @var{wc})
481 Returns true if @var{wc} is a printing character.  Printing characters
482 include all the graphic characters, plus the space (@samp{ }) character.
483
484 @noindent
485 This function can be implemented using
486
487 @smallexample
488 iswctype (wc, wctype ("print"))
489 @end smallexample
490
491 @pindex wctype.h
492 It is declared in @file{wctype.h}.
493 @end deftypefun
494
495 @cindex punctuation character
496 @comment wctype.h
497 @comment ISO
498 @deftypefun int iswpunct (wint_t @var{wc})
499 Returns true if @var{wc} is a punctuation character.
500 This means any printing character that is not alphanumeric or a space
501 character.
502
503 @noindent
504 This function can be implemented using
505
506 @smallexample
507 iswctype (wc, wctype ("punct"))
508 @end smallexample
509
510 @pindex wctype.h
511 It is declared in @file{wctype.h}.
512 @end deftypefun
513
514 @cindex whitespace character
515 @comment wctype.h
516 @comment ISO
517 @deftypefun int iswspace (wint_t @var{wc})
518 Returns true if @var{wc} is a @dfn{whitespace} character.  In the standard
519 @code{"C"} locale, @code{iswspace} returns true for only the standard
520 whitespace characters:
521
522 @table @code
523 @item L' '
524 space
525
526 @item L'\f'
527 formfeed
528
529 @item L'\n'
530 newline
531
532 @item L'\r'
533 carriage return
534
535 @item L'\t'
536 horizontal tab
537
538 @item L'\v'
539 vertical tab
540 @end table
541
542 @noindent
543 This function can be implemented using
544
545 @smallexample
546 iswctype (wc, wctype ("space"))
547 @end smallexample
548
549 @pindex wctype.h
550 It is declared in @file{wctype.h}.
551 @end deftypefun
552
553 @cindex upper-case character
554 @comment wctype.h
555 @comment ISO
556 @deftypefun int iswupper (wint_t @var{wc})
557 Returns true if @var{wc} is an upper-case letter.  The letter need not be
558 from the Latin alphabet, any alphabet representable is valid.
559
560 @noindent
561 This function can be implemented using
562
563 @smallexample
564 iswctype (wc, wctype ("upper"))
565 @end smallexample
566
567 @pindex wctype.h
568 It is declared in @file{wctype.h}.
569 @end deftypefun
570
571 @cindex hexadecimal digit character
572 @comment wctype.h
573 @comment ISO
574 @deftypefun int iswxdigit (wint_t @var{wc})
575 Returns true if @var{wc} is a hexadecimal digit.
576 Hexadecimal digits include the normal decimal digits @samp{0} through
577 @samp{9} and the letters @samp{A} through @samp{F} and
578 @samp{a} through @samp{f}.
579
580 @noindent
581 This function can be implemented using
582
583 @smallexample
584 iswctype (wc, wctype ("xdigit"))
585 @end smallexample
586
587 @pindex wctype.h
588 It is declared in @file{wctype.h}.
589 @end deftypefun
590
591 The GNu C library provides also a function which is not defined in the
592 @w{ISO C} standard but which is available as a version for single byte
593 characters as well.
594
595 @cindex blank character
596 @comment wctype.h
597 @comment GNU
598 @deftypefun int iswblank (wint_t @var{wc})
599 Returns true if @var{wc} is a blank character; that is, a space or a tab.
600 This function is a GNU extension.  It is declared in @file{wchar.h}.
601 @end deftypefun
602
603 @node Using Wide Char Classes, Wide Character Case Conversion, Classification of Wide Characters, Character Handling
604 @section Notes on using the wide character classes
605
606 The first note is probably nothing astonishing but still occasionally a
607 cause of problems.  The @code{isw@var{XXX}} functions can be implemented
608 using macros and in fact, the GNU C library does this.  They are still
609 available as real functions but when the @file{wctype.h} header is
610 included the macros will be used.  This is nothing new compared to the
611 @code{char} type versions of these functions.
612
613 The second notes covers something which is new.  It can be best
614 illustrated by a (real-world) example.  The first piece of code is an
615 excerpt from the original code.  It is truncated a bit but the intention
616 should be clear.
617
618 @smallexample
619 int
620 is_in_class (int c, const char *class)
621 @{
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;
630 @}
631 @end smallexample
632
633 Now with the @code{wctype} and @code{iswctype} one could avoid the
634 @code{if} cascades.  But rewriting the code as follows is wrong:
635
636 @smallexample
637 int
638 is_in_class (int c, const char *class)
639 @{
640   wctype_t desc = wctype (class);
641   return desc ? iswctype ((wint_t) c, desc) : 0;
642 @}
643 @end smallexample
644
645 The problem is that it is not guarateed 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 for this
648 problem is to write the code as follows:
649
650 @smallexample
651 int
652 is_in_class (int c, const char *class)
653 @{
654   wctype_t desc = wctype (class);
655   return desc ? iswctype (btowc (c), desc) : 0;
656 @}
657 @end smallexample
658
659 @xref{Converting a Character}, for more information on @code{btowc}.
660 Please 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.  But it gets really interesting if the
663 @code{is_in_class} function would be called more than once using 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.
667
668
669 @node Wide Character Case Conversion, , Using Wide Char Classes, Character Handling
670 @section Mapping of wide characters.
671
672 As for the classification functions the @w{ISO C} standard also
673 generalizes the mapping functions.  Instead of only allowing the two
674 standard mappings the locale can contain others.  Again, the
675 @code{localedef} program already supports generating such locale data
676 files.
677
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 beside using the return value of the
684 @code{wctrans} function.
685
686 @pindex wctype.h
687 @noindent
688 This type is defined in @file{wctype.h}.
689 @end deftp
690
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 it can
697 afterwards be used in calls to @code{towctrans}.  If the return value is
698 zero no such mapping is known in the current locale.
699
700 Beside locale-specific mappings there are two mappings which are
701 guaranteed to be available in every locale:
702
703 @multitable @columnfractions .5 .5
704 @item
705 @code{"tolower"} @tab @code{"toupper"}
706 @end multitable
707
708 @pindex wctype.h
709 @noindent
710 This function is declared in @file{wctype.h}.
711 @end deftypefun
712
713 @comment wctype.h
714 @comment ISO
715 @deftypefun wint_t towctrans (wint_t @var{wc}, wctrans_t @var{desc})
716 The @code{towctrans} function maps the input character @var{wc}
717 according to the rules of the mapping for which @var{desc} is an
718 descriptor and returns the so found value.  The @var{desc} value must be
719 obtained by a successful call to @code{wctrans}.
720
721 @pindex wctype.h
722 @noindent
723 This function is declared in @file{wctype.h}.
724 @end deftypefun
725
726 The @w{ISO C} standard also defines for the generally available mappings
727 convenient shortcuts so that it is not necesary to call @code{wctrans}
728 for them.
729
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.
736
737 @noindent
738 @code{towlower} can be implemented using
739
740 @smallexample
741 towctrans (wc, wctrans ("tolower"))
742 @end smallexample
743
744 @pindex wctype.h
745 @noindent
746 This function is declared in @file{wctype.h}.
747 @end deftypefun
748
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.
754
755 @noindent
756 @code{towupper} can be implemented using
757
758 @smallexample
759 towctrans (wc, wctrans ("toupper"))
760 @end smallexample
761
762 @pindex wctype.h
763 @noindent
764 This function is declared in @file{wctype.h}.
765 @end deftypefun
766
767 The same warnings given in the last section for the use of the wide
768 character classiffication function applies 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 for @code{towctrans} calls.