home | help 
Tcl_UtfToUpper(3)	     Tcl Library Procedures	       Tcl_UtfToUpper(3)

________________________________________________________________________________

NAME
     Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper,
     Tcl_UtfToLower, Tcl_UtfToTitle - routines for manipulating the case of Uni-
     code characters and UTF-8 strings

SYNOPSIS
     #include <tcl.h>

     int
     Tcl_UniCharToUpper(ch)

     int
     Tcl_UniCharToLower(ch)

     int
     Tcl_UniCharToTitle(ch)

     Tcl_Size
     Tcl_UtfToUpper(str)

     Tcl_Size
     Tcl_UtfToLower(str)

     Tcl_Size
     Tcl_UtfToTitle(str)

ARGUMENTS
     int ch (in)	     The Unicode character to be converted.

     char *str (in/out)      Pointer to the TUTF-8 byte sequence to be converted
			     in place.
________________________________________________________________________________

DESCRIPTION
     N.B.  Refer  to the Tcl_UniChar documentation page for a description of the
     TUTF-8 encoding and related terms referenced here.

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

     If ch represents a lower-case  character,	Tcl_UniCharToUpper  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_UniCharToLower 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_UniCharToTitle  returns  the
     corresponding title-case character.  If no title-case character is defined,
     it  returns the corresponding upper-case character.  If no upper-case char-
     acter is defined, it returns the character unchanged.   Title-case  is  de-
     fined  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 null-terminated TUTF-8 byte se-
     quences in place in memory:

     Tcl_UtfToUpper changes every TUTF-8 encoded character in str to upper-case.
     Because changing the case of a character may change its size, the byte off-
     set of each character in the resulting string may differ from its	original
     location.	 Tcl_UtfToUpper  writes  a null byte at the end of the converted
     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.

KEYWORDS
     utf, unicode, toupper, tolower, totitle, case

Tcl				       8.1		       Tcl_UtfToUpper(3)
home | help