1Tcl_UtfToUpper(3)           Tcl Library Procedures           Tcl_UtfToUpper(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_UniCharToUpper,       Tcl_UniCharToLower,       Tcl_UniCharToTitle,
9       Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle - routines  for  manipu‐
10       lating the case of Unicode characters and UTF-8 strings
11

SYNOPSIS

13       #include <tcl.h>
14
15       Tcl_UniChar
16       Tcl_UniCharToUpper(ch)
17
18       Tcl_UniChar
19       Tcl_UniCharToLower(ch)
20
21       Tcl_UniChar
22       Tcl_UniCharToTitle(ch)
23
24       int
25       Tcl_UtfToUpper(str)
26
27       int
28       Tcl_UtfToLower(str)
29
30       int
31       Tcl_UtfToTitle(str)
32

ARGUMENTS

34       int ch (in)             The Unicode character to be converted.
35
36       char *str (in/out)      Pointer  to  UTF-8  string  to  be converted in
37                               place.
38______________________________________________________________________________
39
40

DESCRIPTION

42       The first three routines convert the case of individual Unicode charac‐
43       ters:
44
45       If ch represents a lower-case character, Tcl_UniCharToUpper returns the
46       corresponding upper-case character.  If no upper-case character is  de‐
47       fined, it returns the character unchanged.
48
49       If  ch  represents  an upper-case character, Tcl_UniCharToLower returns
50       the corresponding lower-case character.  If no lower-case character  is
51       defined, it returns the character unchanged.
52
53       If ch represents a lower-case character, Tcl_UniCharToTitle returns the
54       corresponding title-case character.  If no title-case character is  de‐
55       fined, it returns the corresponding upper-case character.  If no upper-
56       case character is defined, it returns the character unchanged.   Title-
57       case  is defined for a small number of characters that have a different
58       appearance when they are at the beginning of a capitalized word.
59
60       The next three routines convert the case of UTF-8 strings in  place  in
61       memory:
62
63       Tcl_UtfToUpper changes every UTF-8 character in str to upper-case.  Be‐
64       cause changing the case of a character may change its  size,  the  byte
65       offset  of  each  character in the resulting string may differ from its
66       original location.  Tcl_UtfToUpper writes a null byte at the end of the
67       converted  string.  Tcl_UtfToUpper returns the new length of the string
68       in bytes.  This new length is guaranteed to be no longer than the orig‐
69       inal string length.
70
71       Tcl_UtfToLower is the same as Tcl_UtfToUpper except it turns each char‐
72       acter in the string into its lower-case equivalent.
73
74       Tcl_UtfToTitle is the same as Tcl_UtfToUpper except it turns the  first
75       character  in the string into its title-case equivalent and all follow‐
76       ing characters into their lower-case equivalents.
77
78

BUGS

80       At this time, the case conversions are only  defined  for  the  Unicode
81       plane  0 characters.  The result for Unicode characters above 0xFFFF is
82       undefined, but - actually - only the lower 16  bits  of  the  character
83       value is handled.
84
85

KEYWORDS

87       utf, unicode, toupper, tolower, totitle, case
88
89
90
91Tcl                                   8.1                    Tcl_UtfToUpper(3)