Check-in [0220e14300]

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:More TIP #548 explanation.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 0220e14300e4793463169ed358187c3ee1244e742808cdb6548c8309b7daa58e
User & Date: jan.nijtmans 2019-06-03 15:14:27
Context
2019-06-05
19:51
Formatting cleanup for TIP 461 check-in: 53528a425f user: dkf tags: trunk
2019-06-03
15:14
More TIP #548 explanation. check-in: 0220e14300 user: jan.nijtmans tags: trunk
14:41
New TIP #548: Deprecate Tcl_WinUtfToTChar() and Tcl_WinTCharToUtf() and provide more flexible replacement functions. check-in: b092de73ae user: jan.nijtmans tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to tip/548.md.

32
33
34
35
36
37
38
39
40
41

42
43

44
45
46


47
48
49

50
51
52
53
54
55
























56
57
58
59
60
61
62
 * Deprecate the following functions:

     Tcl\_WinUtfToTChar()

     Tcl\_WinTCharToUtf()

   If Tcl is compiled with either -DTCL\_UTF\_MAX=6 (which is not officially supported) or -DTCL\_NO\_DEPRECATED, those functions will
   no longer be available for extensions. In Tcl 9.0, those functions will be completely removed.

 * New functions:

     
     Tcl\_Utf16ToUtfDString()

     
     Tcl\_UtfToUtf16DString()



     Those are the same as the _UniChar_ variants (Tcl\_UniCharToUtfDString/Tcl\_UtfToUniCharDString), but they use an "unsigned short"
     pointer type in their signature stead of a Tcl\_UniChar pointer type.
     In addition, Tcl\_Utf16ToUtfDString() now accepts the value -1 as length parameter.


     Those functions can be used if you want your extension to compile with -DTCL\_UTF\_MAX=3, -DTCL\_UTF\_MAX=4 or -DTCL\_UTF\_MAX=6,
     but still want to use the 16-bit conversions independent on the TCL\_UTF\_MAX setting or Tcl\_UniChar type.

 * Enhance the Tcl\_UniCharToUtfDString() function such that the uniLength parameter is allowed to
   have the value -1.

























# Compatibility

This is fully upwards compatible in Tcl 8.x, except if Tcl is compiled with -DTCL\_UTF\_MAX=6 (not officially supported) or
-DTCL\_NO\_DEPRECATED. Starting with Tcl 9.0, the replacement functions should be used in stead.

# Reference Implementation






|

|
>
|
<
>
|
|

>
>
|
|
<
>




<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







32
33
34
35
36
37
38
39
40
41
42
43

44
45
46
47
48
49
50
51

52
53
54
55
56


57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 * Deprecate the following functions:

     Tcl\_WinUtfToTChar()

     Tcl\_WinTCharToUtf()

   If Tcl is compiled with either -DTCL\_UTF\_MAX=6 (which is not officially supported) or -DTCL\_NO\_DEPRECATED, those functions will
   no longer be available. In Tcl 9.0, those functions will be completely removed.

 * Enhance the Tcl\_UniCharToUtfDString() function such that the uniLength parameter is allowed to
   have the value -1. In that case, the UniChar string will be read up to the closing /u0000 character.


 * New replacement functions:

     Tcl\_UtfToUtf16DString(), replaces Tcl\_WinUtfToTChar()

     Tcl\_Utf16ToUtfDString(), replaces Tcl\_WinTCharToUtf()

     Those are the same as the already existing _UniChar_ variants (Tcl\_UniCharToUtfDString/Tcl\_UtfToUniCharDString), but they use an "unsigned short"
     pointer type in their signature stead of a "Tcl\_UniChar" pointer type, which is always 16-bits.

     Tcl\_Utf16ToUtfDString() accepts - just as Tcl\_UniCharToUtfDString() - the value -1 as length parameter.

     Those functions can be used if you want your extension to compile with -DTCL\_UTF\_MAX=3, -DTCL\_UTF\_MAX=4 or -DTCL\_UTF\_MAX=6,
     but still want to use the 16-bit conversions independent on the TCL\_UTF\_MAX setting or Tcl\_UniChar type.



     Those functions are available on all platforms, not only Windows.

# How to upgrade.

In your extension, replace the call:

     Tcl_WinUtfToTChar(....., bufPtr);
     
with the following two lines:

     Tcl_DStringInit(bufPtr);
     Tcl_UtfToUtf16DString(....., bufPtr);

And also, replace:

     Tcl_WinTCharToUtf(....., bufPtr);
     
with the following two lines:

     Tcl_DStringInit(bufPtr);
     Tcl_Utf16ToUtfDString(....., bufPtr);

If the Tcl\_WinTCharToUtf() call originally had a "length" parameter not equal to -1, divide it by 2 (or ... don't multiply it by 2 any more).


# Compatibility

This is fully upwards compatible in Tcl 8.x, except if Tcl is compiled with -DTCL\_UTF\_MAX=6 (not officially supported) or
-DTCL\_NO\_DEPRECATED. Starting with Tcl 9.0, the replacement functions should be used in stead.

# Reference Implementation