1: @node Character Handling, String and Array Utilities, Memory, 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 characters (@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 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
  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: @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.
  271: 
  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.
  278: 
  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.
  284: 
  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.
  291: 
  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.
  298: 
  299: @pindex wctype.h
  300: This type is defined in @file{wctype.h}.
  301: @end deftp
  302: 
  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.
  311: 
  312: @noindent
  313: The properties known in every locale are:
  314: 
  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
  323: 
  324: @pindex wctype.h
  325: This function is declared in @file{wctype.h}.
  326: @end deftypefun
  327: 
  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.
  330: 
  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}.
  337: 
  338: @pindex wctype.h
  339: This function is declared in @file{wctype.h}.
  340: @end deftypefun
  341: 
  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.
  348: 
  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.
  357: 
  358: @noindent
  359: This function can be implemented using
  360: 
  361: @smallexample
  362: iswctype (wc, wctype ("alnum"))
  363: @end smallexample
  364: 
  365: @pindex wctype.h
  366: It is declared in @file{wctype.h}.
  367: @end deftypefun
  368: 
  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.
  376: 
  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.
  381: 
  382: @noindent
  383: This function can be implemented using
  384: 
  385: @smallexample
  386: iswctype (wc, wctype ("alpha"))
  387: @end smallexample
  388: 
  389: @pindex wctype.h
  390: It is declared in @file{wctype.h}.
  391: @end deftypefun
  392: 
  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).
  399: 
  400: @noindent
  401: This function can be implemented using
  402: 
  403: @smallexample
  404: iswctype (wc, wctype ("cntrl"))
  405: @end smallexample
  406: 
  407: @pindex wctype.h
  408: It is declared in @file{wctype.h}.
  409: @end deftypefun
  410: 
  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:
  420: 
  421: @smallexample
  422: n = 0;
  423: while (iswdigit (*wc))
  424:   @{
  425:     n *= 10;
  426:     n += *wc++ - L'0';
  427:   @}
  428: @end smallexample
  429: 
  430: @noindent
  431: This function can be implemented using
  432: 
  433: @smallexample
  434: iswctype (wc, wctype ("digit"))
  435: @end smallexample
  436: 
  437: @pindex wctype.h
  438: It is declared in @file{wctype.h}.
  439: @end deftypefun
  440: 
  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.
  448: 
  449: @noindent
  450: This function can be implemented using
  451: 
  452: @smallexample
  453: iswctype (wc, wctype ("graph"))
  454: @end smallexample
  455: 
  456: @pindex wctype.h
  457: It is declared in @file{wctype.h}.
  458: @end deftypefun
  459: 
  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.
  466: 
  467: @noindent
  468: This function can be implemented using
  469: 
  470: @smallexample
  471: iswctype (wc, wctype ("lower"))
  472: @end smallexample
  473: 
  474: @pindex wctype.h
  475: It is declared in @file{wctype.h}.
  476: @end deftypefun
  477: 
  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.
  484: 
  485: @noindent
  486: This function can be implemented using
  487: 
  488: @smallexample
  489: iswctype (wc, wctype ("print"))
  490: @end smallexample
  491: 
  492: @pindex wctype.h
  493: It is declared in @file{wctype.h}.
  494: @end deftypefun
  495: 
  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.
  503: 
  504: @noindent
  505: This function can be implemented using
  506: 
  507: @smallexample
  508: iswctype (wc, wctype ("punct"))
  509: @end smallexample
  510: 
  511: @pindex wctype.h
  512: It is declared in @file{wctype.h}.
  513: @end deftypefun
  514: 
  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:
  522: 
  523: @table @code
  524: @item L' '
  525: space
  526: 
  527: @item L'\f'
  528: formfeed
  529: 
  530: @item L'\n'
  531: newline
  532: 
  533: @item L'\r'
  534: carriage return
  535: 
  536: @item L'\t'
  537: horizontal tab
  538: 
  539: @item L'\v'
  540: vertical tab
  541: @end table
  542: 
  543: @noindent
  544: This function can be implemented using
  545: 
  546: @smallexample
  547: iswctype (wc, wctype ("space"))
  548: @end smallexample
  549: 
  550: @pindex wctype.h
  551: It is declared in @file{wctype.h}.
  552: @end deftypefun
  553: 
  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.
  560: 
  561: @noindent
  562: This function can be implemented using
  563: 
  564: @smallexample
  565: iswctype (wc, wctype ("upper"))
  566: @end smallexample
  567: 
  568: @pindex wctype.h
  569: It is declared in @file{wctype.h}.
  570: @end deftypefun
  571: 
  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}.
  580: 
  581: @noindent
  582: This function can be implemented using
  583: 
  584: @smallexample
  585: iswctype (wc, wctype ("xdigit"))
  586: @end smallexample
  587: 
  588: @pindex wctype.h
  589: It is declared in @file{wctype.h}.
  590: @end deftypefun
  591: 
  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.
  595: 
  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
  604: 
  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
  607: 
  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.
  614: 
  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.
  618: 
  619: @smallexample
  620: int
  621: is_in_class (int c, const char *class)
  622: @{
  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;
  631: @}
  632: @end smallexample
  633: 
  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:
  636: 
  637: @smallexample
  638: int
  639: is_in_class (int c, const char *class)
  640: @{
  641:   wctype_t desc = wctype (class);
  642:   return desc ? iswctype ((wint_t) c, desc) : 0;
  643: @}
  644: @end smallexample
  645: 
  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:
  650: 
  651: @smallexample
  652: int
  653: is_in_class (int c, const char *class)
  654: @{
  655:   wctype_t desc = wctype (class);
  656:   return desc ? iswctype (btowc (c), desc) : 0;
  657: @}
  658: @end smallexample
  659: 
  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.
  668: 
  669: 
  670: @node Wide Character Case Conversion, , Using Wide Char Classes, Character Handling
  671: @section Mapping of wide characters.
  672: 
  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.
  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 apart from 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, 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.
  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: These functions are 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: @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}.
  720: 
  721: @pindex wctype.h
  722: @noindent
  723: This function is declared in @file{wctype.h}.
  724: @end deftypefun
  725: 
  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.
  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 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.