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
47       defined, 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
55       defined,  it  returns  the  corresponding  upper-case character.  If no
56       upper-case character is defined, it returns  the  character  unchanged.
57       Title-case is defined for a small number of characters that have a dif‐
58       ferent 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.
64       Because 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)