NAME

       Tcl_UniCharToUpper,  Tcl_UniCharToLower,  Tcl_UniCharToTi­
       tle, Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle - rou­
       tines  for manipulating the case of Unicode characters and
       UTF-8 strings.


SYNOPSIS

       #include <tcl.h>

       Tcl_UniChar
       Tcl_UniCharToUpper(ch)

       Tcl_UniChar
       Tcl_UniCharToLower(ch)

       Tcl_UniChar
       Tcl_UniCharToTitle(ch)

       int
       Tcl_UtfToUpper(str)

       int
       Tcl_UtfToLower(str)

       int
       Tcl_UtfToTitle(str)


ARGUMENTS

       int    ch     (in)      The Tcl_UniChar to be converted.

       char   *str   (in/out)  Pointer to UTF-8 string to be con­
                               verted in place.
_________________________________________________________________



DESCRIPTION

       The  first  three  routines convert the case of individual
       Unicode characters:

       If ch represents a lower-case character,  Tcl_UniCharToUp­
       per returns the corresponding upper-case character.  If no
       upper-case character is defined, it returns the  character
       unchanged.

       If  ch  represents  an  upper-case character, Tcl_UniChar­
       ToLower returns the  corresponding  lower-case  character.
       If  no  lower-case  character  is  defined, it returns the
       character unchanged.

       If ch represents a lower-case character,  Tcl_UniCharToTi­
       tle returns the corresponding title-case character.  If no
       character is defined, it returns the character  unchanged.
       Title-case  is  defined  for  a small number of characters
       that have a different appearance  when  they  are  at  the
       beginning of a capitalized word.

       The  next three routines convert the case of UTF-8 strings
       in place in memory:

       Tcl_UtfToUpper changes every UTF-8  character  in  str  to
       upper-case.   Because changing the case of a character may
       change its size, the byte offset of each character in  the
       resulting  string  may  differ from its original location.
       Tcl_UtfToUpper writes a null byte at the end of  the  con­
       verted  string.   Tcl_UtfToUpper returns the new length of
       the string in bytes.  This new length is guaranteed to  be
       no longer than the original string length.

       Tcl_UtfToLower  is  the  same  as Tcl_UtfToUpper except it
       turns each character in the  string  into  its  lower-case
       equivalent.

       Tcl_UtfToTitle  is  the  same  as Tcl_UtfToUpper except it
       turns the first character in the string  into  its  title-
       case  equivalent  and  all following characters into their
       lower-case equivalents.



BUGS

       At this time, the case conversions are  only  defined  for
       the ISO8859-1 characters.  Unicode characters above 0x00ff
       are not modified by these routines.



KEYWORDS

       utf, unicode, toupper, tolower, totitle, case