TclUtfToUpper(3) Tcl Library Procedures TclUtfToUpper(3)

NAME
       TclUniCharToUpper,       TclUniCharToLower,       TclUniCharToTitle,
       TclUtfToUpper, TclUtfToLower, TclUtfToTitle - routines  for  manipu-
       lating the case of Unicode characters and UTF-8 strings.

SYNOPSIS
       ##iinncclluuddee <>

       TclUniChar
       TTccllUUnniiCChhaarrTTooUUppppeerr(ch)

       TclUniChar
       TTccllUUnniiCChhaarrTTooLLoowweerr(ch)

       TclUniChar
       TTccllUUnniiCChhaarrTTooTTiittllee(ch)

       int
       TTccllUUttffTTooUUppppeerr(str)

       int
       TTccllUUttffTTooLLoowweerr(str)

       int
       TTccllUUttffTTooTTiittllee(str)

AARRGGUUMMEENNTTSS
       int    ch     (in)      The TclUniChar to be converted.

       char   *str   (in/out)  Pointer  to  UTF-8  string  to  be converted in
                               place.



DESCRIPTION
       The first three routines convert the case of individual Unicode charac-
       ters:

       If ch represents a lower-case character, TTccllUUnniiCChhaarrTTooUUppppeerr 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, TTccllUUnniiCChhaarrTTooLLoowweerr 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, TTccllUUnniiCChhaarrTTooTTiittllee returns the
       corresponding title-case character.   If  no  title-case  character  is
       defined,  it  returns  the  corresponding  upper-case character.  If no
       upper-case character is defined, it returns  the  character  unchanged.
       Title-case is defined for a small number of characters that have a dif-
       ferent 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:

       TTccllUUttffTTooUUppppeerr 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.  TTccllUUttffTTooUUppppeerr writes a null byte at the end of the
       converted string.  TTccllUUttffTTooUUppppeerr returns the new length of the  string
       in bytes.  This new length is guaranteed to be no longer than the orig-
       inal string length.

       TTccllUUttffTTooLLoowweerr is the same as TTccllUUttffTTooUUppppeerr except it turns each char-
       acter in the string into its lower-case equivalent.

       TTccllUUttffTTooTTiittllee  is the same as TTccllUUttffTTooUUppppeerr except it turns the first
       character in the string into its title-case equivalent and all  follow-
       ing 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.


KKEEYYWWOORRDDSS
       utf, unicode, toupper, tolower, totitle, case



Tcl                                   8.1                    TclUtfToUpper(3)