0000: 23 20 48 69 73 74 6f 72 79 20 6f 66 20 54 63 6c # History of Tcl
0010: 20 73 74 72 69 6e 67 20 76 61 6c 75 65 73 0a 0a string values..
0020: 2a 53 70 65 63 75 6c 61 74 69 76 65 20 61 6e 64 *Speculative and
0030: 20 6c 69 6b 65 6c 79 20 72 65 76 69 73 69 6f 6e likely revision
0040: 69 73 74 20 6c 6f 6f 6b 20 62 61 63 6b 20 61 74 ist look back at
0050: 20 54 63 6c 20 73 74 72 69 6e 67 73 2e 2a 0a 0a Tcl strings.*..
0060: 54 63 6c 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 Tcl programmers
0070: 61 72 65 20 66 61 6d 69 6c 69 61 72 20 77 69 74 are familiar wit
0080: 68 20 74 68 65 20 70 68 72 61 73 65 0a 5b 45 76 h the phrase.[Ev
0090: 65 72 79 20 76 61 6c 75 65 20 69 73 20 61 20 73 ery value is a s
00a0: 74 72 69 6e 67 5d 28 68 74 74 70 73 3a 2f 2f 77 tring](https://w
00b0: 69 6b 69 2e 74 63 6c 2d 6c 61 6e 67 2e 6f 72 67 iki.tcl-lang.org
00c0: 2f 70 61 67 65 2f 65 76 65 72 79 74 68 69 6e 67 /page/everything
00d0: 2b 69 73 2b 61 2b 73 74 72 69 6e 67 29 2e 0a 44 +is+a+string)..D
00e0: 69 73 63 75 73 73 69 6f 6e 73 20 6f 66 20 74 68 iscussions of th
00f0: 69 73 20 61 73 70 65 63 74 20 6f 66 20 54 63 6c is aspect of Tcl
0100: 20 61 72 65 20 66 6f 75 6e 64 20 69 6e 20 6d 61 are found in ma
0110: 6e 79 20 70 6c 61 63 65 73 2e 20 49 74 20 69 73 ny places. It is
0120: 20 68 61 72 64 65 72 20 74 6f 20 0a 66 69 6e 64 harder to .find
0130: 20 64 65 74 61 69 6c 65 64 20 64 69 73 63 75 73 detailed discus
0140: 73 69 6f 6e 73 20 6f 66 20 70 72 65 63 69 73 65 sions of precise
0150: 6c 79 20 77 68 61 74 20 69 73 20 22 61 20 73 74 ly what is "a st
0160: 72 69 6e 67 22 20 69 6e 20 54 63 6c 2c 20 61 6e ring" in Tcl, an
0170: 64 20 68 6f 77 0a 74 68 61 74 20 70 72 65 63 69 d how.that preci
0180: 73 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 68 61 se definition ha
0190: 73 20 73 68 69 66 74 65 64 20 6f 76 65 72 20 74 s shifted over t
01a0: 68 65 20 79 65 61 72 73 2e 20 54 68 69 73 20 64 he years. This d
01b0: 6f 63 75 6d 65 6e 74 20 69 73 20 6d 65 61 6e 74 ocument is meant
01c0: 0a 74 6f 20 74 61 63 6b 6c 65 20 74 68 61 74 20 .to tackle that
01d0: 74 61 73 6b 2c 20 62 61 73 65 64 20 6f 6e 20 61 task, based on a
01e0: 20 72 65 76 69 65 77 20 6f 66 20 74 68 65 20 63 review of the c
01f0: 68 61 6e 67 69 6e 67 20 69 6e 74 65 72 66 61 63 hanging interfac
0200: 65 73 20 61 6e 64 0a 69 6d 70 6c 65 6d 65 6e 74 es and.implement
0210: 61 74 69 6f 6e 20 69 6e 20 74 68 65 20 54 63 6c ation in the Tcl
0220: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 69 74 73 source code its
0230: 65 6c 66 2e 0a 0a 23 23 20 50 72 65 68 69 73 74 elf...## Prehist
0240: 6f 72 69 63 20 54 63 6c 20 28 37 2e 36 20 61 6e oric Tcl (7.6 an
0250: 64 20 65 61 72 6c 69 65 72 2c 20 70 72 65 2d 31 d earlier, pre-1
0260: 39 39 37 29 0a 0a 2a 2a 4e 55 4c 2a 2a 20 2a 74 997)..**NUL** *t
0270: 65 72 6d 69 6e 61 74 65 64 20 61 72 72 61 79 20 erminated array
0280: 6f 66 2a 20 2a 2a 63 68 61 72 2a 2a 20 2a 28 43 of* **char** *(C
0290: 20 73 74 72 69 6e 67 29 2a 0a 0a 54 68 65 20 69 string)*..The i
02a0: 6e 73 70 69 72 61 74 69 6f 6e 73 20 66 6f 72 20 nspirations for
02b0: 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 54 63 6c the original Tcl
02c0: 20 73 74 72 69 6e 67 20 76 61 6c 75 65 73 20 77 string values w
02d0: 65 72 65 20 63 6c 65 61 72 6c 79 20 74 68 65 0a ere clearly the.
02e0: 69 6e 2d 6d 65 6d 6f 72 79 20 72 65 70 72 65 73 in-memory repres
02f0: 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 43 20 73 entations of C s
0300: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 2c 20 tring literals,
0310: 61 6e 64 20 74 68 65 20 0a 61 72 67 75 6d 65 6e and the .argumen
0320: 74 73 20 75 73 65 64 20 62 79 20 43 20 70 72 6f ts used by C pro
0330: 67 72 61 6d 73 20 74 6f 20 72 65 63 65 69 76 65 grams to receive
0340: 20 74 68 65 69 72 20 63 6f 6d 6d 61 6e 64 20 6c their command l
0350: 69 6e 65 2e 0a 0a 3e 09 2a 2a 69 6e 74 2a 2a 20 ine...>.**int**
0360: 2a 2a 6d 61 69 6e 2a 2a 20 28 20 2a 2a 69 6e 74 **main** ( **int
0370: 2a 2a 20 2a 61 72 67 63 2a 2c 20 2a 2a 63 68 61 ** *argc*, **cha
0380: 72 2a 2a 20 2a 2a 5f 61 72 67 76 5f 29 0a 0a 45 r** **_argv_)..E
0390: 76 65 72 79 20 63 6f 6d 6d 61 6e 64 20 69 6e 20 very command in
03a0: 54 63 6c 20 37 20 69 73 20 69 6d 70 6c 65 6d 65 Tcl 7 is impleme
03b0: 6e 74 65 64 20 62 79 20 61 20 2a 2a 54 63 6c 5f nted by a **Tcl_
03c0: 43 6d 64 50 72 6f 63 2a 2a 20 77 69 74 68 20 73 CmdProc** with s
03d0: 69 67 6e 61 74 75 72 65 0a 0a 3e 09 2a 2a 69 6e ignature..>.**in
03e0: 74 2a 2a 20 2a 2a 54 63 6c 5f 43 6d 64 50 72 6f t** **Tcl_CmdPro
03f0: 63 2a 2a 20 28 20 2a 2a 43 6c 69 65 6e 74 44 61 c** ( **ClientDa
0400: 74 61 2a 2a 2c 20 5f 69 6e 74 65 72 70 5f 2c 20 ta**, _interp_,
0410: 2a 2a 69 6e 74 2a 2a 20 5f 61 72 67 63 5f 2c 20 **int** _argc_,
0420: 2a 2a 63 68 61 72 2a 2a 20 2a 5f 61 72 67 76 5f **char** *_argv_
0430: 5b 5d 29 0a 0a 45 61 63 68 20 61 72 67 75 6d 65 [])..Each argume
0440: 6e 74 20 76 61 6c 75 65 20 5f 61 72 67 76 5f 5b nt value _argv_[
0450: 5f 69 5f 5d 20 70 61 73 73 65 64 20 74 6f 20 61 _i_] passed to a
0460: 20 63 6f 6d 6d 61 6e 64 20 61 72 72 69 76 65 73 command arrives
0470: 20 69 6e 20 74 68 65 0a 66 6f 72 6d 20 20 6f 66 in the.form of
0480: 20 61 20 28 5f 5f 63 68 61 72 5f 5f 20 2a 29 2e a (__char__ *).
0490: 0a 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 70 .The caller is p
04a0: 72 65 73 75 6d 65 64 20 74 6f 20 70 61 73 73 20 resumed to pass
04b0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
04c0: 65 72 20 74 6f 20 61 20 73 75 69 74 61 62 6c 79 er to a suitably
04d0: 20 75 73 61 62 6c 65 0a 63 6f 6e 74 69 67 75 6f usable.contiguo
04e0: 75 73 20 63 68 75 6e 6b 20 6f 66 20 6d 65 6d 6f us chunk of memo
04f0: 72 79 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 ry, interpreted
0500: 61 73 20 61 20 43 20 61 72 72 61 79 20 6f 66 20 as a C array of
0510: 74 79 70 65 20 2a 2a 63 68 61 72 2a 2a 2e 20 54 type **char**. T
0520: 68 69 73 0a 69 6e 63 6c 75 64 65 73 20 61 20 64 his.includes a d
0530: 75 74 79 20 6f 66 20 74 68 65 20 63 61 6c 6c 65 uty of the calle
0540: 72 20 74 6f 20 6b 65 65 70 20 74 68 69 73 20 6d r to keep this m
0550: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 emory allocated
0560: 61 6e 64 20 75 6e 64 69 73 74 75 72 62 65 64 0a and undisturbed.
0570: 77 68 69 6c 65 20 74 68 65 20 63 6f 6d 6d 61 6e while the comman
0580: 64 20 70 72 6f 63 65 64 75 72 65 20 65 78 65 63 d procedure exec
0590: 75 74 65 73 2e 20 28 49 6e 20 74 68 65 20 64 61 utes. (In the da
05a0: 79 73 20 6f 66 20 54 63 6c 20 37 2c 20 74 68 69 ys of Tcl 7, thi
05b0: 73 20 77 61 73 0a 74 72 69 76 69 61 6c 6c 79 20 s was.trivially
05c0: 61 63 68 69 65 76 65 64 20 77 69 74 68 20 61 6e achieved with an
05d0: 20 61 73 73 75 6d 70 74 69 6f 6e 20 74 68 61 74 assumption that
05e0: 20 61 6c 6c 20 75 73 65 20 6f 66 20 74 68 65 20 all use of the
05f0: 54 63 6c 20 6c 69 62 72 61 72 79 20 77 61 73 0a Tcl library was.
0600: 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 2e single-threaded.
0610: 29 20 54 68 65 20 65 6c 65 6d 65 6e 74 73 20 6f ) The elements o
0620: 66 20 74 68 61 74 20 61 72 72 61 79 20 64 65 74 f that array det
0630: 65 72 6d 69 6e 65 20 74 68 65 20 73 74 72 69 6e ermine the strin
0640: 67 20 76 61 6c 75 65 2e 0a 45 61 63 68 20 65 6c g value..Each el
0650: 65 6d 65 6e 74 20 77 69 74 68 20 28 75 6e 73 69 ement with (unsi
0660: 67 6e 65 64 29 20 2a 2a 63 68 61 72 2a 2a 20 76 gned) **char** v
0670: 61 6c 75 65 20 62 65 74 77 65 65 6e 20 31 20 61 alue between 1 a
0680: 6e 64 20 32 35 35 20 72 65 70 72 65 73 65 6e 74 nd 255 represent
0690: 73 20 61 6e 0a 65 6c 65 6d 65 6e 74 20 6f 66 20 s an.element of
06a0: 74 68 65 20 73 74 72 69 6e 67 2c 20 73 74 6f 72 the string, stor
06b0: 65 64 20 61 74 20 74 68 65 20 63 6f 72 72 65 73 ed at the corres
06c0: 70 6f 6e 64 69 6e 67 20 69 6e 64 65 78 20 6f 66 ponding index of
06d0: 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 54 68 that string..Th
06e0: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 20 e first element
06f0: 77 69 74 68 20 76 61 6c 75 65 20 30 20 28 61 6b with value 0 (ak
0700: 61 20 2a 2a 4e 55 4c 2a 2a 29 20 69 73 20 6e 6f a **NUL**) is no
0710: 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 73 74 t part of the st
0720: 72 69 6e 67 20 76 61 6c 75 65 2c 0a 62 75 74 20 ring value,.but
0730: 6d 61 72 6b 73 20 69 74 73 20 65 6e 64 2e 0a 0a marks its end...
0740: 46 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d From this implem
0750: 65 6e 74 61 74 69 6f 6e 2c 20 77 65 20 73 65 65 entation, we see
0760: 20 74 68 61 74 20 61 20 54 63 6c 20 73 74 72 69 that a Tcl stri
0770: 6e 67 20 69 6e 20 72 65 6c 65 61 73 65 20 37 2e ng in release 7.
0780: 36 20 69 73 20 61 0a 73 65 71 75 65 6e 63 65 20 6 is a.sequence
0790: 6f 66 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 of zero or more
07a0: 5f 5f 63 68 61 72 5f 5f 20 76 61 6c 75 65 73 20 __char__ values
07b0: 66 72 6f 6d 20 74 68 65 20 72 61 6e 67 65 20 31 from the range 1
07c0: 2e 2e 32 35 35 2e 0a 49 6e 20 74 68 65 20 43 20 ..255..In the C
07d0: 74 79 70 65 20 73 79 73 74 65 6d 2c 20 65 61 63 type system, eac
07e0: 68 20 73 74 72 69 6e 67 20 65 6c 65 6d 65 6e 74 h string element
07f0: 20 69 73 20 61 20 5f 5f 63 68 61 72 5f 5f 2e 0a is a __char__..
0800: 49 74 20 69 73 20 61 6c 73 6f 20 75 73 65 66 75 It is also usefu
0810: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 65 61 l to think of ea
0820: 63 68 20 73 74 72 69 6e 67 0a 65 6c 65 6d 65 6e ch string.elemen
0830: 74 20 61 73 20 61 20 62 79 74 65 2e 20 54 68 65 t as a byte. The
0840: 20 74 79 70 65 20 6e 61 6d 65 20 2a 2a 63 68 61 type name **cha
0850: 72 2a 2a 20 73 75 67 67 65 73 74 73 20 22 63 68 r** suggests "ch
0860: 61 72 61 63 74 65 72 22 2c 20 61 6e 64 20 77 72 aracter", and wr
0870: 69 74 74 65 6e 0a 77 6f 72 6b 73 20 61 62 6f 75 itten.works abou
0880: 74 20 54 63 6c 20 66 72 6f 6d 20 74 68 61 74 20 t Tcl from that
0890: 74 69 6d 65 20 70 72 6f 62 61 62 6c 79 20 72 65 time probably re
08a0: 66 65 72 20 74 6f 20 61 20 54 63 6c 20 73 74 72 fer to a Tcl str
08b0: 69 6e 67 20 61 73 0a 61 20 22 73 65 71 75 65 6e ing as.a "sequen
08c0: 63 65 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 ce of characters
08d0: 22 2e 20 20 49 6e 20 6c 61 74 65 72 20 64 65 76 ". In later dev
08e0: 65 6c 6f 70 6d 65 6e 74 73 20 74 68 65 20 74 65 elopments the te
08f0: 72 6d 73 20 22 62 79 74 65 22 0a 61 6e 64 20 22 rms "byte".and "
0900: 63 68 61 72 61 63 74 65 72 22 20 68 61 76 65 20 character" have
0910: 64 69 76 65 72 67 65 64 20 69 6e 20 6d 65 61 6e diverged in mean
0920: 69 6e 67 2e 20 54 68 65 72 65 20 69 73 20 6e 6f ing. There is no
0930: 20 64 65 66 69 6e 65 64 20 6c 69 6d 69 74 20 6f defined limit o
0940: 6e 20 74 68 65 0a 6c 65 6e 67 74 68 20 6f 66 20 n the.length of
0950: 74 68 69 73 20 73 74 72 69 6e 67 20 72 65 70 72 this string repr
0960: 65 73 65 6e 74 61 74 69 6f 6e 3b 20 74 68 65 20 esentation; the
0970: 6f 6e 6c 79 20 6c 69 6d 69 74 20 69 73 20 61 76 only limit is av
0980: 61 69 6c 61 62 6c 65 20 6d 65 6d 6f 72 79 2e 0a ailable memory..
0990: 0a 54 68 65 72 65 20 69 73 20 61 20 6f 6e 65 2d .There is a one-
09a0: 74 6f 2d 6f 6e 65 20 63 6f 6e 6e 65 63 74 69 6f to-one connectio
09b0: 6e 20 62 65 74 77 65 65 6e 20 73 74 6f 72 65 64 n between stored
09c0: 20 6d 65 6d 6f 72 79 20 70 61 74 74 65 72 6e 73 memory patterns
09d0: 20 61 6e 64 20 74 68 65 0a 61 62 73 74 72 61 63 and the.abstrac
09e0: 74 20 6e 6f 74 69 6f 6e 20 6f 66 20 76 61 6c 69 t notion of vali
09f0: 64 20 54 63 6c 20 73 74 72 69 6e 67 73 2e 20 20 d Tcl strings.
0a00: 54 68 65 20 54 63 6c 20 73 74 72 69 6e 67 20 22 The Tcl string "
0a10: 63 61 74 22 20 69 73 20 61 6c 77 61 79 73 0a 72 cat" is always.r
0a20: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 epresented by a
0a30: 34 2d 62 79 74 65 20 63 68 75 6e 6b 20 6f 66 20 4-byte chunk of
0a40: 6d 65 6d 6f 72 79 20 73 74 6f 72 69 6e 67 0a 28 memory storing.(
0a50: 2a 2a 30 78 36 33 2a 2a 2c 20 2a 2a 30 78 36 31 **0x63**, **0x61
0a60: 2a 2a 2c 20 2a 2a 30 78 37 34 2a 2a 2c 20 2a 2a **, **0x74**, **
0a70: 30 78 30 30 2a 2a 29 2e 0a 41 6e 79 20 64 69 66 0x00**)..Any dif
0a80: 66 65 72 65 6e 74 20 62 79 74 65 73 20 69 6e 20 ferent bytes in
0a90: 6d 65 6d 6f 72 79 20 72 65 70 72 65 73 65 6e 74 memory represent
0aa0: 20 64 69 66 66 65 72 65 6e 74 20 73 74 72 69 6e different strin
0ab0: 67 73 2e 20 54 68 69 73 20 6d 65 61 6e 73 0a 62 gs. This means.b
0ac0: 79 74 65 20 63 6f 6d 70 61 72 69 73 6f 6e 73 20 yte comparisons
0ad0: 61 72 65 20 73 74 72 69 6e 67 20 63 6f 6d 70 61 are string compa
0ae0: 72 69 73 6f 6e 73 20 61 6e 64 20 62 79 74 65 20 risons and byte
0af0: 61 72 72 61 79 20 73 69 7a 65 20 69 73 20 73 74 array size is st
0b00: 72 69 6e 67 20 6c 65 6e 67 74 68 2e 0a 54 68 65 ring length..The
0b10: 20 62 79 74 65 20 76 61 6c 75 65 73 20 74 68 65 byte values the
0b20: 6d 73 65 6c 76 65 73 20 61 72 65 20 77 68 61 74 mselves are what
0b30: 20 54 63 6c 20 63 6f 6d 6d 61 6e 64 73 20 6f 70 Tcl commands op
0b40: 65 72 61 74 65 20 6f 6e 2e 20 46 72 6f 6d 20 65 erate on. From e
0b50: 61 72 6c 79 20 6f 6e 2c 0a 74 68 65 20 64 6f 63 arly on,.the doc
0b60: 75 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 63 umentation has c
0b70: 6c 61 69 6d 65 64 20 63 6f 6d 70 6c 65 74 65 20 laimed complete
0b80: 66 72 65 65 64 6f 6d 20 66 6f 72 20 65 61 63 68 freedom for each
0b90: 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 20 69 6e 74 command to int
0ba0: 65 72 70 72 65 74 0a 74 68 65 20 62 79 74 65 73 erpret.the bytes
0bb0: 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
0bc0: 20 74 6f 20 69 74 20 61 73 20 61 72 67 75 6d 65 to it as argume
0bd0: 6e 74 73 20 28 6f 72 20 22 77 6f 72 64 73 22 29 nts (or "words")
0be0: 3a 0a 0a 3e 09 54 68 65 20 66 69 72 73 74 20 77 :..>.The first w
0bf0: 6f 72 64 20 69 73 20 75 73 65 64 20 74 6f 20 6c ord is used to l
0c00: 6f 63 61 74 65 20 61 20 63 6f 6d 6d 61 6e 64 20 ocate a command
0c10: 70 72 6f 63 65 64 75 72 65 20 74 6f 20 63 61 72 procedure to car
0c20: 72 79 20 6f 75 74 0a 3e 09 74 68 65 20 63 6f 6d ry out.>.the com
0c30: 6d 61 6e 64 2c 20 74 68 65 6e 20 61 6c 6c 20 6f mand, then all o
0c40: 66 20 74 68 65 20 77 6f 72 64 73 20 6f 66 20 74 f the words of t
0c50: 68 65 20 63 6f 6d 6d 61 6e 64 20 61 72 65 20 70 he command are p
0c60: 61 73 73 65 64 20 74 6f 0a 3e 09 74 68 65 20 63 assed to.>.the c
0c70: 6f 6d 6d 61 6e 64 20 70 72 6f 63 65 64 75 72 65 ommand procedure
0c80: 2e 20 20 54 68 65 20 63 6f 6d 6d 61 6e 64 20 70 . The command p
0c90: 72 6f 63 65 64 75 72 65 20 20 69 73 20 20 66 72 rocedure is fr
0ca0: 65 65 20 74 6f 0a 3e 09 69 6e 74 65 72 70 72 65 ee to.>.interpre
0cb0: 74 20 65 61 63 68 20 6f 66 20 69 74 73 20 77 6f t each of its wo
0cc0: 72 64 73 20 69 6e 20 61 6e 79 20 77 61 79 20 69 rds in any way i
0cd0: 74 20 6c 69 6b 65 73 2c 20 73 75 63 68 20 61 73 t likes, such as
0ce0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 0a 3e 09 76 an integer,.>.v
0cf0: 61 72 69 61 62 6c 65 20 6e 61 6d 65 2c 20 6c 69 ariable name, li
0d00: 73 74 2c 20 6f 72 20 54 63 6c 20 73 63 72 69 70 st, or Tcl scrip
0d10: 74 2e 20 20 44 69 66 66 65 72 65 6e 74 20 63 6f t. Different co
0d20: 6d 6d 61 6e 64 73 20 69 6e 74 65 72 70 72 65 74 mmands interpret
0d30: 0a 3e 09 74 68 65 69 72 20 77 6f 72 64 73 20 64 .>.their words d
0d40: 69 66 66 65 72 65 6e 74 6c 79 2e 0a 0a 49 6e 20 ifferently...In
0d50: 70 72 61 63 74 69 63 65 20 74 68 6f 75 67 68 2c practice though,
0d60: 20 69 74 20 68 61 73 20 62 65 65 6e 20 65 78 70 it has been exp
0d70: 65 63 74 65 64 20 74 68 61 74 20 77 68 65 72 65 ected that where
0d80: 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
0d90: 6f 66 20 61 0a 73 74 72 69 6e 67 20 65 6c 65 6d of a.string elem
0da0: 65 6e 74 20 76 61 6c 75 65 20 61 73 20 61 20 6d ent value as a m
0db0: 65 6d 62 65 72 20 6f 66 20 61 20 63 68 61 72 73 ember of a chars
0dc0: 65 74 20 6d 61 74 74 65 72 73 2c 20 74 68 65 20 et matters, the
0dd0: 41 53 43 49 49 20 65 6e 63 6f 64 69 6e 67 0a 69 ASCII encoding.i
0de0: 73 20 70 72 65 73 75 6d 65 64 20 66 6f 72 20 74 s presumed for t
0df0: 68 65 20 62 79 74 65 20 76 61 6c 75 65 73 20 31 he byte values 1
0e00: 2e 2e 31 32 37 2e 20 54 68 69 73 20 69 73 20 69 ..127. This is i
0e10: 6e 20 61 67 72 65 65 6d 65 6e 74 20 77 69 74 68 n agreement with
0e20: 20 74 68 65 0a 72 65 70 72 65 73 65 6e 74 61 74 the.representat
0e30: 69 6f 6e 20 6f 66 20 43 20 73 74 72 69 6e 67 20 ion of C string
0e40: 6c 69 74 65 72 61 6c 73 20 69 6e 20 61 6c 6c 20 literals in all
0e50: 43 20 63 6f 6d 70 69 6c 65 72 73 2c 20 61 6e 64 C compilers, and
0e60: 20 69 74 20 61 6e 63 68 6f 72 73 20 74 68 65 0a it anchors the.
0e70: 63 68 61 72 61 63 74 65 72 20 64 65 66 69 6e 69 character defini
0e80: 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 tions that are i
0e90: 6d 70 6f 72 74 61 6e 74 20 74 6f 20 74 68 65 20 mportant to the
0ea0: 73 79 6e 74 61 78 20 6f 66 20 54 63 6c 20 69 74 syntax of Tcl it
0eb0: 73 65 6c 66 2e 20 46 6f 72 0a 69 6e 73 74 61 6e self. For.instan
0ec0: 63 65 2c 20 74 68 65 20 6e 65 77 6c 69 6e 65 20 ce, the newline
0ed0: 63 68 61 72 61 63 74 65 72 20 74 68 61 74 20 74 character that t
0ee0: 65 72 6d 69 6e 61 74 65 73 20 61 20 63 6f 6d 6d erminates a comm
0ef0: 61 6e 64 20 69 6e 20 61 20 73 63 72 69 70 74 20 and in a script
0f00: 69 73 0a 74 68 65 20 62 79 74 65 20 76 61 6c 75 is.the byte valu
0f10: 65 20 2a 2a 30 78 30 41 2a 2a 20 2e 20 4e 6f 20 e **0x0A** . No
0f20: 63 6f 6d 6d 61 6e 64 20 70 75 72 70 6f 72 74 69 command purporti
0f30: 6e 67 20 74 6f 20 61 63 63 65 70 74 20 61 6e 64 ng to accept and
0f40: 20 65 76 61 6c 75 61 74 65 0a 61 6e 20 61 72 67 evaluate.an arg
0f50: 75 6d 65 6e 74 20 61 73 20 61 20 54 63 6c 20 73 ument as a Tcl s
0f60: 63 72 69 70 74 20 77 6f 75 6c 64 20 62 65 20 66 cript would be f
0f70: 72 65 65 20 74 6f 20 63 68 6f 6f 73 65 20 73 6f ree to choose so
0f80: 6d 65 74 68 69 6e 67 20 65 6c 73 65 2e 20 20 54 mething else. T
0f90: 68 65 0a 68 61 6e 64 6c 69 6e 67 20 6f 66 20 62 he.handling of b
0fa0: 79 74 65 20 76 61 6c 75 65 73 20 31 32 38 2e 2e yte values 128..
0fb0: 32 35 35 20 73 68 6f 77 65 64 20 6d 6f 72 65 20 255 showed more
0fc0: 76 61 72 69 61 74 69 6f 6e 20 61 6d 6f 6e 67 20 variation among
0fd0: 63 6f 6d 6d 61 6e 64 73 20 74 68 61 74 0a 74 6f commands that.to
0fe0: 6f 6b 20 61 6e 79 20 70 61 72 74 69 63 75 6c 61 ok any particula
0ff0: 72 20 6e 6f 74 65 20 6f 66 20 74 68 65 6d 2e 20 r note of them.
1000: 20 54 63 6c 20 70 72 6f 76 69 64 65 64 20 62 75 Tcl provided bu
1010: 69 6c 74 2d 69 6e 20 63 6f 6d 6d 61 6e 64 73 0a ilt-in commands.
1020: 5f 5f 66 6f 72 6d 61 74 5f 5f 20 61 6e 64 20 5f __format__ and _
1030: 5f 73 63 61 6e 5f 5f 2c 20 61 73 20 77 65 6c 6c _scan__, as well
1040: 20 61 73 20 74 68 65 20 62 61 63 6b 73 6c 61 73 as the backslas
1050: 68 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 6d 73 h encoding forms
1060: 20 6f 66 0a 5f 5f 5c 5c 78 48 48 5f 5f 20 61 6e of.__\\xHH__ an
1070: 64 20 5f 5f 5c 5c 6f 6f 6f 5f 5f 20 74 6f 20 6d d __\\ooo__ to m
1080: 61 6e 61 67 65 20 74 68 65 20 74 72 61 6e 73 66 anage the transf
1090: 6f 72 6d 61 74 69 6f 6e 20 62 65 74 77 65 65 6e ormation between
10a0: 20 73 74 72 69 6e 67 20 65 6c 65 6d 65 6e 74 0a string element.
10b0: 76 61 6c 75 65 73 20 61 6e 64 20 74 68 65 20 63 values and the c
10c0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6e 75 6d orresponding num
10d0: 65 72 69 63 20 76 61 6c 75 65 73 2e 0a 0a 45 61 eric values...Ea
10e0: 63 68 20 54 63 6c 20 63 6f 6d 6d 61 6e 64 20 61 ch Tcl command a
10f0: 6c 73 6f 20 6c 65 61 76 65 73 20 61 20 72 65 73 lso leaves a res
1100: 75 6c 74 20 76 61 6c 75 65 20 69 6e 20 74 68 65 ult value in the
1110: 20 69 6e 74 65 72 70 72 65 74 65 72 20 6f 66 20 interpreter of
1120: 65 76 61 6c 75 61 74 69 6f 6e 2c 0a 77 68 65 74 evaluation,.whet
1130: 68 65 72 20 74 68 61 74 20 69 73 20 73 6f 6d 65 her that is some
1140: 20 72 65 73 75 6c 74 20 64 65 66 69 6e 65 64 20 result defined
1150: 62 79 20 74 68 65 20 70 72 6f 70 65 72 20 66 75 by the proper fu
1160: 6e 63 74 69 6f 6e 69 6e 67 20 6f 66 20 74 68 65 nctioning of the
1170: 0a 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 61 20 72 .command, or a r
1180: 65 61 64 61 62 6c 65 20 6d 65 73 73 61 67 65 20 eadable message
1190: 64 65 73 63 72 69 62 69 6e 67 20 61 6e 20 65 72 describing an er
11a0: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 2e 20 49 ror condition. I
11b0: 6e 20 54 63 6c 20 37 2c 0a 61 20 63 61 6c 6c 65 n Tcl 7,.a calle
11c0: 72 20 6f 66 20 2a 2a 54 63 6c 5f 45 76 61 6c 2a r of **Tcl_Eval*
11d0: 2a 20 68 61 73 20 6f 6e 6c 79 20 6f 6e 65 20 6d * has only one m
11e0: 65 63 68 61 6e 69 73 6d 20 74 6f 20 72 65 74 72 echanism to retr
11f0: 69 65 76 65 20 74 68 61 74 20 72 65 73 75 6c 74 ieve that result
1200: 0a 76 61 6c 75 65 20 61 66 74 65 72 20 65 76 61 .value after eva
1210: 6c 75 61 74 69 6e 67 20 61 20 63 6f 6d 6d 61 6e luating a comman
1220: 64 3a 20 72 65 61 64 20 61 20 28 5f 5f 63 68 61 d: read a (__cha
1230: 72 5f 5f 20 2a 29 20 64 69 72 65 63 74 6c 79 20 r__ *) directly
1240: 66 72 6f 6d 20 0a 74 68 65 20 5f 72 65 73 75 6c from .the _resul
1250: 74 5f 20 66 69 65 6c 64 20 6f 66 20 74 68 65 20 t_ field of the
1260: 73 61 6d 65 20 2a 2a 54 63 6c 5f 49 6e 74 65 72 same **Tcl_Inter
1270: 70 2a 2a 20 73 74 72 75 63 74 20 70 61 73 73 65 p** struct passe
1280: 64 20 74 6f 20 2a 2a 54 63 6c 5f 45 76 61 6c 2a d to **Tcl_Eval*
1290: 2a 2e 0a 54 68 65 20 70 6f 69 6e 74 65 72 20 66 *..The pointer f
12a0: 6f 75 6e 64 20 74 68 65 72 65 20 70 6f 69 6e 74 ound there point
12b0: 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 6b 69 s to the same ki
12c0: 6e 64 20 6f 66 20 0a 2a 2a 4e 55 4c 2a 2a 2d 74 nd of .**NUL**-t
12d0: 65 72 6d 69 6e 61 74 65 64 20 61 72 72 61 79 20 erminated array
12e0: 6f 66 20 5f 5f 63 68 61 72 5f 5f 20 75 73 65 64 of __char__ used
12f0: 20 74 6f 20 70 61 73 73 20 69 6e 20 74 68 65 20 to pass in the
1300: 61 72 67 75 6d 65 6e 74 20 77 6f 72 64 73 2e 0a argument words..
1310: 54 68 65 20 73 65 74 20 6f 66 20 70 6f 73 73 69 The set of possi
1320: 62 6c 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ble return value
1330: 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 61 6e 64 s from a command
1340: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
1350: 74 68 65 20 73 65 74 20 6f 66 0a 70 6f 73 73 69 the set of.possi
1360: 62 6c 65 20 61 72 67 75 6d 65 6e 74 73 20 28 61 ble arguments (a
1370: 6e 64 20 73 65 74 20 6f 66 20 70 6f 73 73 69 62 nd set of possib
1380: 6c 65 20 76 61 6c 75 65 73 20 73 74 6f 72 65 64 le values stored
1390: 20 69 6e 20 61 20 76 61 72 69 61 62 6c 65 29 2c in a variable),
13a0: 0a 61 20 73 65 71 75 65 6e 63 65 20 6f 66 20 7a .a sequence of z
13b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5f 5f 63 68 ero or more __ch
13c0: 61 72 5f 5f 20 76 61 6c 75 65 73 20 66 72 6f 6d ar__ values from
13d0: 20 74 68 65 20 72 61 6e 67 65 20 31 2e 2e 32 35 the range 1..25
13e0: 35 2e 0a 0a 49 74 20 6d 75 73 74 20 62 65 20 61 5...It must be a
13f0: 72 72 61 6e 67 65 64 20 74 68 61 74 20 74 68 65 rranged that the
1400: 20 70 6f 69 6e 74 65 72 20 69 6e 20 2a 69 6e 74 pointer in *int
1410: 65 72 70 2a 2d 3e 2a 72 65 73 75 6c 74 2a 20 70 erp*->*result* p
1420: 6f 69 6e 74 73 20 74 6f 0a 76 61 6c 69 64 20 6d oints to.valid m
1430: 65 6d 6f 72 79 20 72 65 61 64 61 62 6c 65 20 62 emory readable b
1440: 79 20 74 68 65 20 63 61 6c 6c 65 72 20 65 76 65 y the caller eve
1450: 6e 20 61 66 74 65 72 20 74 68 65 20 2a 2a 54 63 n after the **Tc
1460: 6c 5f 43 6d 64 50 72 6f 63 2a 2a 20 69 73 0a 66 l_CmdProc** is.f
1470: 75 6c 6c 79 20 72 65 74 75 72 6e 65 64 2e 20 54 ully returned. T
1480: 68 65 20 72 6f 75 74 69 6e 65 20 2a 2a 54 63 6c he routine **Tcl
1490: 5f 53 65 74 52 65 73 75 6c 74 2a 2a 20 6f 66 66 _SetResult** off
14a0: 65 72 73 20 73 65 76 65 72 61 6c 20 6f 70 74 69 ers several opti
14b0: 6f 6e 73 2e 0a 49 66 20 61 20 63 6f 6d 6d 61 6e ons..If a comman
14c0: 64 20 70 72 6f 63 65 64 75 72 65 20 61 6c 72 65 d procedure alre
14d0: 61 64 79 20 68 61 73 20 74 68 65 20 72 65 73 75 ady has the resu
14e0: 6c 74 20 76 61 6c 75 65 20 61 73 0a 61 20 28 5f lt value as.a (_
14f0: 5f 63 68 61 72 5f 5f 20 2a 29 20 5f 72 65 73 75 _char__ *) _resu
1500: 6c 74 5f 2c 20 69 74 20 77 69 6c 6c 20 61 6c 77 lt_, it will alw
1510: 61 79 73 20 77 6f 72 6b 20 74 6f 20 63 61 6c 6c ays work to call
1520: 0a 0a 3e 09 2a 2a 54 63 6c 5f 53 65 74 52 65 73 ..>.**Tcl_SetRes
1530: 75 6c 74 2a 2a 20 28 5f 69 6e 74 65 72 70 5f 2c ult** (_interp_,
1540: 20 5f 72 65 73 75 6c 74 5f 2c 20 2a 2a 54 43 4c _result_, **TCL
1550: 5f 56 4f 4c 41 54 49 4c 45 2a 2a 29 3b 0a 0a 54 _VOLATILE**);..T
1560: 68 65 20 61 72 67 75 6d 65 6e 74 20 2a 2a 54 43 he argument **TC
1570: 4c 5f 56 4f 4c 41 54 49 4c 45 2a 2a 20 69 6e 73 L_VOLATILE** ins
1580: 74 72 75 63 74 73 20 74 68 65 20 54 63 6c 20 6c tructs the Tcl l
1590: 69 62 72 61 72 79 20 74 6f 20 61 6c 6c 6f 63 61 ibrary to alloca
15a0: 74 65 0a 61 20 6c 61 72 67 65 20 65 6e 6f 75 67 te.a large enoug
15b0: 68 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 h block of memor
15c0: 79 20 74 6f 20 63 6f 70 79 20 5f 72 65 73 75 6c y to copy _resul
15d0: 74 5f 20 69 6e 74 6f 2c 20 6d 61 6b 65 73 20 74 t_ into, makes t
15e0: 68 61 74 20 63 6f 70 79 2c 0a 61 6e 64 20 74 68 hat copy,.and th
15f0: 65 6e 20 73 74 6f 72 65 73 20 61 20 70 6f 69 6e en stores a poin
1600: 74 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 ter to that copy
1610: 20 69 6e 20 5f 69 6e 74 65 72 70 5f 2d 3e 5f 72 in _interp_->_r
1620: 65 73 75 6c 74 5f 2e 20 57 68 65 6e 20 74 68 65 esult_. When the
1630: 0a 73 74 72 69 6e 67 20 74 6f 20 62 65 20 63 6f .string to be co
1640: 70 69 65 64 20 68 61 73 20 6c 65 6e 67 74 68 20 pied has length
1650: 6e 6f 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 no greater than
1660: 5f 5f 54 43 4c 5c 5f 52 45 53 55 4c 54 5c 5f 53 __TCL\_RESULT\_S
1670: 49 5a 45 5f 5f 2c 0a 74 68 69 73 20 22 61 6c 6c IZE__,.this "all
1680: 6f 63 61 74 69 6f 6e 22 20 74 61 6b 65 73 20 74 ocation" takes t
1690: 68 65 20 66 6f 72 6d 20 6f 66 20 75 73 69 6e 67 he form of using
16a0: 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 5f 69 6e an internal _in
16b0: 74 65 72 70 5f 20 66 69 65 6c 64 20 6f 66 0a 73 terp_ field of.s
16c0: 74 61 74 69 63 20 62 75 66 66 65 72 20 73 70 61 tatic buffer spa
16d0: 63 65 2c 20 61 76 6f 69 64 69 6e 67 20 64 79 6e ce, avoiding dyn
16e0: 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f amic memory allo
16f0: 63 61 74 69 6f 6e 20 66 6f 72 20 73 68 6f 72 74 cation for short
1700: 2d 65 6e 6f 75 67 68 0a 72 65 73 75 6c 74 73 2e -enough.results.
1710: 20 20 41 20 72 65 63 6f 72 64 20 69 73 20 6b 65 A record is ke
1720: 70 74 20 69 6e 20 6f 74 68 65 72 20 66 69 65 6c pt in other fiel
1730: 64 73 20 6f 66 20 5f 69 6e 74 65 72 70 5f 20 72 ds of _interp_ r
1740: 65 63 6f 72 64 69 6e 67 0a 74 68 61 74 20 74 68 ecording.that th
1750: 69 73 20 6d 65 6d 6f 72 79 20 6d 75 73 74 20 62 is memory must b
1760: 65 20 66 72 65 65 64 20 77 68 65 6e 65 76 65 72 e freed whenever
1770: 20 74 68 65 20 72 65 73 75 6c 74 20 6d 61 63 68 the result mach
1780: 69 6e 65 72 79 20 6d 75 73 74 20 62 65 0a 72 65 inery must be.re
1790: 2d 69 6e 69 74 69 61 6c 69 7a 65 64 20 66 6f 72 -initialized for
17a0: 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 the use of the
17b0: 6e 65 78 74 20 63 6f 6d 6d 61 6e 64 20 70 72 6f next command pro
17c0: 63 65 64 75 72 65 2c 0a 61 20 74 61 73 6b 20 70 cedure,.a task p
17d0: 65 72 66 6f 72 6d 65 64 20 62 79 20 2a 2a 54 63 erformed by **Tc
17e0: 6c 5f 52 65 73 65 74 52 65 73 75 6c 74 2a 2a 2e l_ResetResult**.
17f0: 20 20 54 68 69 73 20 67 65 6e 65 72 61 6c 20 73 This general s
1800: 6f 6c 75 74 69 6f 6e 20 74 6f 0a 70 61 73 73 69 olution to.passi
1810: 6e 67 20 62 61 63 6b 20 74 68 65 20 72 65 73 75 ng back the resu
1820: 6c 74 20 76 61 6c 75 65 20 75 73 69 6e 67 20 2a lt value using *
1830: 2a 54 43 4c 5f 56 4f 4c 41 54 49 4c 45 2a 2a 20 *TCL_VOLATILE**
1840: 61 6c 77 61 79 73 20 69 6d 70 6f 73 65 73 20 74 always imposes t
1850: 68 65 0a 63 6f 73 74 20 6f 66 20 63 6f 70 79 69 he.cost of copyi
1860: 6e 67 20 69 74 2e 20 20 49 6e 20 73 6f 6d 65 20 ng it. In some
1870: 73 69 74 75 61 74 69 6f 6e 73 20 74 68 65 72 65 situations there
1880: 20 61 72 65 20 6f 74 68 65 72 20 6f 70 74 69 6f are other optio
1890: 6e 73 2e 20 0a 0a 57 68 65 6e 20 74 68 65 20 72 ns. ..When the r
18a0: 65 73 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 61 esult value of a
18b0: 20 63 6f 6d 6d 61 6e 64 20 6f 72 69 67 69 6e 61 command origina
18c0: 74 65 73 20 69 6e 20 61 20 73 74 61 74 69 63 20 tes in a static
18d0: 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 0a 69 string literal.i
18e0: 6e 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 n the source cod
18f0: 65 20 6f 66 20 74 68 65 20 63 6f 6d 6d 61 6e 64 e of the command
1900: 20 70 72 6f 63 65 64 75 72 65 2c 20 74 68 65 72 procedure, ther
1910: 65 20 69 73 20 6e 6f 20 6e 65 65 64 20 74 6f 20 e is no need to
1920: 77 6f 72 6b 0a 77 69 74 68 20 6d 65 6d 6f 72 79 work.with memory
1930: 20 6d 61 6e 61 67 65 6d 65 6e 74 20 61 6e 64 20 management and
1940: 63 6f 70 69 65 73 2e 20 41 20 70 6f 69 6e 74 65 copies. A pointe
1950: 72 20 74 6f 20 74 68 65 20 6c 69 74 65 72 61 6c r to the literal
1960: 20 69 6e 20 73 74 61 74 69 63 0a 73 74 6f 72 61 in static.stora
1970: 67 65 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 ge will be valid
1980: 20 66 6f 72 20 74 68 65 20 63 61 6c 6c 65 72 2e for the caller.
1990: 20 54 68 65 20 63 61 6c 6c 0a 0a 3e 09 2a 2a 54 The call..>.**T
19a0: 63 6c 5f 53 65 74 52 65 73 75 6c 74 2a 2a 20 28 cl_SetResult** (
19b0: 5f 69 6e 74 65 72 70 5f 2c 20 2a 2a 22 6c 69 74 _interp_, **"lit
19c0: 65 72 61 6c 22 2a 2a 2c 20 2a 2a 54 43 4c 5f 53 eral"**, **TCL_S
19d0: 54 41 54 49 43 2a 2a 29 3b 0a 0a 69 73 20 61 70 TATIC**);..is ap
19e0: 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 propriate for th
19f0: 69 73 20 73 69 74 75 61 74 69 6f 6e 2e 20 54 68 is situation. Th
1a00: 65 20 61 72 67 75 6d 65 6e 74 20 2a 2a 54 43 4c e argument **TCL
1a10: 5f 53 54 41 54 49 43 2a 2a 20 69 6e 73 74 72 75 _STATIC** instru
1a20: 63 74 73 0a 74 68 65 20 54 63 6c 20 6c 69 62 72 cts.the Tcl libr
1a30: 61 72 79 20 74 6f 20 64 69 72 65 63 74 6c 79 20 ary to directly
1a40: 77 72 69 74 65 20 74 68 65 20 70 6f 69 6e 74 65 write the pointe
1a50: 72 20 74 6f 20 74 68 65 20 6c 69 74 65 72 61 6c r to the literal
1a60: 20 69 6e 74 6f 0a 5f 69 6e 74 65 72 70 5f 2d 3e into._interp_->
1a70: 5f 72 65 73 75 6c 74 5f 2e 20 49 74 20 69 73 20 _result_. It is
1a80: 61 20 77 65 6c 63 6f 6d 65 20 65 66 66 69 63 69 a welcome effici
1a90: 65 6e 63 79 20 74 6f 20 61 76 6f 69 64 20 63 6f ency to avoid co
1aa0: 70 69 65 73 20 77 68 65 6e 0a 70 6f 73 73 69 62 pies when.possib
1ab0: 6c 65 2e 0a 0a 41 20 74 68 69 72 64 20 6f 70 74 le...A third opt
1ac0: 69 6f 6e 20 69 73 20 77 68 65 6e 20 74 68 65 20 ion is when the
1ad0: 63 6f 6d 6d 61 6e 64 20 70 72 6f 63 65 64 75 72 command procedur
1ae0: 65 20 68 61 73 20 75 73 65 64 20 2a 2a 63 6b 61 e has used **cka
1af0: 6c 6c 6f 63 2a 2a 0a 74 6f 20 61 6c 6c 6f 63 61 lloc**.to alloca
1b00: 74 65 20 74 68 65 20 73 74 6f 72 61 67 65 20 66 te the storage f
1b10: 6f 72 20 5f 72 65 73 75 6c 74 5f 20 61 6e 64 20 or _result_ and
1b20: 74 68 65 6e 20 66 69 6c 6c 65 64 20 69 74 20 77 then filled it w
1b30: 69 74 68 20 74 68 65 20 70 72 6f 70 65 72 0a 62 ith the proper.b
1b40: 79 74 65 73 20 6f 66 20 74 68 65 20 72 65 73 75 ytes of the resu
1b50: 6c 74 20 76 61 6c 75 65 2e 20 20 54 68 65 6e 20 lt value. Then
1b60: 74 68 65 20 63 61 6c 6c 0a 0a 3e 09 2a 2a 54 63 the call..>.**Tc
1b70: 6c 5f 53 65 74 52 65 73 75 6c 74 2a 2a 20 28 5f l_SetResult** (_
1b80: 69 6e 74 65 72 70 5f 2c 20 5f 72 65 73 75 6c 74 interp_, _result
1b90: 5f 2c 20 2a 2a 54 43 4c 5f 44 59 4e 41 4d 49 43 _, **TCL_DYNAMIC
1ba0: 2a 2a 29 3b 0a 0a 69 6e 73 74 72 75 63 74 73 20 **);..instructs
1bb0: 74 68 65 20 54 63 6c 20 6c 69 62 72 61 72 79 20 the Tcl library
1bc0: 6e 6f 74 20 74 6f 20 6d 61 6b 65 20 61 6e 6f 74 not to make anot
1bd0: 68 65 72 20 63 6f 70 79 2c 20 62 75 74 20 74 6f her copy, but to
1be0: 20 74 61 6b 65 0a 6f 77 6e 65 72 73 68 69 70 20 take.ownership
1bf0: 6f 66 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 of the allocated
1c00: 20 73 74 6f 72 61 67 65 20 61 6e 64 20 74 68 65 storage and the
1c10: 20 64 75 74 79 20 74 6f 20 63 61 6c 6c 20 2a 2a duty to call **
1c20: 63 6b 66 72 65 65 2a 2a 0a 61 74 20 74 68 65 20 ckfree**.at the
1c30: 61 70 70 72 6f 70 72 69 61 74 65 20 74 69 6d 65 appropriate time
1c40: 2e 20 20 49 74 20 69 73 20 61 6c 73 6f 20 73 75 . It is also su
1c50: 70 70 6f 72 74 65 64 20 66 6f 72 20 74 68 65 20 pported for the
1c60: 63 6f 6d 6d 61 6e 64 20 70 72 6f 63 65 64 75 72 command procedur
1c70: 65 0a 74 6f 20 75 73 65 20 61 20 63 75 73 74 6f e.to use a custo
1c80: 6d 20 61 6c 6c 6f 63 61 74 6f 72 20 61 6e 64 20 m allocator and
1c90: 70 61 73 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 pass a function
1ca0: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 pointer for the
1cb0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 63 75 corresponding.cu
1cc0: 73 74 6f 6d 20 64 65 61 6c 6c 6f 63 61 74 6f 72 stom deallocator
1cd0: 20 72 6f 75 74 69 6e 65 2e 0a 0a 42 65 73 69 64 routine...Besid
1ce0: 65 73 20 2a 2a 54 63 6c 5f 53 65 74 52 65 73 75 es **Tcl_SetResu
1cf0: 6c 74 2a 2a 2c 20 61 20 63 6f 6d 6d 61 6e 64 20 lt**, a command
1d00: 70 72 6f 63 65 64 75 72 65 20 6d 69 67 68 74 20 procedure might
1d10: 61 6c 73 6f 20 62 75 69 6c 64 20 75 70 20 74 68 also build up th
1d20: 65 0a 72 65 73 75 6c 74 20 69 6e 20 70 6c 61 63 e.result in plac
1d30: 65 20 69 6e 73 69 64 65 20 74 68 65 20 69 6e 74 e inside the int
1d40: 65 72 70 20 72 65 73 75 6c 74 20 6d 61 63 68 69 erp result machi
1d50: 6e 65 72 79 20 62 79 20 75 73 65 20 6f 66 20 74 nery by use of t
1d60: 68 65 0a 72 6f 75 74 69 6e 65 73 20 2a 2a 54 63 he.routines **Tc
1d70: 6c 5f 41 70 70 65 6e 64 52 65 73 75 6c 74 2a 2a l_AppendResult**
1d80: 20 6f 72 20 2a 2a 54 63 6c 5f 41 70 70 65 6e 64 or **Tcl_Append
1d90: 45 6c 65 6d 65 6e 74 2a 2a 2c 20 77 68 69 63 68 Element**, which
1da0: 20 70 6c 61 63 65 73 20 6d 6f 72 65 0a 6f 66 20 places more.of
1db0: 74 68 65 20 68 6f 75 73 65 6b 65 65 70 69 6e 67 the housekeeping
1dc0: 20 62 75 72 64 65 6e 73 20 69 6e 20 74 68 65 20 burdens in the
1dd0: 54 63 6c 20 6c 69 62 72 61 72 79 2e 20 59 6f 75 Tcl library. You
1de0: 20 6d 61 79 20 61 6c 73 6f 20 73 65 65 20 65 78 may also see ex
1df0: 61 6d 70 6c 65 73 0a 6c 69 6b 65 0a 0a 3e 09 2a amples.like..>.*
1e00: 2a 73 70 72 69 6e 74 66 2a 2a 20 28 5f 69 6e 74 *sprintf** (_int
1e10: 65 72 70 5f 2d 3e 5f 72 65 73 75 6c 74 5f 2c 20 erp_->_result_,
1e20: 22 25 64 22 2c 20 5f 6e 5f 29 3b 0a 0a 77 68 65 "%d", _n_);..whe
1e30: 72 65 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 70 re the command p
1e40: 72 6f 63 65 64 75 72 65 20 63 61 6e 20 62 65 20 rocedure can be
1e50: 63 6f 6e 66 69 64 65 6e 74 20 61 62 6f 75 74 20 confident about
1e60: 6e 6f 74 20 6f 76 65 72 66 6c 6f 77 69 6e 67 0a not overflowing.
1e70: 74 68 65 20 2a 2a 54 43 4c 5c 5f 52 45 53 55 4c the **TCL\_RESUL
1e80: 54 5c 5f 53 49 5a 45 2a 2a 20 62 79 74 65 73 20 T\_SIZE** bytes
1e90: 6f 66 20 73 74 61 74 69 63 20 62 75 66 66 65 72 of static buffer
1ea0: 20 73 70 61 63 65 2e 0a 0a 57 68 65 6e 20 74 68 space...When th
1eb0: 65 20 63 61 6c 6c 65 72 20 72 65 61 64 73 20 74 e caller reads t
1ec0: 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 5f he result from _
1ed0: 69 6e 74 65 72 70 5f 2d 3e 5f 72 65 73 75 6c 74 interp_->_result
1ee0: 5f 2c 20 69 74 20 69 73 20 67 69 76 65 6e 20 6e _, it is given n
1ef0: 6f 0a 73 75 70 70 6f 72 74 65 64 20 69 6e 64 69 o.supported indi
1f00: 63 61 74 69 6f 6e 20 77 68 69 63 68 20 73 74 6f cation which sto
1f10: 72 61 67 65 20 70 72 6f 74 6f 63 6f 6c 20 69 73 rage protocol is
1f20: 20 69 6e 20 75 73 65 2c 20 61 6e 64 20 6e 6f 20 in use, and no
1f30: 73 75 70 70 6f 72 74 65 64 0a 6d 65 63 68 61 6e supported.mechan
1f40: 69 73 6d 20 74 6f 20 63 6c 61 69 6d 20 6f 77 6e ism to claim own
1f50: 65 72 73 68 69 70 2e 20 54 68 69 73 20 6d 65 61 ership. This mea
1f60: 6e 73 20 69 66 20 74 68 65 20 63 61 6c 6c 65 72 ns if the caller
1f70: 20 68 61 73 20 61 6e 79 20 6e 65 65 64 20 74 6f has any need to
1f80: 20 6b 65 65 70 0a 74 68 65 20 72 65 73 75 6c 74 keep.the result
1f90: 20 76 61 6c 75 65 20 66 6f 72 20 6c 61 74 65 72 value for later
1fa0: 20 75 73 65 2c 20 69 74 20 77 69 6c 6c 20 6e 65 use, it will ne
1fb0: 65 64 20 74 6f 20 6d 61 6b 65 20 61 6e 6f 74 68 ed to make anoth
1fc0: 65 72 20 63 6f 70 79 20 61 6e 64 20 6d 61 6b 65 er copy and make
1fd0: 0a 70 72 6f 76 69 73 69 6f 6e 73 20 66 6f 72 20 .provisions for
1fe0: 74 68 65 20 73 74 6f 72 61 67 65 20 6f 66 20 74 the storage of t
1ff0: 68 61 74 20 63 6f 70 79 2e 20 4f 66 74 65 6e 20 hat copy. Often
2000: 74 68 69 73 20 74 61 6b 65 73 20 74 68 65 20 66 this takes the f
2010: 6f 72 6d 20 6f 66 0a 63 61 6c 6c 69 6e 67 20 2a orm of.calling *
2020: 2a 54 63 6c 5f 53 65 74 56 61 72 2a 2a 20 74 6f *Tcl_SetVar** to
2030: 20 73 74 6f 72 65 20 74 68 65 20 76 61 6c 75 65 store the value
2040: 20 69 6e 20 61 20 54 63 6c 20 76 61 72 69 61 62 in a Tcl variab
2050: 6c 65 20 28 77 68 69 63 68 0a 70 65 72 66 6f 72 le (which.perfor
2060: 6d 73 20 74 68 65 20 68 6f 75 73 65 6b 65 65 70 ms the housekeep
2070: 69 6e 67 20 6f 66 20 6d 61 6b 69 6e 67 20 74 68 ing of making th
2080: 65 20 63 6f 70 79 20 6f 66 20 69 74 73 20 5f 6e e copy of its _n
2090: 65 77 56 61 6c 75 65 5f 20 61 72 67 75 6d 65 6e ewValue_ argumen
20a0: 74 29 2e 0a 0a 54 68 69 73 20 73 79 73 74 65 6d t)...This system
20b0: 20 6f 66 20 76 61 6c 75 65 73 20 68 61 73 20 73 of values has s
20c0: 65 76 65 72 61 6c 20 6d 65 72 69 74 73 2e 20 49 everal merits. I
20d0: 74 20 69 73 20 66 61 6d 69 6c 69 61 72 20 74 6f t is familiar to
20e0: 20 74 68 65 20 69 6e 74 65 6e 64 65 64 0a 61 75 the intended.au
20f0: 64 69 65 6e 63 65 20 6f 66 20 43 20 70 72 6f 67 dience of C prog
2100: 72 61 6d 6d 65 72 73 2e 20 54 68 65 20 72 65 70 rammers. The rep
2110: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 65 resentation of e
2120: 61 63 68 20 73 74 72 69 6e 67 20 65 6c 65 6d 65 ach string eleme
2130: 6e 74 20 0a 62 79 20 61 20 73 69 6e 67 6c 65 20 nt .by a single
2140: 62 79 74 65 20 69 73 20 73 69 6d 70 6c 65 20 61 byte is simple a
2150: 6e 64 20 64 69 72 65 63 74 20 61 6e 64 20 6f 6e nd direct and on
2160: 65 2d 74 6f 2d 6f 6e 65 2e 20 54 68 65 20 72 65 e-to-one. The re
2170: 73 75 6c 74 20 69 73 0a 61 20 66 69 78 65 64 2d sult is.a fixed-
2180: 6c 65 6e 67 74 68 20 65 6e 63 6f 64 69 6e 67 20 length encoding
2190: 77 68 69 63 68 20 6d 61 6b 65 73 20 72 61 6e 64 which makes rand
21a0: 6f 6d 20 61 63 63 65 73 73 20 69 6e 64 65 78 69 om access indexi
21b0: 6e 67 20 73 69 6d 70 6c 65 20 61 6e 64 0a 65 66 ng simple and.ef
21c0: 66 69 63 69 65 6e 74 2e 20 20 54 68 65 20 70 72 ficient. The pr
21d0: 6f 63 65 73 73 69 6e 67 20 6f 66 20 73 74 72 69 ocessing of stri
21e0: 6e 67 20 76 61 6c 75 65 73 20 74 61 6b 65 73 20 ng values takes
21f0: 74 68 65 20 66 6f 72 6d 20 6f 66 20 69 74 65 72 the form of iter
2200: 61 74 69 6e 67 0a 61 20 70 6f 69 6e 74 65 72 20 ating.a pointer
2210: 74 68 72 6f 75 67 68 20 61 6e 20 61 72 72 61 79 through an array
2220: 2c 20 61 20 66 61 6d 69 6c 69 61 72 20 74 65 63 , a familiar tec
2230: 68 6e 69 71 75 65 20 74 68 61 74 20 63 6f 6d 70 hnique that comp
2240: 69 6c 65 72 73 20 61 6e 64 20 68 61 72 64 77 61 ilers and hardwa
2250: 72 65 0a 68 61 76 65 20 73 74 72 6f 6e 67 20 68 re.have strong h
2260: 69 73 74 6f 72 79 20 6f 66 20 6d 61 6b 69 6e 67 istory of making
2270: 20 65 66 66 69 63 69 65 6e 74 2e 20 54 68 65 20 efficient. The
2280: 6f 76 65 72 61 6c 6c 20 73 69 6d 70 6c 69 63 69 overall simplici
2290: 74 79 20 6b 65 65 70 73 20 74 68 65 0a 63 6f 6e ty keeps the.con
22a0: 63 65 70 74 75 61 6c 20 62 75 72 64 65 6e 20 6c ceptual burden l
22b0: 6f 77 2c 20 77 68 69 63 68 20 65 6e 68 61 6e 63 ow, which enhanc
22c0: 65 73 20 74 68 65 20 75 74 69 6c 69 74 79 20 66 es the utility f
22d0: 6f 72 20 63 6f 6e 6e 65 63 74 69 6e 67 20 73 6f or connecting so
22e0: 66 74 77 61 72 65 0a 6d 6f 64 75 6c 65 73 20 66 ftware.modules f
22f0: 72 6f 6d 20 64 69 66 66 65 72 65 6e 74 20 6f 72 rom different or
2300: 69 67 69 6e 73 2c 20 74 68 65 20 75 73 65 20 6f igins, the use o
2310: 66 20 54 63 6c 20 61 73 20 61 20 73 6f 2d 63 61 f Tcl as a so-ca
2320: 6c 6c 65 64 20 22 67 6c 75 65 20 6c 61 6e 67 75 lled "glue langu
2330: 61 67 65 22 2e 0a 0a 54 68 65 72 65 20 61 72 65 age"...There are
2340: 20 73 6f 6d 65 20 64 65 66 69 63 69 74 73 20 74 some deficits t
2350: 6f 20 63 6f 6e 74 65 6e 64 20 77 69 74 68 2e 20 o contend with.
2360: 54 68 65 20 67 72 65 61 74 65 73 74 20 63 6f 6d The greatest com
2370: 70 6c 65 78 69 74 79 20 61 74 20 77 6f 72 6b 0a plexity at work.
2380: 69 73 20 74 68 65 20 6e 65 65 64 20 74 6f 20 6d is the need to m
2390: 61 6e 61 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c anage memory all
23a0: 6f 63 61 74 69 6f 6e 20 61 6e 64 20 6f 77 6e 65 ocation and owne
23b0: 72 73 68 69 70 2e 20 54 68 65 20 73 6f 6c 75 74 rship. The solut
23c0: 69 6f 6e 73 20 74 6f 0a 74 68 65 73 65 20 6d 61 ions to.these ma
23d0: 74 74 65 72 73 20 69 6e 76 6f 6c 76 65 20 61 20 tters involve a
23e0: 73 69 67 6e 69 66 69 63 61 6e 74 20 61 6d 6f 75 significant amou
23f0: 6e 74 20 6f 66 20 73 74 72 69 6e 67 20 63 6f 70 nt of string cop
2400: 79 69 6e 67 2e 20 46 6f 72 20 61 6e 79 0a 63 6f ying. For any.co
2410: 6d 6d 61 6e 64 73 20 74 68 61 74 20 74 72 65 61 mmands that trea
2420: 74 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 t arguments and
2430: 70 72 6f 64 75 63 65 20 72 65 73 75 6c 74 73 20 produce results
2440: 62 61 73 65 64 20 6f 6e 20 69 6e 74 65 72 70 72 based on interpr
2450: 65 74 61 74 69 6f 6e 73 0a 6f 74 68 65 72 20 74 etations.other t
2460: 68 61 6e 20 73 65 71 75 65 6e 63 65 73 20 6f 66 han sequences of
2470: 20 63 68 61 72 61 63 74 65 72 73 2c 20 70 61 72 characters, par
2480: 73 69 6e 67 20 6f 66 20 61 72 67 75 6d 65 6e 74 sing of argument
2490: 20 73 74 72 69 6e 67 73 20 69 6e 74 6f 0a 6f 74 strings into.ot
24a0: 68 65 72 20 72 65 70 72 65 73 65 6e 74 61 74 69 her representati
24b0: 6f 6e 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 ons suitable for
24c0: 20 63 6f 6d 6d 61 6e 64 20 6f 70 65 72 61 74 69 command operati
24d0: 6f 6e 73 20 61 6e 64 20 74 68 65 20 67 65 6e 65 ons and the gene
24e0: 72 61 74 69 6f 6e 0a 6f 66 20 61 20 72 65 73 75 ration.of a resu
24f0: 6c 74 20 73 74 72 69 6e 67 73 20 66 72 6f 6d 20 lt strings from
2500: 74 68 6f 73 65 20 6f 74 68 65 72 20 72 65 70 72 those other repr
2510: 65 73 65 6e 74 61 74 69 6f 6e 73 20 61 72 65 20 esentations are
2520: 63 6f 73 74 73 20 74 68 61 74 20 6d 75 73 74 0a costs that must.
2530: 62 65 20 72 65 70 65 61 74 65 64 20 61 67 61 69 be repeated agai
2540: 6e 20 61 6e 64 20 61 67 61 69 6e 2c 20 73 69 6e n and again, sin
2550: 63 65 20 6f 6e 6c 79 20 74 68 65 20 73 74 72 69 ce only the stri
2560: 6e 67 20 76 61 6c 75 65 73 20 74 68 65 6d 73 65 ng values themse
2570: 6c 76 65 73 20 63 61 72 72 79 0a 69 6e 66 6f 72 lves carry.infor
2580: 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 mation into and
2590: 6f 75 74 20 6f 66 20 63 6f 6d 6d 61 6e 64 20 70 out of command p
25a0: 72 6f 63 65 64 75 72 65 73 2e 0a 0a 46 69 6e 61 rocedures...Fina
25b0: 6c 6c 79 20 61 20 6c 61 72 67 65 20 64 65 66 69 lly a large defi
25c0: 63 69 74 20 6f 66 20 74 68 69 73 20 76 61 6c 75 cit of this valu
25d0: 65 20 6d 6f 64 65 6c 20 6f 66 20 73 74 72 69 6e e model of strin
25e0: 67 73 20 69 73 20 74 68 65 79 20 63 61 6e 6e 6f gs is they canno
25f0: 74 0a 69 6e 63 6c 75 64 65 20 74 68 65 20 65 6c t.include the el
2600: 65 6d 65 6e 74 20 2a 2a 4e 55 4c 2a 2a 20 77 69 ement **NUL** wi
2610: 74 68 69 6e 20 61 20 73 74 72 69 6e 67 2c 20 65 thin a string, e
2620: 76 65 6e 20 74 68 6f 75 67 68 20 74 68 61 74 20 ven though that
2630: 73 74 72 69 6e 67 0a 65 6c 65 6d 65 6e 74 20 6f string.element o
2640: 74 68 65 72 77 69 73 65 20 61 70 70 65 61 72 73 therwise appears
2650: 20 74 6f 20 62 65 20 6c 65 67 61 6c 20 69 6e 20 to be legal in
2660: 74 68 65 20 6c 61 6e 67 75 61 67 65 2e 20 49 6e the language. In
2670: 20 74 68 65 20 6c 61 6e 67 75 61 67 65 0a 6f 66 the language.of
2680: 20 74 68 65 20 64 61 79 2c 20 54 63 6c 20 37 20 the day, Tcl 7
2690: 69 73 20 6e 6f 74 20 5f 62 69 6e 61 72 79 20 73 is not _binary s
26a0: 61 66 65 5f 20 6f 72 20 5f 38 2d 62 69 74 20 63 afe_ or _8-bit c
26b0: 6c 65 61 6e 5f 2e 0a 0a 3c 70 72 65 3e 0a 60 60 lean_...<pre>.``
26c0: 60 0a 09 25 20 73 74 72 69 6e 67 20 6c 65 6e 67 `..% string leng
26d0: 74 68 20 3c 5c 78 30 31 3e 0a 09 33 0a 09 25 20 th <\x01>..3..%
26e0: 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 3c 5c string length <\
26f0: 78 30 30 3e 0a 09 31 0a 60 60 60 0a 3c 2f 70 72 x00>..1.```.</pr
2700: 65 3e 0a 0a 4e 6f 74 65 20 68 65 72 65 20 74 68 e>..Note here th
2710: 61 74 20 54 63 6c 20 62 61 63 6b 73 6c 61 73 68 at Tcl backslash
2720: 20 73 75 62 73 74 69 74 75 74 69 6f 6e 20 72 61 substitution ra
2730: 69 73 65 73 20 6e 6f 20 65 72 72 6f 72 20 77 68 ises no error wh
2740: 65 6e 20 61 73 6b 65 64 20 74 6f 0a 67 65 6e 65 en asked to.gene
2750: 72 61 74 65 20 74 68 65 20 2a 2a 4e 55 4c 2a 2a rate the **NUL**
2760: 20 62 79 74 65 2c 20 65 76 65 6e 20 74 68 6f 75 byte, even thou
2770: 67 68 20 54 63 6c 20 76 65 72 73 69 6f 6e 20 37 gh Tcl version 7
2780: 2e 36 20 68 61 73 20 6e 6f 20 77 61 79 20 61 74 .6 has no way at
2790: 0a 61 6c 6c 20 74 6f 20 64 6f 20 61 6e 79 74 68 .all to do anyth
27a0: 69 6e 67 20 77 69 74 68 20 74 68 61 74 20 62 79 ing with that by
27b0: 74 65 2e 20 41 74 20 73 6f 6d 65 20 70 6f 69 6e te. At some poin
27c0: 74 20 69 74 20 67 65 74 73 20 74 72 65 61 74 65 t it gets treate
27d0: 64 20 61 73 0a 61 20 73 74 72 69 6e 67 20 74 65 d as.a string te
27e0: 72 6d 69 6e 61 74 6f 72 2e 0a 0a 53 69 6e 63 65 rminator...Since
27f0: 20 54 63 6c 20 37 20 73 74 72 69 6e 67 73 20 61 Tcl 7 strings a
2800: 72 65 20 43 20 73 74 72 69 6e 67 73 2c 20 43 20 re C strings, C
2810: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6f 66 20 74 programmers of t
2820: 68 65 20 74 69 6d 65 20 77 65 72 65 20 66 61 6d he time were fam
2830: 69 6c 69 61 72 0a 77 69 74 68 20 74 68 65 20 69 iliar.with the i
2840: 73 73 75 65 20 6f 66 20 62 69 6e 61 72 79 20 73 ssue of binary s
2850: 61 66 65 74 79 2c 20 61 6e 64 20 73 65 76 65 72 afety, and sever
2860: 61 6c 20 73 79 73 74 65 6d 73 20 6f 66 20 74 68 al systems of th
2870: 65 20 64 61 79 20 6d 61 64 65 20 75 73 65 20 6f e day made use o
2880: 66 0a 73 6f 6c 75 74 69 6f 6e 73 2e 20 45 6c 65 f.solutions. Ele
2890: 63 74 72 6f 6e 69 63 20 6d 61 69 6c 20 73 79 73 ctronic mail sys
28a0: 74 65 6d 73 20 68 61 64 20 74 6f 20 64 65 61 6c tems had to deal
28b0: 20 77 69 74 68 20 74 68 65 20 61 62 69 6c 69 74 with the abilit
28c0: 79 20 74 6f 20 70 61 73 73 0a 61 72 62 69 74 72 y to pass.arbitr
28d0: 61 72 79 20 62 69 6e 61 72 79 20 64 61 74 61 20 ary binary data
28e0: 74 68 72 6f 75 67 68 20 73 79 73 74 65 6d 73 20 through systems
28f0: 77 68 65 72 65 20 62 69 6e 61 72 79 20 73 61 66 where binary saf
2900: 65 74 79 20 6f 66 20 61 6c 6c 20 74 68 65 20 63 ety of all the c
2910: 6f 6d 70 6f 6e 65 6e 74 73 0a 63 6f 75 6c 64 20 omponents.could
2920: 6e 6f 74 20 62 65 20 61 73 73 75 6d 65 64 2e 20 not be assumed.
2930: 54 68 65 20 73 6f 6c 75 74 69 6f 6e 20 77 61 73 The solution was
2940: 20 74 6f 20 64 65 66 69 6e 65 20 61 20 6e 75 6d to define a num
2950: 62 65 72 20 6f 66 20 65 6e 63 6f 64 69 6e 67 20 ber of encoding
2960: 73 63 68 65 6d 65 73 2e 0a 54 63 6c 20 37 20 64 schemes..Tcl 7 d
2970: 69 64 20 6e 6f 74 20 74 61 6b 65 20 74 68 69 73 id not take this
2980: 20 61 70 70 72 6f 61 63 68 2e 20 41 6e 79 20 65 approach. Any e
2990: 6e 63 6f 64 69 6e 67 20 64 65 66 69 6e 65 64 20 ncoding defined
29a0: 74 6f 20 73 75 70 70 6f 72 74 0a 74 68 65 20 2a to support.the *
29b0: 2a 4e 55 4c 2a 2a 20 62 79 74 65 20 77 6f 75 6c *NUL** byte woul
29c0: 64 20 68 61 76 65 20 74 6f 20 62 6f 72 72 6f 77 d have to borrow
29d0: 20 66 72 6f 6d 20 73 6f 6d 65 20 62 79 74 65 20 from some byte
29e0: 73 65 71 75 65 6e 63 65 20 61 6c 72 65 61 64 79 sequence already
29f0: 0a 72 65 70 72 65 73 65 6e 74 69 6e 67 20 69 74 .representing it
2a00: 73 65 6c 66 2e 20 49 74 20 6d 75 73 74 20 68 61 self. It must ha
2a10: 76 65 20 62 65 65 6e 20 6a 75 64 67 65 64 20 74 ve been judged t
2a20: 68 61 74 20 74 68 65 20 75 74 69 6c 69 74 79 20 hat the utility
2a30: 6f 66 20 74 68 65 20 2a 2a 4e 55 4c 2a 2a 0a 77 of the **NUL**.w
2a40: 61 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 as less than the
2a50: 20 64 69 73 75 74 69 6c 69 74 79 20 6f 66 20 63 disutility of c
2a60: 6f 6d 70 6c 69 63 61 74 69 6e 67 20 74 68 65 20 omplicating the
2a70: 76 61 6c 75 65 20 65 6e 63 6f 64 69 6e 67 20 74 value encoding t
2a80: 68 61 74 20 61 6c 6c 0a 63 6f 6d 6d 61 6e 64 73 hat all.commands
2a90: 20 77 6f 75 6c 64 20 6e 65 65 64 20 74 6f 20 63 would need to c
2aa0: 6f 6e 74 65 6e 64 20 77 69 74 68 2c 20 61 74 20 ontend with, at
2ab0: 6c 65 61 73 74 20 66 6f 72 20 67 65 6e 65 72 61 least for genera
2ac0: 6c 20 76 61 6c 75 65 73 2e 0a 0a 41 73 20 54 63 l values...As Tc
2ad0: 6c 20 67 61 69 6e 65 64 20 63 72 6f 73 73 2d 70 l gained cross-p
2ae0: 6c 61 74 66 6f 72 6d 20 63 68 61 6e 6e 65 6c 20 latform channel
2af0: 73 75 70 70 6f 72 74 2c 20 74 68 65 20 69 6e 61 support, the ina
2b00: 62 69 6c 74 79 20 74 6f 20 73 74 6f 72 65 20 69 bilty to store i
2b10: 6e 20 61 0a 54 63 6c 20 76 61 6c 75 65 20 74 68 n a.Tcl value th
2b20: 65 20 61 72 62 69 74 72 61 72 79 20 64 61 74 61 e arbitrary data
2b30: 20 72 65 61 64 20 69 6e 20 66 72 6f 6d 20 61 20 read in from a
2b40: 63 68 61 6e 6e 65 6c 20 73 74 61 72 74 65 64 20 channel started
2b50: 74 6f 20 63 61 75 73 65 20 6d 6f 72 65 0a 61 6e to cause more.an
2b60: 64 20 6d 6f 72 65 20 70 61 69 6e 2e 20 49 6e 20 d more pain. In
2b70: 70 61 72 74 69 63 75 6c 61 72 20 69 74 20 77 61 particular it wa
2b80: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
2b90: 6f 20 73 61 66 65 6c 79 20 63 6f 70 79 20 61 20 o safely copy a
2ba0: 66 69 6c 65 2c 0a 6f 72 20 74 72 61 6e 73 6d 69 file,.or transmi
2bb0: 74 20 69 74 73 20 63 6f 6e 74 65 6e 74 73 20 74 t its contents t
2bc0: 6f 20 61 6e 20 6f 75 74 70 75 74 20 63 68 61 6e o an output chan
2bd0: 6e 65 6c 20 28 61 73 20 6f 6e 65 20 6d 69 67 68 nel (as one migh
2be0: 74 20 73 65 65 6b 20 74 6f 20 64 6f 0a 77 68 65 t seek to do.whe
2bf0: 6e 20 70 72 6f 67 72 61 6d 6d 69 6e 67 20 61 20 n programming a
2c00: 77 65 62 20 73 65 72 76 65 72 29 20 77 69 74 68 web server) with
2c10: 20 63 6f 64 65 20 6c 69 6b 65 0a 0a 3c 70 72 65 code like..<pre
2c20: 3e 0a 60 60 60 0a 09 66 63 6f 6e 66 69 67 75 72 >.```..fconfigur
2c30: 65 20 24 69 6e 20 2d 74 72 61 6e 73 6c 61 74 69 e $in -translati
2c40: 6f 6e 20 62 69 6e 61 72 79 0a 09 66 63 6f 6e 66 on binary..fconf
2c50: 69 67 75 72 65 20 24 6f 75 74 20 2d 74 72 61 6e igure $out -tran
2c60: 73 6c 61 74 69 6f 6e 20 62 69 6e 61 72 79 0a 09 slation binary..
2c70: 70 75 74 73 20 2d 6e 6f 6e 65 77 6c 69 6e 65 20 puts -nonewline
2c80: 24 6f 75 74 20 5b 72 65 61 64 20 24 69 6e 5d 0a $out [read $in].
2c90: 60 60 60 0a 3c 2f 70 72 65 3e 0a 0a 54 68 65 20 ```.</pre>..The
2ca0: 69 73 73 75 65 20 77 61 73 20 73 6f 20 63 6f 6d issue was so com
2cb0: 70 65 6c 6c 69 6e 67 20 74 68 61 74 20 54 63 6c pelling that Tcl
2cc0: 20 67 61 69 6e 65 64 20 61 20 73 65 6d 69 2d 73 gained a semi-s
2cd0: 65 63 72 65 74 20 75 6e 73 75 70 70 6f 72 74 65 ecret unsupporte
2ce0: 64 0a 63 6f 6d 6d 61 6e 64 20 5f 5f 75 6e 73 75 d.command __unsu
2cf0: 70 70 6f 72 74 65 64 30 5f 5f 20 66 6f 72 20 6a pported0__ for j
2d00: 75 73 74 20 74 68 69 73 20 70 75 72 70 6f 73 65 ust this purpose
2d10: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 61 6c with functional
2d20: 69 74 79 0a 6d 75 63 68 20 6c 69 6b 65 20 74 68 ity.much like th
2d30: 65 20 63 6f 6d 6d 61 6e 64 20 5f 5f 66 63 6f 70 e command __fcop
2d40: 79 5f 5f 20 74 68 61 74 20 77 6f 75 6c 64 20 63 y__ that would c
2d50: 6f 6d 65 20 6c 61 74 65 72 2e 0a 0a 49 74 20 69 ome later...It i
2d60: 73 20 6d 6f 72 65 20 73 70 65 63 75 6c 61 74 69 s more speculati
2d70: 76 65 2c 20 62 75 74 20 69 74 20 61 70 70 65 61 ve, but it appea
2d80: 72 73 20 74 68 65 20 69 6e 61 62 69 6c 69 74 79 rs the inability
2d90: 20 74 6f 20 70 61 73 73 20 61 72 62 69 74 72 61 to pass arbitra
2da0: 72 79 0a 62 69 6e 61 72 79 20 64 61 74 61 20 74 ry.binary data t
2db0: 68 72 6f 75 67 68 20 54 63 6c 20 63 6f 6e 74 72 hrough Tcl contr
2dc0: 69 62 75 74 65 64 20 74 6f 20 74 68 65 20 6c 61 ibuted to the la
2dd0: 74 65 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 6f te development o
2de0: 66 20 66 75 6c 6c 0a 73 75 70 70 6f 72 74 20 6f f full.support o
2df0: 66 20 6d 61 6e 79 20 69 6d 61 67 65 20 66 6f 72 f many image for
2e00: 6d 61 74 73 20 66 6f 72 20 54 6b 20 63 6f 6d 6d mats for Tk comm
2e10: 61 6e 64 20 5f 5f 69 6d 61 67 65 20 63 72 65 61 and __image crea
2e20: 74 65 20 70 68 6f 74 6f 20 2d 64 61 74 61 5f 5f te photo -data__
2e30: 2e 0a 54 6b 20 34 20 6e 65 76 65 72 20 68 61 64 ..Tk 4 never had
2e40: 20 61 6e 79 20 62 75 69 6c 74 2d 69 6e 20 69 6d any built-in im
2e50: 61 67 65 20 66 6f 72 6d 61 74 20 74 68 61 74 20 age format that
2e60: 73 75 70 70 6f 72 74 65 64 20 74 68 69 73 20 66 supported this f
2e70: 75 6e 63 74 69 6f 6e 2e 0a 0a 53 69 6e 63 65 20 unction...Since
2e80: 54 63 6c 20 49 2f 4f 20 63 6f 75 6c 64 20 72 65 Tcl I/O could re
2e90: 61 64 20 69 6e 20 61 6e 64 20 77 72 69 74 65 20 ad in and write
2ea0: 6f 75 74 20 62 69 6e 61 72 79 20 64 61 74 61 2c out binary data,
2eb0: 20 62 75 74 20 74 68 61 74 20 64 61 74 61 20 63 but that data c
2ec0: 6f 75 6c 64 0a 6e 6f 74 20 70 61 73 73 20 62 65 ould.not pass be
2ed0: 74 77 65 65 6e 20 63 6f 6d 6d 61 6e 64 73 2c 20 tween commands,
2ee0: 74 68 69 73 20 66 6f 72 63 65 64 20 74 68 65 20 this forced the
2ef0: 64 65 73 69 67 6e 20 6f 66 20 6d 61 6e 79 20 63 design of many c
2f00: 6f 6d 6d 61 6e 64 73 20 74 6f 20 61 63 63 65 70 ommands to accep
2f10: 74 0a 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d t.filename argum
2f20: 65 6e 74 73 20 74 6f 20 64 6f 20 74 68 65 69 72 ents to do their
2f30: 20 6f 77 6e 20 49 2f 4f 20 72 61 74 68 65 72 20 own I/O rather
2f40: 74 68 61 6e 20 63 6f 6d 70 6f 73 65 20 77 69 74 than compose wit
2f50: 68 20 67 65 6e 65 72 61 6c 0a 6c 61 6e 67 75 61 h general.langua
2f60: 67 65 2d 77 69 64 65 20 49 2f 4f 20 66 61 63 69 ge-wide I/O faci
2f70: 6c 69 74 69 65 73 2e 20 41 73 20 63 68 61 6e 6e lities. As chann
2f80: 65 6c 73 20 65 78 70 61 6e 64 65 64 20 74 6f 20 els expanded to
2f90: 69 6e 63 6c 75 64 65 20 73 6f 63 6b 65 74 73 20 include sockets
2fa0: 61 6e 64 0a 70 69 70 65 73 20 74 68 65 20 63 6f and.pipes the co
2fb0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 78 70 61 rresponding expa
2fc0: 6e 73 69 6f 6e 20 6f 66 20 75 74 69 6c 69 74 79 nsion of utility
2fd0: 20 63 6f 75 6c 64 20 6e 6f 74 20 6f 63 63 75 72 could not occur
2fe0: 20 69 6e 20 63 6f 6d 6d 61 6e 64 73 0a 63 6f 64 in commands.cod
2ff0: 65 64 20 69 6e 20 74 68 69 73 20 77 61 79 20 77 ed in this way w
3000: 69 74 68 6f 75 74 20 66 75 72 74 68 65 72 20 72 ithout further r
3010: 65 76 69 73 69 6f 6e 73 2e 0a 0a 54 68 65 20 70 evisions...The p
3020: 75 62 6c 69 63 20 43 20 41 50 49 20 66 6f 72 20 ublic C API for
3030: 54 63 6c 20 37 2e 36 20 69 6e 63 6c 75 64 65 73 Tcl 7.6 includes
3040: 20 32 32 20 72 6f 75 74 69 6e 65 73 20 74 68 61 22 routines tha
3050: 74 20 72 65 74 75 72 6e 0a 61 20 28 5f 5f 63 68 t return.a (__ch
3060: 61 72 5f 5f 20 2a 29 20 77 68 69 63 68 20 69 73 ar__ *) which is
3070: 20 61 20 54 63 6c 20 73 74 72 69 6e 67 20 76 61 a Tcl string va
3080: 6c 75 65 2e 20 49 74 20 69 6e 63 6c 75 64 65 73 lue. It includes
3090: 20 37 34 20 72 6f 75 74 69 6e 65 73 0a 74 68 61 74 routines.tha
30a0: 74 20 61 63 63 65 70 74 20 61 74 20 6c 65 61 73 t accept at leas
30b0: 74 20 6f 6e 65 20 28 5f 5f 63 68 61 72 5f 5f 20 t one (__char__
30c0: 2a 29 20 61 72 67 75 6d 65 6e 74 20 74 68 61 74 *) argument that
30d0: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a is intended to.
30e0: 62 65 20 61 20 54 63 6c 20 73 74 72 69 6e 67 20 be a Tcl string
30f0: 76 61 6c 75 65 2e 20 49 74 20 69 6e 63 6c 75 64 value. It includ
3100: 65 73 20 36 20 63 61 6c 6c 62 61 63 6b 20 73 69 es 6 callback si
3110: 67 6e 61 74 75 72 65 20 74 79 70 65 64 65 66 73 gnature typedefs
3120: 20 74 68 61 74 0a 73 70 65 63 69 66 79 20 63 61 that.specify ca
3130: 6c 6c 62 61 63 6b 20 69 6e 74 65 72 66 61 63 65 llback interface
3140: 73 20 77 68 69 63 68 20 6d 75 73 74 20 61 63 63 s which must acc
3150: 65 70 74 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 ept at least one
3160: 20 28 5f 5f 63 68 61 72 5f 5f 20 2a 29 0a 61 72 (__char__ *).ar
3170: 67 75 6d 65 6e 74 20 74 68 61 74 20 69 73 20 61 gument that is a
3180: 20 54 63 6c 20 73 74 72 69 6e 67 20 76 61 6c 75 Tcl string valu
3190: 65 2e 20 49 74 20 69 6e 63 6c 75 64 65 73 20 6f e. It includes o
31a0: 6e 65 20 63 61 6c 6c 62 61 63 6b 20 73 69 67 6e ne callback sign
31b0: 61 74 75 72 65 0a 74 79 70 65 64 65 66 2c 20 2a ature.typedef, *
31c0: 2a 54 63 6c 5f 56 61 72 54 72 61 63 65 50 72 6f *Tcl_VarTracePro
31d0: 63 2a 2a 2c 20 74 68 61 74 20 73 70 65 63 66 69 c**, that specfi
31e0: 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 69 6e es a callback in
31f0: 74 65 72 66 61 63 65 20 74 68 61 74 0a 6d 75 73 terface that.mus
3200: 74 20 72 65 74 75 72 6e 20 61 20 28 5f 5f 63 68 t return a (__ch
3210: 61 72 5f 5f 20 2a 29 20 74 68 61 74 20 69 73 20 ar__ *) that is
3220: 61 20 54 63 6c 20 73 74 72 69 6e 67 20 76 61 6c a Tcl string val
3230: 75 65 2e 20 20 41 6c 6c 20 6f 66 20 74 68 65 73 ue. All of thes
3240: 65 0a 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 e.components of
3250: 74 68 65 20 70 75 62 6c 69 63 20 41 50 49 20 61 the public API a
3260: 72 65 20 70 6f 69 6e 74 73 20 6f 66 20 70 6f 74 re points of pot
3270: 65 6e 74 69 61 6c 20 63 6f 6d 70 61 74 69 62 69 ential compatibi
3280: 6c 69 74 79 0a 63 6f 6e 63 65 72 6e 20 61 73 20 lity.concern as
3290: 74 68 65 20 63 6f 6e 63 65 70 74 69 6f 6e 20 6f the conception o
32a0: 66 20 54 63 6c 20 73 74 72 69 6e 67 73 20 73 68 f Tcl strings sh
32b0: 69 66 74 73 20 6f 76 65 72 20 74 69 6d 65 2e 0a ifts over time..
32c0: 0a 23 23 20 54 63 6c 20 38 2e 30 20 28 44 65 76 .## Tcl 8.0 (Dev
32d0: 65 6c 6f 70 6d 65 6e 74 20 62 65 67 75 6e 20 31 elopment begun 1
32e0: 39 39 36 2c 20 4f 66 66 69 63 69 61 6c 20 72 65 996, Official re
32f0: 6c 65 61 73 65 20 31 39 39 37 2d 31 39 39 39 29 lease 1997-1999)
3300: 0a 0a 2a 43 6f 75 6e 74 65 64 20 61 72 72 61 79 ..*Counted array
3310: 20 6f 66 2a 20 2a 2a 63 68 61 72 2a 2a 0a 0a 49 of* **char**..I
3320: 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 6d 65 64 n order to remed
3330: 79 20 74 68 65 20 64 65 66 69 63 69 74 73 20 6f y the deficits o
3340: 66 20 74 68 65 20 54 63 6c 20 37 20 76 61 6c 75 f the Tcl 7 valu
3350: 65 20 73 65 74 2c 20 74 68 65 20 69 6d 70 6c 65 e set, the imple
3360: 6d 65 6e 74 61 74 69 6f 6e 0a 6f 66 20 54 63 6c mentation.of Tcl
3370: 20 73 74 72 69 6e 67 73 20 68 61 64 20 74 6f 20 strings had to
3380: 62 65 20 6d 6f 64 69 66 69 65 64 2e 20 54 68 65 be modified. The
3390: 20 6d 6f 64 69 66 69 63 61 74 69 6f 6e 20 70 75 modification pu
33a0: 74 20 69 6e 20 70 6c 61 63 65 20 62 79 0a 54 63 t in place by.Tc
33b0: 6c 20 38 2e 30 20 77 61 73 20 74 6f 20 73 74 6f l 8.0 was to sto
33c0: 70 20 74 72 65 61 74 69 6e 67 20 65 76 65 72 79 p treating every
33d0: 20 2a 2a 4e 55 4c 2a 2a 20 62 79 74 65 20 61 73 **NUL** byte as
33e0: 20 61 20 6d 61 72 6b 65 72 20 6f 66 20 74 68 65 a marker of the
33f0: 20 65 6e 64 20 6f 66 0a 61 20 54 63 6c 20 73 74 end of.a Tcl st
3400: 72 69 6e 67 20 76 61 6c 75 65 2e 20 54 63 6c 20 ring value. Tcl
3410: 77 6f 75 6c 64 20 62 65 67 69 6e 20 74 6f 20 70 would begin to p
3420: 65 72 6d 69 74 20 61 20 2a 2a 4e 55 4c 2a 2a 20 ermit a **NUL**
3430: 62 79 74 65 20 69 6e 20 74 68 65 20 69 6e 74 65 byte in the inte
3440: 72 6e 61 6c 0a 70 6f 72 74 69 6f 6e 20 6f 66 20 rnal.portion of
3450: 74 68 65 20 5f 5f 63 68 61 72 5f 5f 20 61 72 72 the __char__ arr
3460: 61 79 73 20 68 6f 6c 64 69 6e 67 20 54 63 6c 20 ays holding Tcl
3470: 73 74 72 69 6e 67 73 2e 20 53 69 6e 63 65 20 74 strings. Since t
3480: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 61 he presence of.a
3490: 20 2a 2a 4e 55 4c 2a 2a 20 62 79 74 65 20 77 6f **NUL** byte wo
34a0: 75 6c 64 20 6e 6f 20 6c 6f 6e 67 65 72 20 28 61 uld no longer (a
34b0: 6c 77 61 79 73 29 20 74 65 72 6d 69 6e 61 74 65 lways) terminate
34c0: 20 61 20 73 74 72 69 6e 67 2c 20 61 20 28 5f 5f a string, a (__
34d0: 63 68 61 72 5f 5f 20 2a 29 0a 61 6c 6f 6e 65 20 char__ *).alone
34e0: 63 6f 75 6c 64 20 6e 6f 20 6c 6f 6e 67 65 72 20 could no longer
34f0: 63 6f 6e 76 65 79 20 61 6e 20 61 72 62 69 74 72 convey an arbitr
3500: 61 72 79 20 73 74 72 69 6e 67 20 76 61 6c 75 65 ary string value
3510: 2e 20 4e 65 77 20 69 6e 74 65 72 66 61 63 65 73 . New interfaces
3520: 20 77 65 72 65 0a 64 65 66 69 6e 65 64 20 77 68 were.defined wh
3530: 65 72 65 20 61 20 28 5f 5f 63 68 61 72 5f 5f 20 ere a (__char__
3540: 2a 29 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 *) argument was
3550: 61 63 63 6f 6d 70 61 6e 69 65 64 20 62 79 20 61 accompanied by a
3560: 6e 20 5f 5f 69 6e 74 5f 5f 20 61 72 67 75 6d 65 n __int__ argume
3570: 6e 74 0a 74 68 61 74 20 77 6f 75 6c 64 20 73 70 nt.that would sp
3580: 65 63 69 66 79 20 68 6f 77 20 6d 61 6e 79 20 62 ecify how many b
3590: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 ytes of memory a
35a0: 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 68 t the pointer sh
35b0: 6f 75 6c 64 20 62 65 0a 74 61 6b 65 6e 20 61 73 ould be.taken as
35c0: 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 6c 75 the string valu
35d0: 65 2e 20 20 0a 0a 41 73 20 61 6e 20 69 6c 6c 75 e. ..As an illu
35e0: 73 74 72 61 74 69 6f 6e 2c 20 63 6f 6e 73 69 64 stration, consid
35f0: 65 72 20 74 68 65 20 54 63 6c 20 37 20 70 75 62 er the Tcl 7 pub
3600: 6c 69 63 20 72 6f 75 74 69 6e 65 0a 0a 3e 09 2a lic routine..>.*
3610: 2a 69 6e 74 2a 2a 20 2a 2a 54 63 6c 5f 53 63 61 *int** **Tcl_Sca
3620: 6e 45 6c 65 6d 65 6e 74 2a 2a 20 28 63 6f 6e 73 nElement** (cons
3630: 74 20 2a 2a 63 68 61 72 2a 2a 20 2a 20 5f 73 74 t **char** * _st
3640: 72 69 6e 67 5f 2c 20 2a 2a 69 6e 74 2a 2a 20 2a ring_, **int** *
3650: 20 5f 66 6c 61 67 50 74 72 5f 20 29 3b 0a 0a 49 _flagPtr_ );..I
3660: 74 20 69 73 20 61 20 75 74 69 6c 69 74 79 20 72 t is a utility r
3670: 6f 75 74 69 6e 65 20 75 73 65 64 20 69 6e 20 74 outine used in t
3680: 68 65 20 74 61 73 6b 20 6f 66 20 67 65 6e 65 72 he task of gener
3690: 61 74 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 ating the string
36a0: 20 76 61 6c 75 65 0a 6f 66 20 61 20 6c 69 73 74 value.of a list
36b0: 20 6f 75 74 20 6f 66 20 74 68 65 20 73 74 72 69 out of the stri
36c0: 6e 67 20 76 61 6c 75 65 73 20 6f 66 20 69 74 73 ng values of its
36d0: 20 65 6c 65 6d 65 6e 74 73 2e 20 54 68 65 20 61 elements. The a
36e0: 72 67 75 6d 65 6e 74 20 5f 73 74 72 69 6e 67 5f rgument _string_
36f0: 0a 69 73 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f .is an element o
3700: 66 20 74 68 65 20 6c 69 73 74 20 70 61 73 73 65 f the list passe
3710: 64 20 69 6e 20 61 73 20 61 20 2a 2a 4e 55 4c 2a d in as a **NUL*
3720: 2a 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 *-terminated str
3730: 69 6e 67 2e 20 49 74 0a 69 73 20 6e 6f 74 20 70 ing. It.is not p
3740: 6f 73 73 69 62 6c 65 20 74 6f 20 73 75 63 63 65 ossible to succe
3750: 73 73 66 75 6c 6c 79 20 75 73 65 20 74 68 69 73 ssfully use this
3760: 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 70 61 interface to pa
3770: 73 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 ss in the string
3780: 0a 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 73 74 .value of a list
3790: 20 65 6c 65 6d 65 6e 74 20 74 68 61 74 20 69 6e element that in
37a0: 63 6c 75 64 65 73 20 74 68 65 20 2a 2a 4e 55 4c cludes the **NUL
37b0: 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 20 42 79 ** character. By
37c0: 20 65 78 70 61 6e 64 69 6e 67 0a 74 68 65 20 54 expanding.the T
37d0: 63 6c 20 76 61 6c 75 65 20 73 65 74 2c 20 54 63 cl value set, Tc
37e0: 6c 20 6c 65 66 74 20 6d 61 6e 79 20 70 75 62 6c l left many publ
37f0: 69 63 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e ic interfaces in
3800: 63 61 70 61 62 6c 65 20 6f 66 20 64 65 61 6c 69 capable of deali
3810: 6e 67 20 77 69 74 68 0a 74 68 65 20 65 6e 74 69 ng with.the enti
3820: 72 65 20 76 61 6c 75 65 20 73 65 74 2e 20 54 68 re value set. Th
3830: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 63 6f 6e ese routines con
3840: 74 69 6e 75 65 20 74 6f 20 64 6f 20 77 68 61 74 tinue to do what
3850: 20 74 68 65 79 20 61 6c 77 61 79 73 20 64 69 64 they always did
3860: 2c 0a 61 6e 64 20 66 6f 72 20 73 6f 6d 65 20 70 ,.and for some p
3870: 75 72 70 6f 73 65 73 20 74 68 61 74 20 69 73 20 urposes that is
3880: 67 6f 6f 64 20 65 6e 6f 75 67 68 2c 20 62 75 74 good enough, but
3890: 20 74 68 65 79 20 61 72 65 20 75 6e 73 75 69 74 they are unsuit
38a0: 61 62 6c 65 20 66 6f 72 0a 75 73 65 73 20 74 68 able for.uses th
38b0: 61 74 20 6d 75 73 74 20 61 63 63 6f 6d 6d 6f 64 at must accommod
38c0: 61 74 65 20 74 68 65 20 6e 65 77 20 76 61 6c 75 ate the new valu
38d0: 65 73 20 73 75 70 70 6f 72 74 65 64 20 69 6e 20 es supported in
38e0: 54 63 6c 20 38 2e 30 2e 20 54 68 69 73 20 6c 65 Tcl 8.0. This le
38f0: 61 64 73 0a 74 6f 20 74 68 65 20 63 72 65 61 74 ads.to the creat
3900: 69 6f 6e 20 6f 66 20 61 6e 20 61 64 64 69 74 69 ion of an additi
3910: 6f 6e 61 6c 20 70 75 62 6c 69 63 20 72 6f 75 74 onal public rout
3920: 69 6e 65 0a 0a 3e 09 2a 2a 69 6e 74 2a 2a 20 2a ine..>.**int** *
3930: 2a 54 63 6c 5f 53 63 61 6e 43 6f 75 6e 74 65 64 *Tcl_ScanCounted
3940: 45 6c 65 6d 65 6e 74 2a 2a 20 28 63 6f 6e 73 74 Element** (const
3950: 20 2a 2a 63 68 61 72 2a 2a 20 2a 20 5f 73 74 72 **char** * _str
3960: 69 6e 67 5f 2c 20 2a 2a 69 6e 74 2a 2a 20 5f 6c ing_, **int** _l
3970: 65 6e 67 74 68 5f 2c 20 2a 2a 69 6e 74 2a 2a 20 ength_, **int**
3980: 2a 20 5f 66 6c 61 67 50 74 72 5f 20 29 3b 0a 0a * _flagPtr_ );..
3990: 54 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 The additional a
39a0: 72 67 75 6d 65 6e 74 20 5f 6c 65 6e 67 74 68 5f rgument _length_
39b0: 20 63 6f 6d 62 69 6e 65 73 20 77 69 74 68 20 74 combines with t
39c0: 68 65 20 61 72 67 75 6d 65 6e 74 20 5f 73 74 72 he argument _str
39d0: 69 6e 67 5f 20 74 6f 0a 74 72 61 6e 73 6d 69 74 ing_ to.transmit
39e0: 20 61 6e 79 20 54 63 6c 20 38 2e 30 20 73 74 72 any Tcl 8.0 str
39f0: 69 6e 67 20 76 61 6c 75 65 20 69 6e 74 6f 20 74 ing value into t
3a00: 68 65 20 72 6f 75 74 69 6e 65 2e 20 49 6e 20 6d he routine. In m
3a10: 6f 73 74 20 69 6e 74 65 72 66 61 63 65 73 0a 65 ost interfaces.e
3a20: 78 70 61 6e 64 65 64 20 69 6e 20 74 68 69 73 20 xpanded in this
3a30: 77 61 79 2c 20 69 74 20 69 73 20 63 6f 6e 76 65 way, it is conve
3a40: 6e 74 69 6f 6e 61 6c 20 66 6f 72 20 74 68 65 20 ntional for the
3a50: 5f 6c 65 6e 67 74 68 5f 20 61 72 67 75 6d 65 6e _length_ argumen
3a60: 74 20 74 6f 0a 61 63 63 65 70 74 20 74 68 65 20 t to.accept the
3a70: 76 61 6c 75 65 20 2a 2a 2d 31 2a 2a 20 28 6f 72 value **-1** (or
3a80: 20 73 6f 6d 65 74 69 6d 65 73 20 61 6e 79 20 6e sometimes any n
3a90: 65 67 61 74 69 76 65 20 76 61 6c 75 65 29 20 61 egative value) a
3aa0: 73 20 61 20 73 69 67 6e 61 6c 0a 74 68 61 74 20 s a signal.that
3ab0: 5f 73 74 72 69 6e 67 5f 20 69 73 20 2a 2a 4e 55 _string_ is **NU
3ac0: 4c 2a 2a 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 L**-terminated.
3ad0: 41 6e 6f 74 68 65 72 20 61 64 76 61 6e 74 61 67 Another advantag
3ae0: 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
3af0: 61 63 65 0a 69 73 20 74 68 61 74 20 69 74 20 69 ace.is that it i
3b00: 73 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 20 s not necessary
3b10: 66 6f 72 20 5f 73 74 72 69 6e 67 5f 20 5b 20 5f for _string_ [ _
3b20: 6c 65 6e 67 74 68 5f 20 5d 20 74 6f 20 63 6f 6e length_ ] to con
3b30: 74 61 69 6e 20 74 68 65 0a 62 79 74 65 20 76 61 tain the.byte va
3b40: 6c 75 65 20 2a 2a 4e 55 4c 2a 2a 20 2e 20 54 68 lue **NUL** . Th
3b50: 69 73 20 6d 61 6b 65 73 20 69 74 20 65 61 73 69 is makes it easi
3b60: 65 72 20 74 6f 20 70 61 73 73 20 73 75 62 73 74 er to pass subst
3b70: 72 69 6e 67 73 20 6f 66 20 6c 61 72 67 65 72 0a rings of larger.
3b80: 73 74 72 69 6e 67 73 20 77 69 74 68 6f 75 74 20 strings without
3b90: 74 68 65 20 6e 65 65 64 20 74 6f 20 63 6f 70 79 the need to copy
3ba0: 20 6f 72 20 6f 76 65 72 77 72 69 74 65 2e 0a 0a or overwrite...
3bb0: 54 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 This implementat
3bc0: 69 6f 6e 20 69 73 20 6f 66 74 65 6e 20 63 61 6c ion is often cal
3bd0: 6c 65 64 20 61 0a 63 6f 75 6e 74 65 64 20 73 74 led a.counted st
3be0: 72 69 6e 67 20 74 6f 20 64 69 73 74 69 6e 67 75 ring to distingu
3bf0: 69 73 68 20 69 74 20 66 72 6f 6d 20 61 20 2a 2a ish it from a **
3c00: 4e 55 4c 2a 2a 2d 74 65 72 6d 69 6e 61 74 65 64 NUL**-terminated
3c10: 20 73 74 72 69 6e 67 2e 0a 49 6e 20 54 63 6c 20 string..In Tcl
3c20: 38 2e 30 2c 20 65 76 65 72 79 20 76 61 6c 69 64 8.0, every valid
3c30: 20 54 63 6c 20 73 74 72 69 6e 67 20 69 73 20 61 Tcl string is a
3c40: 20 73 65 71 75 65 6e 63 65 20 6f 66 20 7a 65 72 sequence of zer
3c50: 6f 20 75 70 0a 74 6f 20 2a 2a 49 4e 54 5f 4d 41 o up.to **INT_MA
3c60: 58 2a 2a 20 5f 5f 63 68 61 72 5f 5f 20 76 61 6c X** __char__ val
3c70: 75 65 73 20 66 72 6f 6d 20 74 68 65 20 72 61 6e ues from the ran
3c80: 67 65 20 30 2e 2e 32 35 35 2e 0a 49 6e 20 74 68 ge 0..255..In th
3c90: 65 20 6e 65 77 20 72 65 70 72 65 73 65 6e 74 61 e new representa
3ca0: 74 69 6f 6e 2c 20 74 68 65 20 73 65 74 20 6f 66 tion, the set of
3cb0: 20 76 61 6c 69 64 20 54 63 6c 20 73 74 72 69 6e valid Tcl strin
3cc0: 67 73 20 69 73 20 62 6f 74 68 20 65 78 70 61 6e gs is both expan
3cd0: 64 65 64 0a 61 6e 64 20 63 6f 6e 74 72 61 63 74 ded.and contract
3ce0: 65 64 2e 20 20 54 68 65 20 61 6c 70 68 61 62 65 ed. The alphabe
3cf0: 74 20 69 73 20 65 78 70 61 6e 64 65 64 20 74 6f t is expanded to
3d00: 20 69 6e 63 6c 75 64 65 20 2a 2a 4e 55 4c 2a 2a include **NUL**
3d10: 2c 20 77 68 69 6c 65 20 61 0a 64 65 66 69 6e 65 , while a.define
3d20: 64 20 6c 69 6d 69 74 20 69 73 20 69 6d 70 6f 73 d limit is impos
3d30: 65 64 20 6f 6e 20 74 68 65 20 6c 65 6e 67 74 68 ed on the length
3d40: 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 73 of the string s
3d50: 65 71 75 65 6e 63 65 20 6f 66 20 65 6c 65 6d 65 equence of eleme
3d60: 6e 74 73 0a 66 72 6f 6d 20 74 68 61 74 20 61 6c nts.from that al
3d70: 70 68 61 62 65 74 20 66 6f 72 20 74 68 65 20 66 phabet for the f
3d80: 69 72 73 74 20 74 69 6d 65 2e 0a 0a 49 6e 20 74 irst time...In t
3d90: 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 61 76 he context of av
3da0: 61 69 6c 61 62 6c 65 20 6d 65 6d 6f 72 79 20 69 ailable memory i
3db0: 6e 20 6d 6f 73 74 20 63 6f 6d 70 75 74 69 6e 67 n most computing
3dc0: 20 73 79 73 74 65 6d 73 0a 6f 66 20 74 68 65 20 systems.of the
3dd0: 64 61 79 2c 20 74 68 65 20 6c 69 6d 69 74 61 74 day, the limitat
3de0: 69 6f 6e 20 6f 6e 20 73 74 72 69 6e 67 20 6c 65 ion on string le
3df0: 6e 67 74 68 20 64 69 64 20 6e 6f 74 20 73 65 65 ngth did not see
3e00: 6d 20 75 6e 72 65 61 73 6f 6e 61 62 6c 65 2e 0a m unreasonable..
3e10: 54 68 65 20 6e 65 77 20 69 6d 70 6c 65 6d 65 6e The new implemen
3e20: 74 61 74 69 6f 6e 20 73 6f 6c 76 65 73 20 74 68 tation solves th
3e30: 65 20 70 72 6f 62 6c 65 6d 20 6f 66 20 73 74 6f e problem of sto
3e40: 72 69 6e 67 20 69 6e 20 61 20 54 63 6c 20 76 61 ring in a Tcl va
3e50: 6c 75 65 0a 61 72 62 69 74 72 61 72 79 20 62 69 lue.arbitrary bi
3e60: 6e 61 72 79 20 64 61 74 61 20 75 70 20 74 6f 20 nary data up to
3e70: 32 47 62 20 69 6e 20 73 69 7a 65 2e 20 20 54 68 2Gb in size. Th
3e80: 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 e encoding of st
3e90: 72 69 6e 67 20 65 6c 65 6d 65 6e 74 73 0a 61 73 ring elements.as
3ea0: 20 5f 5f 63 68 61 72 5f 5f 20 61 72 72 61 79 20 __char__ array
3eb0: 65 6c 65 6d 65 6e 74 73 20 69 73 20 73 74 69 6c elements is stil
3ec0: 6c 20 64 69 72 65 63 74 2c 20 73 69 6d 70 6c 65 l direct, simple
3ed0: 2c 20 6f 6e 65 2d 74 6f 2d 6f 6e 65 2c 20 61 6e , one-to-one, an
3ee0: 64 20 65 76 65 72 79 0a 5f 5f 63 68 61 72 5f 5f d every.__char__
3ef0: 20 61 72 72 61 79 20 74 68 61 74 20 77 61 73 20 array that was
3f00: 61 20 76 61 6c 69 64 20 72 65 70 72 65 73 65 6e a valid represen
3f10: 74 61 74 69 6f 6e 20 6f 66 20 61 20 76 61 6c 75 tation of a valu
3f20: 65 20 69 6e 20 54 63 6c 20 37 20 72 65 6d 61 69 e in Tcl 7 remai
3f30: 6e 73 0a 76 61 6c 69 64 20 61 6e 64 20 63 6f 6e ns.valid and con
3f40: 74 69 6e 75 65 73 20 74 6f 20 72 65 70 72 65 73 tinues to repres
3f50: 65 6e 74 20 74 68 65 20 73 61 6d 65 20 76 61 6c ent the same val
3f60: 75 65 20 69 6e 20 54 63 6c 20 38 2e 30 2c 20 77 ue in Tcl 8.0, w
3f70: 68 69 63 68 20 6f 66 66 65 72 73 20 61 0a 68 69 hich offers a.hi
3f80: 67 68 20 64 65 67 72 65 65 20 6f 66 20 61 63 63 gh degree of acc
3f90: 6f 6d 6d 6f 64 61 74 69 6f 6e 20 6f 66 20 63 6c ommodation of cl
3fa0: 69 65 6e 74 20 63 6f 64 65 20 77 72 69 74 74 65 ient code writte
3fb0: 6e 20 66 6f 72 20 54 63 6c 20 37 2e 20 45 76 65 n for Tcl 7. Eve
3fc0: 72 79 0a 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 ry.collection of
3fd0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 5f 5f bytes in the __
3fe0: 63 68 61 72 5f 5f 20 61 72 72 61 79 20 72 65 70 char__ array rep
3ff0: 72 65 73 65 6e 74 73 20 61 20 76 61 6c 69 64 20 resents a valid
4000: 73 74 72 69 6e 67 2c 20 73 6f 0a 74 68 65 72 65 string, so.there
4010: 20 69 73 20 6e 6f 20 6e 65 65 64 20 74 6f 20 63 is no need to c
4020: 6f 6e 73 69 64 65 72 20 68 6f 77 20 61 6e 79 20 onsider how any
4030: 72 6f 75 74 69 6e 65 20 6f 75 67 68 74 20 74 6f routine ought to
4040: 20 72 65 73 70 6f 6e 64 20 74 6f 20 61 6e 20 69 respond to an i
4050: 6e 76 61 6c 69 64 0a 69 6e 70 75 74 2e 0a 0a 54 nvalid.input...T
4060: 68 65 20 70 75 62 6c 69 63 20 43 20 41 50 49 20 he public C API
4070: 66 6f 72 20 54 63 6c 20 38 2e 30 20 69 6e 63 6c for Tcl 8.0 incl
4080: 75 64 65 73 20 6f 6e 6c 79 20 37 20 6e 65 77 20 udes only 7 new
4090: 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 65 69 routines that ei
40a0: 74 68 65 72 0a 61 63 63 65 70 74 20 6f 72 20 72 ther.accept or r
40b0: 65 74 75 72 6e 20 65 78 70 6c 69 63 69 74 6c 79 eturn explicitly
40c0: 20 61 20 70 61 69 72 20 6f 66 20 76 61 6c 75 65 a pair of value
40d0: 73 20 6f 66 20 74 79 70 65 20 28 5f 5f 63 68 61 s of type (__cha
40e0: 72 5f 5f 20 2a 29 0a 61 6e 64 20 5f 5f 69 6e 74 r__ *).and __int
40f0: 5f 5f 20 72 65 70 72 65 73 65 6e 74 69 6e 67 20 __ representing
4100: 74 6f 67 65 74 68 65 72 20 61 20 63 6f 75 6e 74 together a count
4110: 65 64 20 73 74 72 69 6e 67 20 76 61 6c 75 65 2e ed string value.
4120: 20 41 20 73 65 63 6f 6e 64 20 73 6f 6c 75 74 69 A second soluti
4130: 6f 6e 0a 69 73 20 74 6f 20 69 6e 63 6c 75 64 65 on.is to include
4140: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 these two value
4150: 73 20 61 73 20 66 69 65 6c 64 73 20 6f 66 20 61 s as fields of a
4160: 20 6e 65 77 20 73 74 72 75 63 74 2c 20 2a 2a 54 new struct, **T
4170: 63 6c 5f 4f 62 6a 2a 2a 2c 20 61 6e 64 0a 64 65 cl_Obj**, and.de
4180: 66 69 6e 65 20 6e 65 77 20 69 6e 74 65 72 66 61 fine new interfa
4190: 63 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 ce routines that
41a0: 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 74 68 61 make use of tha
41b0: 74 20 73 74 72 75 63 74 2e 0a 54 68 65 20 2a 2a t struct..The **
41c0: 54 63 6c 5f 4f 62 6a 2a 2a 20 73 74 72 75 63 74 Tcl_Obj** struct
41d0: 20 69 6e 74 72 6f 64 75 63 65 64 20 69 6e 20 54 introduced in T
41e0: 63 6c 20 38 2e 30 20 69 6e 63 6c 75 64 65 73 20 cl 8.0 includes
41f0: 61 20 28 5f 5f 63 68 61 72 5f 5f 20 2a 29 20 0a a (__char__ *) .
4200: 66 69 65 6c 64 20 5f 62 79 74 65 73 5f 20 61 6e field _bytes_ an
4210: 64 20 61 6e 20 5f 5f 69 6e 74 5f 5f 20 66 69 65 d an __int__ fie
4220: 6c 64 20 5f 6c 65 6e 67 74 68 5f 2e 20 20 54 61 ld _length_. Ta
4230: 6b 65 6e 20 74 6f 67 65 74 68 65 72 0a 74 68 65 ken together.the
4240: 73 65 20 74 77 6f 20 66 69 65 6c 64 73 20 61 72 se two fields ar
4250: 65 20 61 20 54 63 6c 20 76 61 6c 75 65 20 72 65 e a Tcl value re
4260: 70 72 65 73 65 6e 74 65 64 20 61 73 20 61 20 63 presented as a c
4270: 6f 75 6e 74 65 64 20 73 74 72 69 6e 67 2e 20 20 ounted string.
4280: 54 68 65 0a 72 6f 75 74 69 6e 65 0a 0a 3e 09 2a The.routine..>.*
4290: 2a 54 63 6c 5f 4f 62 6a 2a 2a 20 2a 20 2a 2a 54 *Tcl_Obj** * **T
42a0: 63 6c 5f 4e 65 77 53 74 72 69 6e 67 4f 62 6a 2a cl_NewStringObj*
42b0: 2a 20 28 5f 5f 63 68 61 72 5f 5f 20 2a 20 5f 62 * (__char__ * _b
42c0: 79 74 65 73 5f 2c 20 5f 5f 69 6e 74 5f 5f 20 5f ytes_, __int__ _
42d0: 6c 65 6e 67 74 68 5f 29 3b 0a 0a 69 73 20 75 73 length_);..is us
42e0: 65 64 20 74 6f 20 63 72 65 61 74 65 20 73 75 63 ed to create suc
42f0: 68 20 61 20 73 74 72 75 63 74 20 6f 75 74 20 6f h a struct out o
4300: 66 20 74 68 65 20 70 61 69 72 20 6f 66 20 61 72 f the pair of ar
4310: 67 75 6d 65 6e 74 73 20 64 65 66 69 6e 69 6e 67 guments defining
4320: 20 61 0a 63 6f 75 6e 74 65 64 20 73 74 72 69 6e a.counted strin
4330: 67 2e 20 54 68 65 20 72 6f 75 74 69 6e 65 0a 0a g. The routine..
4340: 3e 09 5f 5f 63 68 61 72 5f 5f 20 2a 20 2a 2a 54 >.__char__ * **T
4350: 63 6c 5f 47 65 74 53 74 72 69 6e 67 46 72 6f 6d cl_GetStringFrom
4360: 4f 62 6a 2a 2a 20 28 20 2a 2a 54 63 6c 5f 4f 62 Obj** ( **Tcl_Ob
4370: 6a 2a 2a 20 2a 20 5f 6f 62 6a 50 74 72 5f 2c 20 j** * _objPtr_,
4380: 5f 5f 69 6e 74 5f 5f 20 2a 20 5f 6c 65 6e 67 74 __int__ * _lengt
4390: 68 50 74 72 5f 20 29 3b 0a 0a 70 72 6f 76 69 64 hPtr_ );..provid
43a0: 65 73 20 74 68 65 20 72 65 76 65 72 73 65 20 66 es the reverse f
43b0: 75 6e 63 74 69 6f 6e 61 6c 69 74 79 2c 20 72 65 unctionality, re
43c0: 74 75 72 6e 69 6e 67 20 61 20 28 5f 5f 63 68 61 turning a (__cha
43d0: 72 5f 5f 20 2a 29 20 76 61 6c 75 65 20 61 6e 64 r__ *) value and
43e0: 0a 77 72 69 74 69 6e 67 20 74 6f 20 2a 5f 6c 65 .writing to *_le
43f0: 6e 67 74 68 50 74 72 5f 20 61 6e 20 5f 5f 69 6e ngthPtr_ an __in
4400: 74 5f 5f 20 76 61 6c 75 65 20 6d 61 6b 69 6e 67 t__ value making
4410: 20 75 70 20 74 68 65 20 63 6f 75 6e 74 65 64 20 up the counted
4420: 73 74 72 69 6e 67 0a 72 65 74 72 69 65 76 65 64 string.retrieved
4430: 20 66 72 6f 6d 20 5f 6f 62 6a 50 74 72 5f 2e 20 from _objPtr_.
4440: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 These routines s
4450: 75 70 70 6f 72 74 20 74 68 65 20 74 72 61 6e 73 upport the trans
4460: 6d 69 73 73 69 6f 6e 20 6f 66 0a 74 68 65 20 63 mission of.the c
4470: 6f 6d 70 6c 65 74 65 20 62 69 6e 61 72 79 2d 73 omplete binary-s
4480: 61 66 65 20 73 65 74 20 6f 66 20 54 63 6c 20 38 afe set of Tcl 8
4490: 2e 30 20 76 61 6c 75 65 73 2e 0a 0a 49 74 20 69 .0 values...It i
44a0: 73 20 6d 6f 73 74 6c 79 20 6f 75 74 73 69 64 65 s mostly outside
44b0: 20 74 68 65 20 73 63 6f 70 65 20 6f 66 20 74 68 the scope of th
44c0: 69 73 20 64 6f 63 75 6d 65 6e 74 2c 20 62 75 74 is document, but
44d0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c additional fiel
44e0: 64 73 0a 6f 66 20 74 68 65 20 2a 2a 54 63 6c 5f ds.of the **Tcl_
44f0: 4f 62 6a 2a 2a 20 73 74 72 75 63 74 20 65 6e 61 Obj** struct ena
4500: 62 6c 65 20 76 61 6c 75 65 20 73 68 61 72 69 6e ble value sharin
4510: 67 2c 20 61 6e 64 20 63 61 63 68 69 6e 67 20 6f g, and caching o
4520: 66 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 74 6f f conversions.to
4530: 20 6f 74 68 65 72 20 76 61 6c 75 65 20 72 65 70 other value rep
4540: 72 65 73 65 6e 74 61 74 69 6f 6e 73 2e 20 54 68 resentations. Th
4550: 65 73 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 ese other functi
4560: 6f 6e 73 20 73 6f 6c 76 65 20 6d 61 6e 79 20 6f ons solve many o
4570: 66 20 74 68 65 0a 64 65 66 65 63 74 73 20 6f 66 f the.defects of
4580: 20 74 68 65 20 54 63 6c 20 37 20 76 61 6c 75 65 the Tcl 7 value
4590: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
45a0: 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 63 other than the c
45b0: 6f 6e 73 74 72 61 69 6e 65 64 0a 75 6e 69 76 65 onstrained.unive
45c0: 72 73 65 20 6f 66 20 73 75 70 70 6f 72 74 65 64 rse of supported
45d0: 20 76 61 6c 75 65 73 20 69 74 73 65 6c 66 2e 20 values itself.
45e0: 4e 6f 74 61 62 6c 79 20 74 68 65 73 65 20 6f 74 Notably these ot
45f0: 68 65 72 20 66 65 61 74 75 72 65 73 20 65 6e 61 her features ena
4600: 62 6c 65 0a 73 75 62 73 74 61 6e 74 69 61 6c 20 ble.substantial
4610: 70 65 72 66 6f 72 6d 61 6e 63 65 20 67 61 69 6e performance gain
4620: 73 2e 20 4d 75 63 68 20 6f 66 20 74 68 65 20 70 s. Much of the p
4630: 75 62 6c 69 73 68 65 64 20 61 64 76 69 63 65 20 ublished advice
4640: 74 6f 20 61 64 6f 70 74 0a 69 6e 74 65 72 66 61 to adopt.interfa
4650: 63 65 73 20 75 73 69 6e 67 20 74 68 65 20 2a 2a ces using the **
4660: 54 63 6c 5f 4f 62 6a 2a 2a 20 73 74 72 75 63 74 Tcl_Obj** struct
4670: 20 63 65 6e 74 65 72 73 20 6f 6e 20 74 68 65 20 centers on the
4680: 70 65 72 66 6f 72 6d 61 6e 63 65 20 72 65 77 61 performance rewa
4690: 72 64 73 0a 72 61 74 68 65 72 20 74 68 61 6e 20 rds.rather than
46a0: 74 68 65 20 65 78 70 61 6e 64 65 64 20 63 61 70 the expanded cap
46b0: 61 62 69 6c 69 74 79 20 74 6f 20 69 6e 63 6c 75 ability to inclu
46c0: 64 65 20 2a 2a 4e 55 4c 2a 2a 20 62 79 74 65 73 de **NUL** bytes
46d0: 2e 0a 0a 54 68 65 20 73 74 6f 72 61 67 65 20 6f ...The storage o
46e0: 66 20 61 20 5f 5f 63 68 61 72 5f 5f 20 61 72 72 f a __char__ arr
46f0: 61 79 20 62 79 20 61 20 2a 2a 54 63 6c 5f 4f 62 ay by a **Tcl_Ob
4700: 6a 2a 2a 20 68 61 73 20 73 6f 6d 65 20 70 61 72 j** has some par
4710: 61 6c 6c 65 6c 73 20 77 69 74 68 0a 74 68 65 20 allels with.the
4720: 73 74 6f 72 61 67 65 20 6f 66 20 61 20 5f 5f 63 storage of a __c
4730: 68 61 72 5f 5f 20 61 72 72 61 79 20 61 73 20 74 har__ array as t
4740: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 61 20 63 he result of a c
4750: 6f 6d 6d 61 6e 64 20 65 76 61 6c 75 61 74 65 64 ommand evaluated
4760: 0a 69 6e 20 61 20 2a 2a 54 63 6c 5f 49 6e 74 65 .in a **Tcl_Inte
4770: 72 70 2a 2a 2e 20 20 48 6f 77 65 76 65 72 2c 20 rp**. However,
4780: 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
4790: 6e 61 6c 69 74 79 20 6f 66 20 2a 2a 54 63 6c 5f nality of **Tcl_
47a0: 53 65 74 52 65 73 75 6c 74 2a 2a 0a 77 61 73 20 SetResult**.was
47b0: 6e 6f 74 20 6d 61 64 65 20 61 76 61 69 6c 61 62 not made availab
47c0: 6c 65 2e 20 54 6f 20 64 6f 20 73 6f 2c 20 73 6f le. To do so, so
47d0: 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 61 20 5f mething like a _
47e0: 66 72 65 65 50 72 6f 63 5f 20 66 69 65 6c 64 0a freeProc_ field.
47f0: 77 6f 75 6c 64 20 6e 65 65 64 20 74 6f 20 62 65 would need to be
4800: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 included in the
4810: 20 2a 2a 54 63 6c 5f 4f 62 6a 2a 2a 20 73 74 72 **Tcl_Obj** str
4820: 75 63 74 2c 20 61 6e 64 20 63 6f 6e 63 65 72 6e uct, and concern
4830: 73 20 61 62 6f 75 74 0a 65 78 63 65 73 73 69 76 s about.excessiv
4840: 65 20 6d 65 6d 6f 72 79 20 72 65 71 75 69 72 65 e memory require
4850: 6d 65 6e 74 73 20 74 6f 20 73 74 6f 72 65 20 65 ments to store e
4860: 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 54 63 very value in Tc
4870: 6c 20 72 75 6c 65 64 20 74 68 65 20 64 61 79 2e l ruled the day.
4880: 0a 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 .As a consequenc
4890: 65 2c 20 69 74 20 69 73 20 61 6e 20 69 6d 70 6c e, it is an impl
48a0: 69 63 69 74 20 72 65 71 75 69 72 65 6d 65 6e 74 icit requirement
48b0: 20 74 68 61 74 20 5f 6f 62 6a 50 74 72 5f 2d 3e that _objPtr_->
48c0: 5f 62 79 74 65 73 5f 0a 6e 6f 72 6d 61 6c 6c 79 _bytes_.normally
48d0: 20 70 6f 69 6e 74 73 20 74 6f 20 6d 65 6d 6f 72 points to memor
48e0: 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 2a y allocated by *
48f0: 2a 63 6b 61 6c 6c 6f 63 2a 2a 20 61 6e 64 20 77 *ckalloc** and w
4900: 68 65 6e 20 73 68 61 72 69 6e 67 0a 64 65 6d 61 hen sharing.dema
4910: 6e 64 73 20 61 72 65 20 61 6c 6c 20 72 65 6c 65 nds are all rele
4920: 61 73 65 64 20 69 74 20 77 69 6c 6c 20 62 65 20 ased it will be
4930: 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 freed by a call
4940: 74 6f 20 2a 2a 63 6b 66 72 65 65 2a 2a 2e 0a 54 to **ckfree**..T
4950: 68 65 20 72 6f 75 74 69 6e 65 20 2a 2a 54 63 6c he routine **Tcl
4960: 5f 4e 65 77 53 74 72 69 6e 67 4f 62 6a 2a 2a 20 _NewStringObj**
4970: 6d 61 6b 65 73 20 73 75 63 68 20 61 6e 20 61 6c makes such an al
4980: 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 20 63 6f 70 location and cop
4990: 69 65 73 0a 74 68 65 20 5f 5f 63 68 61 72 5f 5f ies.the __char__
49a0: 20 61 72 72 61 79 20 69 6e 20 69 74 73 20 5f 62 array in its _b
49b0: 79 74 65 73 5f 20 61 72 67 75 6d 65 6e 74 20 69 ytes_ argument i
49c0: 6e 74 6f 20 69 74 2e 20 49 6e 20 63 6f 6e 74 72 nto it. In contr
49d0: 61 73 74 2c 0a 74 68 65 20 28 5f 5f 63 68 61 72 ast,.the (__char
49e0: 5f 5f 20 2a 29 20 76 61 6c 75 65 20 72 65 74 75 __ *) value retu
49f0: 72 6e 65 64 20 62 79 20 2a 2a 54 63 6c 5f 47 65 rned by **Tcl_Ge
4a00: 74 53 74 72 69 6e 67 46 72 6f 6d 4f 62 6a 2a 2a tStringFromObj**
4a10: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 74 6f is a pointer.to
4a20: 20 74 68 65 20 73 61 6d 65 20 5f 5f 63 68 61 72 the same __char
4a30: 5f 5f 20 61 72 72 61 79 20 74 68 61 74 20 69 73 __ array that is
4a40: 20 73 74 6f 72 65 64 20 62 79 20 5f 6f 62 6a 50 stored by _objP
4a50: 74 72 5f 2e 20 54 68 65 20 63 61 6c 6c 65 72 20 tr_. The caller
4a60: 6f 66 0a 2a 2a 54 63 6c 5f 47 65 74 53 74 72 69 of.**Tcl_GetStri
4a70: 6e 67 46 72 6f 6d 4f 62 6a 2a 2a 20 63 61 6e 20 ngFromObj** can
4a80: 73 75 73 74 61 69 6e 20 74 68 65 20 76 61 6c 69 sustain the vali
4a90: 64 69 74 79 20 6f 66 20 74 68 61 74 20 6d 65 6d dity of that mem
4aa0: 6f 72 79 20 62 79 0a 63 6c 61 69 6d 69 6e 67 20 ory by.claiming
4ab0: 61 20 73 68 61 72 65 20 6f 6e 20 5f 6f 62 6a 50 a share on _objP
4ac0: 74 72 5f 20 77 69 74 68 20 61 20 63 61 6c 6c 20 tr_ with a call
4ad0: 74 6f 20 2a 2a 54 63 6c 5f 49 6e 63 72 52 65 66 to **Tcl_IncrRef
4ae0: 43 6f 75 6e 74 2a 2a 20 61 6e 64 0a 74 68 65 6e Count** and.then
4af0: 20 6c 61 74 65 72 20 72 65 6c 65 61 73 69 6e 67 later releasing
4b00: 20 74 68 61 74 20 63 6c 61 69 6d 20 77 69 74 68 that claim with
4b10: 20 61 20 63 61 6c 6c 20 74 6f 20 2a 2a 54 63 6c a call to **Tcl
4b20: 5f 44 65 63 72 52 65 66 43 6f 75 6e 74 2a 2a 2e _DecrRefCount**.
4b30: 0a 4f 6e 65 20 63 6f 6d 70 6c 65 74 65 20 63 6f .One complete co
4b40: 70 79 20 6f 66 20 74 68 65 20 5f 5f 63 68 61 72 py of the __char
4b50: 5f 5f 20 61 72 72 61 79 20 63 6f 6e 74 65 6e 74 __ array content
4b60: 73 20 63 61 6e 6e 6f 74 20 62 65 20 61 76 6f 69 s cannot be avoi
4b70: 64 65 64 20 62 79 20 74 68 69 73 0a 76 61 6c 75 ded by this.valu
4b80: 65 20 6d 6f 64 65 6c 2c 20 62 75 74 20 76 61 6c e model, but val
4b90: 75 65 20 73 68 61 72 69 6e 67 20 70 65 72 6d 69 ue sharing permi
4ba0: 74 73 20 6d 6f 73 74 20 73 75 62 73 65 71 75 65 ts most subseque
4bb0: 6e 74 20 63 6f 70 79 69 6e 67 20 74 6f 20 62 65 nt copying to be
4bc0: 20 61 76 6f 69 64 65 64 2e 0a 54 68 69 73 20 64 avoided..This d
4bd0: 65 73 69 67 6e 20 61 6c 73 6f 20 69 6d 70 6f 73 esign also impos
4be0: 65 73 20 63 6f 6e 73 65 71 75 65 6e 74 69 61 6c es consequential
4bf0: 20 63 6f 73 74 73 20 6f 6e 20 74 68 65 20 22 43 costs on the "C
4c00: 6f 70 79 20 6f 6e 20 57 72 69 74 65 22 20 73 74 opy on Write" st
4c10: 72 61 74 65 67 79 0a 77 68 65 6e 20 6f 76 65 72 rategy.when over
4c20: 2d 77 72 69 74 69 6e 67 20 61 20 2a 2a 54 63 6c -writing a **Tcl
4c30: 5f 4f 62 6a 2a 2a 20 73 74 72 75 63 74 2e 20 4e _Obj** struct. N
4c40: 6f 20 61 6c 74 65 72 6e 61 74 69 76 65 20 74 6f o alternative to
4c50: 20 63 6f 6d 70 6c 65 74 65 0a 61 6c 6c 6f 63 61 complete.alloca
4c60: 74 69 6f 6e 20 61 6e 64 20 63 6f 70 79 20 69 73 tion and copy is
4c70: 20 61 76 61 69 6c 61 62 6c 65 2c 20 77 69 74 68 available, with
4c80: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 63 6f 6e performance con
4c90: 73 65 71 75 65 6e 63 65 73 20 66 6f 72 0a 6c 61 sequences for.la
4ca0: 72 67 65 20 76 61 6c 75 65 73 20 74 68 61 74 20 rge values that
4cb0: 68 61 76 65 20 76 69 73 69 62 6c 65 20 69 6d 70 have visible imp
4cc0: 61 63 74 20 6f 6e 20 73 63 72 69 70 74 73 2e 0a act on scripts..
4cd0: 0a 57 69 74 68 20 61 20 2a 2a 54 63 6c 5f 4f 62 .With a **Tcl_Ob
4ce0: 6a 2a 2a 20 73 74 72 75 63 74 20 64 65 66 69 6e j** struct defin
4cf0: 65 64 20 61 73 20 61 20 63 6f 6e 74 61 69 6e 65 ed as a containe
4d00: 72 20 66 6f 72 20 61 6e 79 20 54 63 6c 20 38 2e r for any Tcl 8.
4d10: 30 20 76 61 6c 75 65 2c 0a 61 20 6e 65 77 20 73 0 value,.a new s
4d20: 69 67 6e 61 74 75 72 65 20 66 6f 72 20 63 6f 6d ignature for com
4d30: 6d 61 6e 64 20 70 72 6f 63 65 64 75 72 65 73 20 mand procedures
4d40: 77 61 73 20 64 65 66 69 6e 65 64 2c 0a 0a 3e 09 was defined,..>.
4d50: 2a 2a 69 6e 74 2a 2a 20 2a 2a 54 63 6c 5f 4f 62 **int** **Tcl_Ob
4d60: 6a 43 6d 64 50 72 6f 63 2a 2a 20 28 20 2a 2a 43 jCmdProc** ( **C
4d70: 6c 69 65 6e 74 44 61 74 61 2a 2a 2c 20 5f 69 6e lientData**, _in
4d80: 74 65 72 70 5f 2c 20 2a 2a 69 6e 74 2a 2a 20 5f terp_, **int** _
4d90: 6f 62 6a 63 5f 2c 20 2a 2a 54 63 6c 5f 4f 62 6a objc_, **Tcl_Obj
4da0: 2a 2a 20 2a 20 63 6f 6e 73 74 20 5f 6f 62 6a 76 ** * const _objv
4db0: 5f 5b 5d 29 3b 0a 0a 61 6e 64 20 61 20 6e 65 77 _[]);..and a new
4dc0: 20 70 75 62 6c 69 63 20 72 6f 75 74 69 6e 65 20 public routine
4dd0: 2a 2a 54 63 6c 5f 43 72 65 61 74 65 4f 62 6a 43 **Tcl_CreateObjC
4de0: 6f 6d 6d 61 6e 64 2a 2a 20 74 6f 20 63 72 65 61 ommand** to crea
4df0: 74 65 20 63 6f 6d 6d 61 6e 64 73 20 0a 69 6d 70 te commands .imp
4e00: 6c 65 6d 65 6e 74 65 64 20 75 73 69 6e 67 20 74 lemented using t
4e10: 68 65 20 6e 65 77 20 63 6f 6d 6d 61 6e 64 20 70 he new command p
4e20: 72 6f 63 65 64 75 72 65 20 73 69 67 6e 61 74 75 rocedure signatu
4e30: 72 65 2e 20 43 6f 6d 6d 61 6e 64 73 20 75 73 69 re. Commands usi
4e40: 6e 67 20 74 68 65 0a 6e 65 77 20 73 69 67 6e 61 ng the.new signa
4e50: 74 75 72 65 20 68 61 76 65 20 74 68 65 20 61 62 ture have the ab
4e60: 69 6c 69 74 79 20 74 6f 20 72 65 63 65 69 76 65 ility to receive
4e70: 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 61 72 the complete ar
4e80: 67 75 6d 65 6e 74 20 73 65 74 20 6f 66 0a 54 63 gument set of.Tc
4e90: 6c 20 38 2e 30 20 61 73 20 61 72 67 75 6d 65 6e l 8.0 as argumen
4ea0: 74 73 2e 20 20 41 6e 20 61 72 62 69 74 72 61 72 ts. An arbitrar
4eb0: 79 20 54 63 6c 20 38 2e 30 20 76 61 6c 75 65 20 y Tcl 8.0 value
4ec0: 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
4ed0: 0a 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f .using a call to
4ee0: 20 2a 2a 54 63 6c 5f 53 65 74 4f 62 6a 52 65 73 **Tcl_SetObjRes
4ef0: 75 6c 74 2a 2a 2e 20 20 4f 6e 65 20 6f 66 20 74 ult**. One of t
4f00: 68 65 73 65 20 63 6f 6d 6d 61 6e 64 73 20 63 61 hese commands ca
4f10: 6e 20 62 65 0a 65 76 61 6c 75 61 74 65 64 20 62 n be.evaluated b
4f20: 79 20 75 73 65 20 6f 66 20 74 68 65 20 6f 6c 64 y use of the old
4f30: 20 72 6f 75 74 69 6e 65 20 2a 2a 54 63 6c 5f 45 routine **Tcl_E
4f40: 76 61 6c 2a 2a 20 6f 72 20 74 68 65 20 6e 65 77 val** or the new
4f50: 20 72 6f 75 74 69 6e 65 0a 2a 2a 54 63 6c 5f 45 routine.**Tcl_E
4f60: 76 61 6c 4f 62 6a 2a 2a 20 77 68 65 6e 20 74 68 valObj** when th
4f70: 65 20 73 63 72 69 70 74 20 74 6f 20 62 65 20 65 e script to be e
4f80: 76 61 6c 75 61 74 65 64 20 69 74 73 65 6c 66 20 valuated itself
4f90: 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 0a 74 68 might include.th
4fa0: 65 20 5f 5f 4e 55 4c 5f 5f 20 62 79 74 65 2e 20 e __NUL__ byte.
4fb0: 54 68 65 20 63 61 6c 6c 65 72 20 74 68 65 6e 20 The caller then
4fc0: 72 65 74 72 69 65 76 65 73 20 74 68 65 20 72 65 retrieves the re
4fd0: 73 75 6c 74 20 6f 66 20 74 68 65 20 65 76 61 6c sult of the eval
4fe0: 75 61 74 65 64 0a 63 6f 6d 6d 61 6e 64 20 77 69 uated.command wi
4ff0: 74 68 20 61 20 63 61 6c 6c 20 74 6f 20 2a 2a 54 th a call to **T
5000: 63 6c 5f 47 65 74 4f 62 6a 52 65 73 75 6c 74 2a cl_GetObjResult*
5010: 2a 2e 20 20 41 20 6e 65 77 20 72 6f 75 74 69 6e *. A new routin
5020: 65 0a 2a 2a 54 63 6c 5f 47 65 74 53 74 72 69 6e e.**Tcl_GetStrin
5030: 67 52 65 73 75 6c 74 2a 2a 20 61 6c 6c 6f 77 73 gResult** allows
5040: 20 74 68 65 20 69 6e 74 65 72 70 72 65 74 65 72 the interpreter
5050: 20 72 65 73 75 6c 74 20 74 6f 20 62 65 20 72 65 result to be re
5060: 74 72 69 65 76 65 64 0a 61 73 20 61 20 2a 2a 4e trieved.as a **N
5070: 55 4c 2a 2a 2d 74 65 72 6d 69 6e 61 74 65 64 20 UL**-terminated
5080: 73 74 72 69 6e 67 2c 20 77 69 74 68 20 74 68 65 string, with the
5090: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 74 corresponding t
50a0: 72 75 6e 63 61 74 69 6f 6e 20 61 74 0a 61 6e 79 runcation at.any
50b0: 20 2a 2a 4e 55 4c 2a 2a 20 62 79 74 65 20 74 68 **NUL** byte th
50c0: 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 20 69 at might be in i
50d0: 74 2e 20 54 68 69 73 20 69 73 20 6e 6f 74 20 61 t. This is not a
50e0: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 72 6f 75 recommended rou
50f0: 74 69 6e 65 2c 0a 62 75 74 20 69 74 20 69 73 20 tine,.but it is
5100: 61 6e 20 69 6d 70 72 6f 76 65 6d 65 6e 74 20 6f an improvement o
5110: 76 65 72 20 64 69 72 65 63 74 20 61 63 63 65 73 ver direct acces
5120: 73 20 74 6f 20 74 68 65 20 5f 69 6e 74 65 72 70 s to the _interp
5130: 5f 2d 3e 5f 72 65 73 75 6c 74 5f 0a 66 69 65 6c _->_result_.fiel
5140: 64 2c 20 77 68 69 63 68 20 54 63 6c 20 38 2e 30 d, which Tcl 8.0
5150: 20 64 65 63 6c 61 72 65 73 20 64 65 70 72 65 63 declares deprec
5160: 61 74 65 64 2e 20 20 41 6c 6c 20 54 63 6c 20 6f ated. All Tcl o
5170: 70 65 72 61 74 69 6f 6e 73 20 74 68 61 74 20 6e perations that n
5180: 65 65 64 0a 74 6f 20 73 75 70 70 6f 72 74 20 74 eed.to support t
5190: 68 65 20 63 6f 6d 70 6c 65 74 65 20 6e 65 77 20 he complete new
51a0: 54 63 6c 20 76 61 6c 75 65 20 73 65 74 20 68 61 Tcl value set ha
51b0: 64 20 74 6f 20 62 65 20 72 65 76 69 73 65 64 20 d to be revised
51c0: 74 6f 20 6d 61 6b 65 20 75 73 65 0a 6f 66 20 6e to make use.of n
51d0: 65 77 20 66 61 63 69 6c 69 74 69 65 73 20 61 6e ew facilities an
51e0: 64 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 0a 43 d interfaces...C
51f0: 6f 6e 74 69 6e 75 69 6e 67 20 65 61 72 6c 69 65 ontinuing earlie
5200: 72 20 69 6c 6c 75 73 74 72 61 74 69 6f 6e 73 2c r illustrations,
5210: 20 77 65 20 63 61 6e 20 73 65 65 20 74 68 61 74 we can see that
5220: 20 74 68 65 20 2a 2a 73 74 72 69 6e 67 2a 2a 20 the **string**
5230: 63 6f 6d 6d 61 6e 64 0a 77 61 73 20 61 64 61 70 command.was adap
5240: 74 65 64 20 69 6e 20 54 63 6c 20 38 2e 30 0a 0a ted in Tcl 8.0..
5250: 3c 70 72 65 3e 0a 60 60 60 0a 09 25 20 73 74 72 <pre>.```..% str
5260: 69 6e 67 20 6c 65 6e 67 74 68 20 3c 5c 78 30 30 ing length <\x00
5270: 3e 0a 09 33 0a 60 60 60 0a 3c 2f 70 72 65 3e 0a >..3.```.</pre>.
5280: 0a 4c 69 6b 65 77 69 73 65 20 74 68 65 20 2a 2a .Likewise the **
5290: 70 75 74 73 2a 2a 20 61 6e 64 20 2a 2a 72 65 61 puts** and **rea
52a0: 64 2a 2a 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 d** commands are
52b0: 20 66 75 6c 6c 79 20 62 69 6e 61 72 79 20 73 61 fully binary sa
52c0: 66 65 2c 20 73 6f 0a 74 68 61 74 20 0a 0a 3c 70 fe, so.that ..<p
52d0: 72 65 3e 0a 60 60 60 0a 09 66 63 6f 6e 66 69 67 re>.```..fconfig
52e0: 75 72 65 20 24 69 6e 20 2d 74 72 61 6e 73 6c 61 ure $in -transla
52f0: 74 69 6f 6e 20 62 69 6e 61 72 79 0a 09 66 63 6f tion binary..fco
5300: 6e 66 69 67 75 72 65 20 24 6f 75 74 20 2d 74 72 nfigure $out -tr
5310: 61 6e 73 6c 61 74 69 6f 6e 20 62 69 6e 61 72 79 anslation binary
5320: 0a 09 70 75 74 73 20 2d 6e 6f 6e 65 77 6c 69 6e ..puts -nonewlin
5330: 65 20 24 6f 75 74 20 5b 72 65 61 64 20 24 69 6e e $out [read $in
5340: 5d 0a 60 60 60 0a 3c 2f 70 72 65 3e 0a 0a 6e 6f ].```.</pre>..no
5350: 77 20 66 61 69 74 68 66 75 6c 6c 79 20 63 6f 70 w faithfully cop
5360: 69 65 73 20 61 6c 6c 20 62 79 74 65 73 20 66 72 ies all bytes fr
5370: 6f 6d 20 6f 6e 65 20 63 68 61 6e 6e 65 6c 20 74 om one channel t
5380: 6f 20 61 6e 6f 74 68 65 72 2e 20 54 63 6c 20 38 o another. Tcl 8
5390: 2e 30 0a 61 6c 73 6f 20 69 6e 74 72 6f 64 75 63 .0.also introduc
53a0: 65 73 20 6e 65 77 20 63 6f 6d 6d 61 6e 64 73 20 es new commands
53b0: 2a 2a 62 69 6e 61 72 79 20 66 6f 72 6d 61 74 2a **binary format*
53c0: 2a 20 61 6e 64 20 2a 2a 62 69 6e 61 72 79 20 73 * and **binary s
53d0: 63 61 6e 2a 2a 0a 74 68 61 74 20 54 63 6c 20 70 can**.that Tcl p
53e0: 72 6f 67 72 61 6d 73 20 63 61 6e 20 75 73 65 20 rograms can use
53f0: 74 6f 20 70 72 6f 63 65 73 73 20 62 69 6e 61 72 to process binar
5400: 79 20 76 61 6c 75 65 73 2e 20 49 6e 20 54 63 6c y values. In Tcl
5410: 20 38 2e 30 2c 20 74 68 65 73 65 0a 63 6f 6d 6d 8.0, these.comm
5420: 61 6e 64 73 20 6f 70 65 72 61 74 65 20 64 69 72 ands operate dir
5430: 65 63 74 6c 79 20 6f 6e 20 74 68 65 20 63 6f 75 ectly on the cou
5440: 6e 74 65 64 20 73 74 72 69 6e 67 20 69 6e 20 5f nted string in _
5450: 6f 62 6a 50 74 72 5f 2d 3e 5f 62 79 74 65 73 5f objPtr_->_bytes_
5460: 2e 0a 0a 41 20 64 65 70 6c 6f 79 65 64 20 63 6f ...A deployed co
5470: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 65 78 74 65 llection of exte
5480: 6e 73 69 6f 6e 20 63 6f 6d 6d 61 6e 64 73 20 77 nsion commands w
5490: 72 69 74 74 65 6e 20 66 6f 72 20 54 63 6c 20 37 ritten for Tcl 7
54a0: 20 63 6f 75 6c 64 0a 73 74 69 6c 6c 20 62 65 20 could.still be
54b0: 75 73 65 64 20 62 79 20 54 63 6c 20 38 2e 30 2e used by Tcl 8.0.
54c0: 20 20 53 69 6e 63 65 20 74 68 65 73 65 20 63 6f Since these co
54d0: 6d 6d 61 6e 64 73 20 77 65 72 65 20 69 6d 70 6c mmands were impl
54e0: 65 6d 65 6e 74 65 64 20 62 79 0a 63 6f 6d 6d 61 emented by.comma
54f0: 6e 64 20 70 72 6f 63 65 64 75 72 65 73 20 75 73 nd procedures us
5500: 69 6e 67 20 74 68 65 20 2a 2a 54 63 6c 5f 43 6d ing the **Tcl_Cm
5510: 64 50 72 6f 63 2a 2a 20 73 69 67 6e 61 74 75 72 dProc** signatur
5520: 65 2c 20 74 68 65 79 20 63 6f 75 6c 64 0a 6f 6e e, they could.on
5530: 6c 79 20 61 63 63 65 70 74 20 2a 2a 4e 55 4c 2a ly accept **NUL*
5540: 2a 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 *-terminated str
5550: 69 6e 67 73 20 61 73 20 61 72 67 75 6d 65 6e 74 ings as argument
5560: 73 2e 20 41 74 74 65 6d 70 74 73 20 74 6f 20 70 s. Attempts to p
5570: 61 73 73 0a 61 6e 79 20 61 72 67 75 6d 65 6e 74 ass.any argument
5580: 20 76 61 6c 75 65 20 74 6f 20 74 68 65 6d 20 74 value to them t
5590: 68 61 74 20 69 6e 63 6c 75 64 65 64 20 61 20 2a hat included a *
55a0: 2a 4e 55 4c 2a 2a 20 62 79 74 65 20 77 6f 75 6c *NUL** byte woul
55b0: 64 20 6f 6e 6c 79 0a 70 61 73 73 20 74 68 65 20 d only.pass the
55c0: 74 72 75 6e 63 61 74 65 64 20 76 61 6c 75 65 2e truncated value.
55d0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 69 73 20 Note that this
55e0: 72 65 6d 61 69 6e 73 20 77 69 74 68 69 6e 20 74 remains within t
55f0: 68 65 20 76 65 72 79 0a 66 72 65 65 20 72 65 71 he very.free req
5600: 75 69 72 65 6d 65 6e 74 73 20 6f 66 20 61 6e 20 uirements of an
5610: 61 72 62 69 74 72 61 72 79 20 54 63 6c 20 63 6f arbitrary Tcl co
5620: 6d 6d 61 6e 64 2e 20 45 61 63 68 20 63 6f 6d 6d mmand. Each comm
5630: 61 6e 64 20 69 73 20 66 72 65 65 20 74 6f 0a 69 and is free to.i
5640: 6e 74 65 72 70 72 65 74 20 69 74 73 20 61 72 67 nterpret its arg
5650: 75 6d 65 6e 74 73 20 61 73 20 69 74 20 63 68 6f uments as it cho
5660: 6f 73 65 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 oses, including
5670: 74 68 65 20 63 68 6f 69 63 65 20 74 6f 0a 74 72 the choice to.tr
5680: 75 6e 63 61 74 65 20 74 68 65 6d 20 61 74 20 74 uncate them at t
5690: 68 65 20 66 69 72 73 74 20 2a 2a 4e 55 4c 2a 2a he first **NUL**
56a0: 2e 20 20 41 20 54 63 6c 20 37 20 63 6f 6d 6d 61 . A Tcl 7 comma
56b0: 6e 64 20 77 6f 75 6c 64 20 70 72 6f 64 75 63 65 nd would produce
56c0: 20 61 0a 72 65 73 75 6c 74 20 77 69 74 68 69 6e a.result within
56d0: 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 65 64 the constrained
56e0: 20 76 61 6c 75 65 20 73 65 74 2c 20 62 75 74 20 value set, but
56f0: 74 68 61 74 20 69 73 20 61 63 63 65 70 74 61 62 that is acceptab
5700: 6c 65 2e 0a 49 66 20 74 68 65 20 63 6f 6d 6d 61 le..If the comma
5710: 6e 64 20 72 65 63 6f 72 64 73 20 74 68 61 74 20 nd records that
5720: 72 65 73 75 6c 74 20 76 69 61 20 64 69 72 65 63 result via direc
5730: 74 20 77 72 69 74 65 20 74 6f 20 5f 69 6e 74 65 t write to _inte
5740: 72 70 5f 2d 3e 5f 72 65 73 75 6c 74 5f 0a 74 68 rp_->_result_.th
5750: 61 74 20 69 73 20 64 65 70 72 65 63 61 74 65 64 at is deprecated
5760: 20 61 6e 64 20 66 6f 72 6d 61 6c 6c 79 20 75 6e and formally un
5770: 73 75 70 70 6f 72 74 65 64 2c 20 62 75 74 20 69 supported, but i
5780: 6e 20 70 72 61 63 74 69 63 65 20 74 6f 6c 65 72 n practice toler
5790: 61 74 65 64 0a 61 6e 64 20 66 75 6e 63 74 69 6f ated.and functio
57a0: 6e 61 6c 2e 20 53 75 63 68 20 61 6e 20 61 70 70 nal. Such an app
57b0: 72 6f 61 63 68 20 61 6c 6c 6f 77 65 64 20 66 6f roach allowed fo
57c0: 72 20 61 20 67 65 6e 74 6c 65 2c 20 65 76 65 6e r a gentle, even
57d0: 20 6c 61 7a 79 2c 20 61 70 70 72 6f 61 63 68 0a lazy, approach.
57e0: 74 6f 20 6d 69 67 72 61 74 69 6f 6e 20 74 6f 20 to migration to
57f0: 6e 65 77 20 63 61 70 61 62 69 6c 69 74 69 65 73 new capabilities
5800: 2e 20 20 41 6c 6c 20 6f 66 20 74 68 65 20 70 75 . All of the pu
5810: 62 6c 69 63 20 54 63 6c 20 37 20 72 6f 75 74 69 blic Tcl 7 routi
5820: 6e 65 73 20 74 68 61 74 0a 61 63 63 65 70 74 20 nes that.accept
5830: 6f 72 20 72 65 74 75 72 6e 20 2a 2a 4e 55 4c 2a or return **NUL*
5840: 2a 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 *-terminated str
5850: 69 6e 67 73 20 6e 6f 74 65 64 20 69 6e 20 74 68 ings noted in th
5860: 65 20 65 61 72 6c 69 65 72 20 73 65 63 74 69 6f e earlier sectio
5870: 6e 0a 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 n.continue to be
5880: 20 73 75 70 70 6f 72 74 65 64 20 70 75 62 6c 69 supported publi
5890: 63 20 72 6f 75 74 69 6e 65 73 20 69 6e 20 54 63 c routines in Tc
58a0: 6c 20 38 2e 30 2c 20 64 6f 69 6e 67 20 77 68 61 l 8.0, doing wha
58b0: 74 20 74 68 65 79 20 64 6f 2c 0a 77 69 74 68 20 t they do,.with
58c0: 61 6c 6c 20 74 68 65 20 69 6d 70 6c 69 63 69 74 all the implicit
58d0: 20 6c 69 6d 69 74 61 74 69 6f 6e 73 2e 20 20 54 limitations. T
58e0: 68 65 20 6d 6f 64 65 6c 20 69 6e 20 70 6c 61 63 he model in plac
58f0: 65 20 77 61 73 20 63 6c 65 61 72 6c 79 20 61 6e e was clearly an
5900: 0a 65 78 70 65 63 74 61 74 69 6f 6e 20 74 68 61 .expectation tha
5910: 74 20 61 6c 6c 20 63 6f 6d 6d 61 6e 64 73 20 77 t all commands w
5920: 6f 75 6c 64 20 6d 69 67 72 61 74 65 20 69 6e 20 ould migrate in
5930: 74 69 6d 65 2c 20 62 75 74 20 74 68 65 72 65 20 time, but there
5940: 77 61 73 20 6e 6f 74 0a 61 20 62 69 67 20 68 75 was not.a big hu
5950: 72 72 79 2e 20 20 53 65 76 65 72 61 6c 20 72 6f rry. Several ro
5960: 75 74 69 6e 65 73 20 69 6e 63 61 70 61 62 6c 65 utines incapable
5970: 20 6f 66 20 73 75 70 70 6f 72 74 69 6e 67 20 74 of supporting t
5980: 68 65 20 65 78 70 61 6e 64 65 64 0a 54 63 6c 20 he expanded.Tcl
5990: 76 61 6c 75 65 20 6d 6f 64 65 6c 20 77 65 72 65 value model were
59a0: 20 64 65 63 6c 61 72 65 64 20 64 65 70 72 65 63 declared deprec
59b0: 61 74 65 64 20 61 73 20 61 20 70 72 6f 64 20 74 ated as a prod t
59c0: 6f 77 61 72 64 20 65 76 65 6e 74 75 61 6c 20 6d oward eventual m
59d0: 69 67 72 61 74 69 6f 6e 2e 0a 0a 54 63 6c 20 38 igration...Tcl 8
59e0: 2e 30 20 69 74 73 65 6c 66 20 64 69 64 20 6e 6f .0 itself did no
59f0: 74 20 66 75 6c 6c 79 20 63 6f 6e 76 65 72 74 20 t fully convert
5a00: 61 6c 6c 20 6f 66 20 69 74 73 20 62 75 69 6c 74 all of its built
5a10: 2d 69 6e 20 63 6f 6d 6d 61 6e 64 73 2e 20 41 74 -in commands. At
5a20: 20 6c 65 61 73 74 0a 32 33 20 2a 2a 54 63 6c 5f least.23 **Tcl_
5a30: 43 6d 64 50 72 6f 63 2a 2a 20 63 6f 6d 6d 61 6e CmdProc** comman
5a40: 64 20 70 72 6f 63 65 64 75 72 65 73 20 70 65 72 d procedures per
5a50: 73 69 73 74 20 77 69 74 68 69 6e 20 69 74 2e 20 sist within it.
5a60: 53 6f 6d 65 20 63 61 6e 20 62 65 0a 64 65 6d 6f Some can be.demo
5a70: 6e 73 74 72 61 74 65 64 2e 0a 0a 3c 70 72 65 3e nstrated...<pre>
5a80: 0a 60 60 60 0a 09 25 20 72 65 67 73 75 62 20 2d .```..% regsub -
5a90: 61 6c 6c 20 79 20 7a 79 7a 7c 7a 79 7a 20 78 20 all y zyz|zyz x
5aa0: 66 6f 6f 0a 09 32 0a 09 25 20 73 65 74 20 66 6f foo..2..% set fo
5ab0: 6f 0a 09 7a 78 7a 7c 7a 78 7a 0a 09 25 20 72 65 o..zxz|zxz..% re
5ac0: 67 73 75 62 20 2d 61 6c 6c 20 79 20 7a 79 7a 5c gsub -all y zyz\
5ad0: 78 30 30 7a 79 7a 20 78 20 66 6f 6f 0a 09 31 0a x00zyz x foo..1.
5ae0: 09 25 20 73 65 74 20 66 6f 6f 0a 09 7a 78 7a 0a .% set foo..zxz.
5af0: 60 60 60 0a 3c 2f 70 72 65 3e 0a 0a 4f 74 68 65 ```.</pre>..Othe
5b00: 72 73 20 61 72 65 20 6c 61 72 67 65 6c 79 20 6d rs are largely m
5b10: 61 73 6b 65 64 20 62 79 20 74 68 65 20 75 73 65 asked by the use
5b20: 20 6f 66 20 74 68 65 20 62 79 74 65 63 6f 64 65 of the bytecode
5b30: 20 63 6f 6d 70 69 6c 65 72 20 61 6e 64 20 0a 65 compiler and .e
5b40: 78 65 63 75 74 69 6f 6e 20 65 6e 67 69 6e 65 2c xecution engine,
5b50: 20 61 6c 73 6f 20 6e 65 77 20 69 6e 20 54 63 6c also new in Tcl
5b60: 20 38 2e 30 2e 0a 49 6e 20 6f 74 68 65 72 20 62 8.0..In other b
5b70: 75 69 6c 74 2d 69 6e 20 63 6f 6d 6d 61 6e 64 73 uilt-in commands
5b80: 2c 20 74 68 65 20 75 73 65 20 6f 66 20 72 6f 75 , the use of rou
5b90: 74 69 6e 65 73 20 77 69 74 68 20 74 68 65 73 65 tines with these
5ba0: 20 69 6e 74 65 72 66 61 63 65 0a 6c 69 6d 69 74 interface.limit
5bb0: 61 74 69 6f 6e 73 20 6c 65 61 64 73 20 74 6f 20 ations leads to
5bc0: 73 69 6d 69 6c 61 72 20 66 61 69 6c 75 72 65 73 similar failures
5bd0: 2e 0a 0a 3c 70 72 65 3e 0a 60 60 60 0a 09 25 20 ...<pre>.```..%
5be0: 73 65 74 20 66 6f 6f 20 3c 5c 78 30 30 3e 0a 09 set foo <\x00>..
5bf0: 3c 3e 0a 09 25 20 73 75 62 73 74 20 7b 24 66 6f <>..% subst {$fo
5c00: 6f 7d 0a 09 3c 0a 60 60 60 0a 3c 2f 70 72 65 3e o}..<.```.</pre>
5c10: 0a 0a 53 65 76 65 72 61 6c 20 72 6f 75 74 69 6e ..Several routin
5c20: 65 73 2c 20 62 6f 74 68 20 70 75 62 6c 69 63 20 es, both public
5c30: 61 6e 64 20 70 72 69 76 61 74 65 2c 20 61 6e 64 and private, and
5c40: 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 65 73 74 a number of est
5c50: 61 62 6c 69 73 68 65 64 0a 64 61 74 61 20 73 74 ablished.data st
5c60: 72 75 63 74 75 72 65 73 20 63 6f 6e 74 69 6e 75 ructures continu
5c70: 65 20 74 6f 20 6d 61 6b 65 20 75 73 65 20 6f 66 e to make use of
5c80: 20 2a 2a 4e 55 4c 2a 2a 2d 74 65 72 6d 69 6e 61 **NUL**-termina
5c90: 74 65 64 20 73 74 72 69 6e 67 73 2e 20 42 65 63 ted strings. Bec
5ca0: 61 75 73 65 0a 6f 66 20 74 68 69 73 2c 20 61 6c ause.of this, al
5cb0: 74 68 6f 75 67 68 20 74 68 65 20 66 75 6c 6c 79 though the fully
5cc0: 20 67 65 6e 65 72 61 6c 20 73 65 74 20 6f 66 20 general set of
5cd0: 54 63 6c 20 76 61 6c 75 65 73 20 69 6e 63 6c 75 Tcl values inclu
5ce0: 64 65 73 20 61 6c 6c 0a 62 69 6e 61 72 79 20 73 des all.binary s
5cf0: 65 71 75 65 6e 63 65 73 2c 20 73 65 76 65 72 61 equences, severa
5d00: 6c 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 l components of
5d10: 54 63 6c 20 72 65 6d 61 69 6e 20 6c 69 6d 69 74 Tcl remain limit
5d20: 65 64 20 69 6e 20 72 65 6c 65 61 73 65 20 38 2e ed in release 8.
5d30: 30 2c 0a 61 6e 64 20 6d 61 79 20 6e 6f 74 20 69 0,.and may not i
5d40: 6e 63 6c 75 64 65 20 74 68 65 20 2a 2a 4e 55 4c nclude the **NUL
5d50: 2a 2a 20 62 79 74 65 2e 20 45 78 61 6d 70 6c 65 ** byte. Example
5d60: 73 20 69 6e 63 6c 75 64 65 20 63 6f 6d 6d 61 6e s include comman
5d70: 64 20 6e 61 6d 65 73 2c 0a 6e 61 6d 65 73 70 61 d names,.namespa
5d80: 63 65 20 6e 61 6d 65 73 2c 20 63 68 61 6e 6e 65 ce names, channe
5d90: 6c 20 6e 61 6d 65 73 2c 20 63 68 61 6e 6e 65 6c l names, channel
5da0: 20 74 79 70 65 20 6e 61 6d 65 73 2c 20 2a 2a 54 type names, **T
5db0: 63 6c 5f 4f 62 6a 54 79 70 65 2a 2a 20 6e 61 6d cl_ObjType** nam
5dc0: 65 73 2c 0a 61 6e 64 20 6c 69 6b 65 6c 79 20 6d es,.and likely m
5dd0: 6f 72 65 2e 0a 0a 23 23 20 54 63 6c 20 38 2e 31 ore...## Tcl 8.1
5de0: 20 28 44 65 76 65 6c 6f 70 6d 65 6e 74 20 62 65 (Development be
5df0: 67 75 6e 20 31 39 39 37 2c 20 4f 66 66 69 63 69 gun 1997, Offici
5e00: 61 6c 20 72 65 6c 65 61 73 65 20 31 39 39 39 2d al release 1999-
5e10: 29 0a 0a 2a 53 74 72 69 6e 67 73 20 65 6e 63 6f )..*Strings enco
5e20: 64 65 64 20 69 6e 20 55 54 46 2d 38 2c 20 61 73 ded in UTF-8, as
5e30: 20 6d 6f 64 69 66 69 65 64 20 69 6e 20 4a 61 76 modified in Jav
5e40: 61 20 31 2e 31 2a 0a 0a 41 20 6d 61 6a 6f 72 20 a 1.1*..A major
5e50: 72 65 2d 74 68 69 6e 6b 69 6e 67 20 6f 66 20 54 re-thinking of T
5e60: 63 6c 20 76 61 6c 75 65 73 20 62 65 67 61 6e 20 cl values began
5e70: 69 6e 20 31 39 39 37 20 61 73 20 77 6f 72 6b 20 in 1997 as work
5e80: 74 6f 77 61 72 64 20 54 63 6c 20 38 2e 31 0a 62 toward Tcl 8.1.b
5e90: 65 67 61 6e 2e 20 54 68 65 20 72 65 63 6f 6e 63 egan. The reconc
5ea0: 69 6c 69 61 74 69 6f 6e 20 6f 66 20 55 6e 69 63 iliation of Unic
5eb0: 6f 64 65 20 31 2e 31 20 61 6e 64 20 49 53 4f 2d ode 1.1 and ISO-
5ec0: 31 30 36 34 36 20 69 6e 74 6f 20 61 67 72 65 65 10646 into agree
5ed0: 6d 65 6e 74 0a 73 68 6f 77 65 64 20 61 20 63 6c ment.showed a cl
5ee0: 65 61 72 20 70 61 74 68 20 66 6f 72 77 61 72 64 ear path forward
5ef0: 20 66 6f 72 20 73 6f 66 74 77 61 72 65 20 74 6f for software to
5f00: 20 6d 61 6e 61 67 65 20 74 65 78 74 20 65 6e 63 manage text enc
5f10: 6f 64 69 6e 67 73 20 75 6e 64 65 72 0a 6f 6e 65 odings under.one
5f20: 20 6f 72 67 61 6e 69 7a 65 64 20 70 6c 61 6e 2e organized plan.
5f30: 20 20 57 69 74 68 20 74 68 69 73 20 6e 65 77 20 With this new
5f40: 66 75 74 75 72 65 20 76 69 73 69 6f 6e 20 6f 66 future vision of
5f50: 20 74 65 78 74 20 6d 61 6e 61 67 65 6d 65 6e 74 text management
5f60: 20 69 6e 0a 73 6f 66 74 77 61 72 65 2c 20 74 68 in.software, th
5f70: 65 20 6e 6f 74 69 6f 6e 20 74 68 61 74 20 70 72 e notion that pr
5f80: 6f 67 72 61 6d 6d 65 72 73 20 63 6f 75 6c 64 20 ogrammers could
5f90: 62 65 6e 65 66 69 74 20 66 72 6f 6d 20 62 65 69 benefit from bei
5fa0: 6e 67 20 73 68 69 65 6c 64 65 64 0a 66 72 6f 6d ng shielded.from
5fb0: 20 74 68 65 20 6e 65 65 64 20 74 6f 20 64 65 61 the need to dea
5fc0: 6c 20 77 69 74 68 20 65 6e 63 6f 64 69 6e 67 73 l with encodings
5fd0: 20 72 61 70 69 64 6c 79 20 76 61 6e 69 73 68 65 rapidly vanishe
5fe0: 64 2e 20 20 49 6e 20 63 6f 6e 74 72 61 73 74 2c d. In contrast,
5ff0: 20 74 68 65 0a 76 61 6c 75 65 20 6f 66 20 6a 6f the.value of jo
6000: 69 6e 69 6e 67 20 69 6e 20 73 75 70 70 6f 72 74 ining in support
6010: 20 6f 66 20 61 20 64 65 76 65 6c 6f 70 69 6e 67 of a developing
6020: 20 73 74 61 6e 64 61 72 64 20 77 61 73 20 61 70 standard was ap
6030: 70 61 72 65 6e 74 2e 20 20 0a 0a 54 68 65 20 54 parent. ..The T
6040: 63 6c 20 5f 63 68 61 6e 67 65 73 5f 20 66 69 6c cl _changes_ fil
6050: 65 20 72 65 63 6f 72 64 73 20 61 6e 20 65 6e 74 e records an ent
6060: 72 79 20 28 69 6e 20 70 61 72 74 29 3a 0a 0a 3c ry (in part):..<
6070: 70 72 65 3e 0a 60 60 60 0a 36 2f 31 38 2f 39 37 pre>.```.6/18/97
6080: 20 28 6e 65 77 20 66 65 61 74 75 72 65 29 20 54 (new feature) T
6090: 63 6c 20 6e 6f 77 20 73 75 70 70 6f 72 74 73 20 cl now supports
60a0: 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 20 63 68 international ch
60b0: 61 72 61 63 74 65 72 20 73 65 74 73 3a 0a 20 20 aracter sets:.
60c0: 20 20 2d 20 41 6c 6c 20 43 20 41 50 49 73 20 6e - All C APIs n
60d0: 6f 77 20 61 63 63 65 70 74 20 55 54 46 2d 38 20 ow accept UTF-8
60e0: 73 74 72 69 6e 67 73 20 69 6e 73 74 65 61 64 20 strings instead
60f0: 6f 66 20 69 73 6f 38 38 35 39 2d 31 20 73 74 72 of iso8859-1 str
6100: 69 6e 67 73 2c 0a 20 20 20 20 20 20 77 68 65 72 ings,. wher
6110: 65 76 65 72 20 79 6f 75 20 73 65 65 20 22 63 68 ever you see "ch
6120: 61 72 20 2a 22 2c 20 75 6e 6c 65 73 73 20 65 78 ar *", unless ex
6130: 70 6c 69 63 69 74 6c 79 20 6e 6f 74 65 64 20 6f plicitly noted o
6140: 74 68 65 72 77 69 73 65 2e 0a 20 20 20 20 2d 20 therwise.. -
6150: 41 6c 6c 20 54 63 6c 20 73 74 72 69 6e 67 73 20 All Tcl strings
6160: 72 65 70 72 65 73 65 6e 74 65 64 20 69 6e 20 55 represented in U
6170: 54 46 2d 38 2c 20 77 68 69 63 68 20 69 73 20 61 TF-8, which is a
6180: 20 63 6f 6e 76 65 6e 69 65 6e 74 0a 20 20 20 20 convenient.
6190: 20 20 6d 75 6c 74 69 2d 62 79 74 65 20 65 6e 63 multi-byte enc
61a0: 6f 64 69 6e 67 20 6f 66 20 55 6e 69 63 6f 64 65 oding of Unicode
61b0: 2e 20 20 56 61 72 69 61 62 6c 65 20 6e 61 6d 65 . Variable name
61c0: 73 2c 20 70 72 6f 63 65 64 75 72 65 20 6e 61 6d s, procedure nam
61d0: 65 73 2c 0a 20 20 20 20 20 20 61 6e 64 20 61 6c es,. and al
61e0: 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 69 l other values i
61f0: 6e 20 54 63 6c 20 6d 61 79 20 69 6e 63 6c 75 64 n Tcl may includ
6200: 65 20 61 72 62 69 74 72 61 72 79 20 55 6e 69 63 e arbitrary Unic
6210: 6f 64 65 20 63 68 61 72 61 63 74 65 72 73 2e 0a ode characters..
6220: 20 20 20 20 20 20 46 6f 72 20 65 78 61 6d 70 6c For exampl
6230: 65 2c 20 74 68 65 20 54 63 6c 20 63 6f 6d 6d 61 e, the Tcl comma
6240: 6e 64 20 22 73 74 72 69 6e 67 20 6c 65 6e 67 74 nd "string lengt
6250: 68 22 20 72 65 74 75 72 6e 73 20 68 6f 77 20 6d h" returns how m
6260: 61 6e 79 0a 20 20 20 20 20 20 55 6e 69 63 6f 64 any. Unicod
6270: 65 20 63 68 61 72 61 63 74 65 72 73 20 61 72 65 e characters are
6280: 20 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 in the argument
6290: 20 73 74 72 69 6e 67 2e 0a 20 20 20 20 2d 20 46 string.. - F
62a0: 6f 72 20 4a 61 76 61 20 63 6f 6d 70 61 74 69 62 or Java compatib
62b0: 69 6c 69 74 79 2c 20 65 6d 62 65 64 64 65 64 20 ility, embedded
62c0: 6e 75 6c 6c 20 62 79 74 65 73 20 69 6e 20 43 20 null bytes in C
62d0: 73 74 72 69 6e 67 73 20 61 72 65 0a 20 20 20 20 strings are.
62e0: 20 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 represented as
62f0: 20 5c 78 43 30 38 30 20 69 6e 20 55 54 46 2d 38 \xC080 in UTF-8
6300: 20 73 74 72 69 6e 67 73 2c 20 62 75 74 20 74 68 strings, but th
6310: 65 20 6e 75 6c 6c 20 62 79 74 65 20 61 74 20 74 e null byte at t
6320: 68 65 20 65 6e 64 0a 20 20 20 20 20 20 6f 66 20 he end. of
6330: 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 72 a UTF-8 string r
6340: 65 6d 61 69 6e 73 20 5c 30 2e 20 20 54 68 75 73 emains \0. Thus
6350: 20 54 63 6c 20 73 74 72 69 6e 67 73 20 6f 6e 63 Tcl strings onc
6360: 65 20 61 67 61 69 6e 20 64 6f 20 6e 6f 74 0a 20 e again do not.
6370: 20 20 20 20 20 63 6f 6e 74 61 69 6e 20 6e 75 6c contain nul
6380: 6c 20 62 79 74 65 73 2c 20 65 78 63 65 70 74 20 l bytes, except
6390: 66 6f 72 20 74 65 72 6d 69 6e 61 74 69 6f 6e 20 for termination
63a0: 62 79 74 65 73 2e 0a 20 20 20 20 2d 20 46 6f 72 bytes.. - For
63b0: 20 4a 61 76 61 20 63 6f 6d 70 61 74 69 62 69 6c Java compatibil
63c0: 69 74 79 2c 20 22 5c 75 58 58 58 58 22 20 69 73 ity, "\uXXXX" is
63d0: 20 75 73 65 64 20 69 6e 20 54 63 6c 20 74 6f 20 used in Tcl to
63e0: 65 6e 74 65 72 20 61 20 55 6e 69 63 6f 64 65 0a enter a Unicode.
63f0: 20 20 20 20 20 20 63 68 61 72 61 63 74 65 72 2e character.
6400: 20 20 22 5c 75 30 30 30 30 22 20 74 68 72 6f 75 "\u0000" throu
6410: 67 68 20 22 5c 75 66 66 66 66 22 20 61 72 65 20 gh "\uffff" are
6420: 61 63 63 65 70 74 61 62 6c 65 20 55 6e 69 63 6f acceptable Unico
6430: 64 65 0a 20 20 20 20 20 20 63 68 61 72 61 63 74 de. charact
6440: 65 72 73 2e 0a 60 60 60 0a 3c 2f 70 72 65 3e 0a ers..```.</pre>.
6450: 0a 54 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 .The correspondi
6460: 6e 67 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70 ng development p
6470: 61 74 63 68 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 atch is no longe
6480: 72 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 r available. Th
6490: 65 20 72 65 6c 65 76 61 6e 74 0a 63 6f 64 65 20 e relevant.code
64a0: 64 65 76 65 6c 6f 70 6d 65 6e 74 20 66 6f 73 73 development foss
64b0: 69 6c 20 72 65 63 6f 72 64 20 66 6f 72 20 54 63 il record for Tc
64c0: 6c 20 73 74 61 72 74 73 20 6f 6e 20 53 65 70 74 l starts on Sept
64d0: 65 6d 62 65 72 20 32 31 2c 20 31 39 39 38 2c 0a ember 21, 1998,.
64e0: 77 69 74 68 20 74 68 65 20 73 6f 75 72 63 65 20 with the source
64f0: 63 6f 64 65 20 6f 66 20 73 6f 6d 65 74 68 69 6e code of somethin
6500: 67 20 63 6c 6f 73 65 20 74 6f 20 74 68 65 20 54 g close to the T
6510: 63 6c 20 38 2e 31 61 32 20 72 65 6c 65 61 73 65 cl 8.1a2 release
6520: 0a 28 46 65 62 72 75 61 72 79 20 32 34 2c 20 31 .(February 24, 1
6530: 39 39 38 29 2e 20 57 65 20 61 6c 73 6f 20 68 61 998). We also ha
6540: 76 65 20 74 68 65 20 54 63 6c 20 38 2e 31 61 31 ve the Tcl 8.1a1
6550: 20 72 65 6c 65 61 73 65 20 28 4a 61 6e 75 61 72 release (Januar
6560: 79 20 32 33 2c 20 31 39 39 38 29 2e 0a 54 68 65 y 23, 1998)..The
6570: 20 61 62 73 65 6e 63 65 20 6f 66 20 72 65 6c 65 absence of rele
6580: 76 61 6e 74 20 65 6e 74 72 69 65 73 20 69 6e 20 vant entries in
6590: 74 68 65 20 5f 63 68 61 6e 67 65 73 5f 20 66 69 the _changes_ fi
65a0: 6c 65 0a 73 75 67 67 65 73 74 73 20 74 68 65 20 le.suggests the
65b0: 20 22 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 20 "international
65c0: 63 68 61 72 61 63 74 65 72 20 73 65 74 22 20 73 character set" s
65d0: 75 70 70 6f 72 74 20 69 6e 20 74 68 65 20 54 63 upport in the Tc
65e0: 6c 20 38 2e 31 61 31 0a 72 65 6c 65 61 73 65 20 l 8.1a1.release
65f0: 69 73 20 77 68 61 74 20 77 61 73 20 63 6f 6d 6d is what was comm
6600: 69 74 74 65 64 20 69 6e 20 4a 75 6e 65 2c 20 31 itted in June, 1
6610: 39 39 37 2e 20 57 65 20 63 61 6e 20 6f 6e 6c 79 997. We can only
6620: 20 73 70 65 63 75 6c 61 74 65 20 77 68 61 74 0a speculate what.
6630: 64 65 76 65 6c 6f 70 6d 65 6e 74 20 65 66 66 6f development effo
6640: 72 74 2c 20 77 68 61 74 20 6a 75 64 67 6d 65 6e rt, what judgmen
6650: 74 73 20 61 6e 64 20 77 68 61 74 20 72 65 66 65 ts and what refe
6660: 72 72 61 6c 73 20 74 6f 20 77 68 61 74 20 73 6f rrals to what so
6670: 75 72 63 65 73 0a 61 6e 64 20 73 74 61 6e 64 61 urces.and standa
6680: 72 64 73 20 70 6c 61 79 65 64 20 6f 75 74 20 69 rds played out i
6690: 6e 20 74 68 65 20 64 65 76 65 6c 6f 70 6d 65 6e n the developmen
66a0: 74 20 6f 66 20 74 68 61 74 20 66 69 72 73 74 20 t of that first
66b0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 70 implementation.p
66c0: 61 74 63 68 2e 20 4f 75 72 20 73 70 65 63 75 6c atch. Our specul
66d0: 61 74 69 6f 6e 20 69 73 20 69 6e 66 6f 72 6d 65 ation is informe
66e0: 64 2c 20 74 68 6f 75 67 68 2c 20 62 79 20 77 68 d, though, by wh
66f0: 61 74 20 77 65 20 6b 6e 6f 77 20 61 6e 64 20 63 at we know and c
6700: 61 6e 20 72 65 61 73 6f 6e 61 62 6c 79 0a 69 6e an reasonably.in
6710: 66 65 72 20 66 72 6f 6d 20 74 68 65 20 74 65 63 fer from the tec
6720: 68 6e 69 63 61 6c 20 65 6e 76 69 72 6f 6e 6d 65 hnical environme
6730: 6e 74 20 77 68 65 72 65 20 74 68 69 73 20 77 6f nt where this wo
6740: 72 6b 20 74 6f 6f 6b 20 70 6c 61 63 65 2e 0a 0a rk took place...
6750: 54 68 65 20 63 6c 61 69 6d 20 74 68 61 74 20 54 The claim that T
6760: 63 6c 20 38 2e 31 20 73 74 72 69 6e 67 73 20 61 cl 8.1 strings a
6770: 72 65 20 73 74 6f 72 65 64 20 69 6e 20 55 54 46 re stored in UTF
6780: 2d 38 20 69 73 20 66 61 6c 73 65 2c 20 73 74 72 -8 is false, str
6790: 69 63 74 6c 79 0a 73 70 65 61 6b 69 6e 67 2e 20 ictly.speaking.
67a0: 4e 65 69 74 68 65 72 20 74 68 65 20 65 6e 63 6f Neither the enco
67b0: 64 69 6e 67 20 67 65 6e 65 72 61 74 65 64 20 6e ding generated n
67c0: 6f 72 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 or the encoding
67d0: 61 63 63 65 70 74 65 64 20 62 79 20 54 63 6c 20 accepted by Tcl
67e0: 38 2e 31 0a 66 6f 6c 6c 6f 77 20 74 68 65 20 70 8.1.follow the p
67f0: 72 65 63 69 73 65 20 73 70 65 63 69 66 69 63 61 recise specifica
6800: 74 69 6f 6e 20 6f 66 20 55 54 46 2d 38 2e 20 4e tion of UTF-8. N
6810: 6f 74 20 74 68 65 20 73 70 65 63 69 66 69 63 61 ot the specifica
6820: 74 69 6f 6e 20 69 6e 20 70 6c 61 63 65 0a 74 6f tion in place.to
6830: 64 61 79 2c 20 6e 6f 72 20 61 6e 79 20 6f 66 20 day, nor any of
6840: 74 68 65 20 73 70 65 63 69 66 69 63 61 74 69 6f the specificatio
6850: 6e 73 20 69 6e 20 70 6c 61 63 65 20 6e 65 61 72 ns in place near
6860: 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 69 the time of thi
6870: 73 20 77 6f 72 6b 2e 0a 41 73 20 74 68 65 20 5f s work..As the _
6880: 63 68 61 6e 67 65 73 5f 20 65 6e 74 72 79 20 69 changes_ entry i
6890: 6e 64 69 63 61 74 65 73 2c 20 61 20 6e 75 6d 62 ndicates, a numb
68a0: 65 72 20 6f 66 20 69 6d 70 6c 65 6d 65 6e 74 61 er of implementa
68b0: 74 69 6f 6e 20 63 68 6f 69 63 65 73 20 61 72 65 tion choices are
68c0: 0a 63 6c 61 69 6d 65 64 20 74 6f 20 73 65 72 76 .claimed to serv
68d0: 65 20 22 4a 61 76 61 20 63 6f 6d 70 61 74 69 62 e "Java compatib
68e0: 69 6c 69 74 79 22 2e 20 54 63 6c 20 64 65 76 65 ility". Tcl deve
68f0: 6c 6f 70 6d 65 6e 74 20 61 74 20 74 68 69 73 20 lopment at this
6900: 74 69 6d 65 20 74 6f 6f 6b 0a 70 6c 61 63 65 20 time took.place
6910: 61 74 20 53 75 6e 20 4d 69 63 72 6f 73 79 73 74 at Sun Microsyst
6920: 65 6d 73 2c 20 77 68 69 63 68 20 77 61 73 20 61 ems, which was a
6930: 6c 73 6f 20 74 68 65 20 68 6f 6d 65 20 6f 66 20 lso the home of
6940: 4a 61 76 61 2e 20 49 74 20 61 70 70 65 61 72 73 Java. It appears
6950: 20 74 68 61 74 0a 22 4a 61 76 61 20 63 6f 6d 70 that."Java comp
6960: 61 74 69 62 69 6c 69 74 79 22 20 69 73 20 6e 6f atibility" is no
6970: 74 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 62 t a statement ab
6980: 6f 75 74 20 61 6e 79 20 73 6f 72 74 20 6f 66 20 out any sort of
6990: 69 6e 74 65 72 6f 70 65 72 61 62 69 6c 69 74 79 interoperability
69a0: 2c 0a 62 75 74 20 61 62 6f 75 74 20 66 6f 6c 6c ,.but about foll
69b0: 6f 77 69 6e 67 20 74 68 65 20 73 61 6d 65 20 63 owing the same c
69c0: 6f 6e 76 65 6e 74 69 6f 6e 73 20 66 6f 72 20 74 onventions for t
69d0: 68 65 20 73 61 6b 65 20 6f 66 20 70 72 6f 67 72 he sake of progr
69e0: 61 6d 6d 65 72 0a 66 61 6d 69 6c 69 61 72 69 74 ammer.familiarit
69f0: 79 2e 20 20 54 63 6c 20 38 2e 31 20 61 64 64 65 y. Tcl 8.1 adde
6a00: 64 20 74 68 65 20 2a 2a 5c 5c 75 2a 2a 5f 5f 5f d the **\\u**___
6a10: 48 48 48 48 5f 5f 5f 20 73 79 6e 74 61 78 20 61 HHHH___ syntax a
6a20: 73 20 61 20 77 61 79 20 66 6f 72 0a 73 63 72 69 s a way for.scri
6a30: 70 74 73 20 74 6f 20 73 70 65 63 69 66 79 20 55 pts to specify U
6a40: 6e 69 63 6f 64 65 20 63 68 61 72 61 63 74 65 72 nicode character
6a50: 73 20 75 73 69 6e 67 20 6f 6e 6c 79 20 74 68 65 s using only the
6a60: 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72 ASCII character
6a70: 73 2e 0a 54 68 69 73 20 69 73 20 74 68 65 20 73 s..This is the s
6a80: 61 6d 65 20 73 79 6e 74 61 78 20 4a 61 76 61 20 ame syntax Java
6a90: 75 73 65 73 20 66 6f 72 20 74 68 65 20 73 61 6d uses for the sam
6aa0: 65 20 74 68 69 6e 67 2e 20 54 68 65 20 22 63 6f e thing. The "co
6ab0: 6d 70 61 74 69 62 69 6c 69 74 79 22 0a 61 74 20 mpatibility".at
6ac0: 77 6f 72 6b 20 69 73 20 61 20 72 65 64 75 63 74 work is a reduct
6ad0: 69 6f 6e 20 6f 66 20 63 6f 67 6e 69 74 69 76 65 ion of cognitive
6ae0: 20 62 75 72 64 65 6e 20 62 79 20 75 73 69 6e 67 burden by using
6af0: 20 74 68 65 20 73 61 6d 65 20 73 6f 6c 75 74 69 the same soluti
6b00: 6f 6e 20 74 6f 0a 74 68 65 20 73 61 6d 65 20 70 on to.the same p
6b10: 72 6f 62 6c 65 6d 20 69 6e 20 74 77 6f 20 6c 61 roblem in two la
6b20: 6e 67 75 61 67 65 73 2e 20 20 54 63 6c 20 63 6f nguages. Tcl co
6b30: 70 69 65 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 pied some other
6b40: 64 65 76 69 61 74 69 6f 6e 73 0a 66 72 6f 6d 20 deviations.from
6b50: 73 74 61 6e 64 61 72 64 20 55 54 46 2d 38 20 66 standard UTF-8 f
6b60: 72 6f 6d 20 4a 61 76 61 20 61 73 20 77 65 6c 6c rom Java as well
6b70: 2e 0a 0a 54 6f 20 61 70 70 72 65 63 69 61 74 65 ...To appreciate
6b80: 20 74 68 65 20 63 68 6f 69 63 65 73 20 6d 61 64 the choices mad
6b90: 65 20 62 79 20 54 63 6c 20 69 6e 20 68 6f 77 20 e by Tcl in how
6ba0: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 73 75 70 to implement sup
6bb0: 70 6f 72 74 20 66 6f 72 20 74 68 65 0a 22 69 6e port for the."in
6bc0: 74 65 72 6e 61 74 69 6f 6e 61 6c 20 63 68 61 72 ternational char
6bd0: 61 63 74 65 72 20 73 65 74 22 2c 20 69 74 20 69 acter set", it i
6be0: 73 20 68 65 6c 70 66 75 6c 20 74 6f 20 72 65 76 s helpful to rev
6bf0: 69 65 77 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 iew some of the
6c00: 62 61 73 69 63 73 0a 6f 66 20 65 6e 63 6f 64 69 basics.of encodi
6c10: 6e 67 2c 20 61 6e 64 20 74 68 65 20 70 6c 61 79 ng, and the play
6c20: 65 72 73 20 61 6e 64 20 6f 66 66 65 72 65 64 20 ers and offered
6c30: 73 74 61 6e 64 61 72 64 73 20 6f 66 20 74 68 65 standards of the
6c40: 20 74 69 6d 65 2e 20 20 54 77 6f 20 65 66 66 6f time. Two effo
6c50: 72 74 73 0a 61 74 20 64 65 66 69 6e 69 6e 67 20 rts.at defining
6c60: 61 20 73 69 6e 67 6c 65 20 55 6e 69 76 65 72 73 a single Univers
6c70: 61 6c 20 43 6f 64 65 64 20 43 68 61 72 61 63 74 al Coded Charact
6c80: 65 72 20 53 65 74 20 28 55 43 53 29 20 77 65 72 er Set (UCS) wer
6c90: 65 20 61 63 74 69 76 65 20 0a 64 75 72 69 6e 67 e active .during
6ca0: 20 74 68 65 20 31 39 39 30 73 2c 20 49 53 4f 2d the 1990s, ISO-
6cb0: 31 30 36 34 36 20 61 6e 64 20 55 6e 69 63 6f 64 10646 and Unicod
6cc0: 65 2e 20 20 54 68 65 20 63 6f 6d 6d 6f 6e 20 74 e. The common t
6cd0: 61 73 6b 20 77 61 73 20 74 6f 20 64 65 66 69 6e ask was to defin
6ce0: 65 0a 61 20 6d 61 70 70 69 6e 67 20 66 72 6f 6d e.a mapping from
6cf0: 20 65 61 63 68 20 69 6e 74 65 67 65 72 20 69 6e each integer in
6d00: 64 65 78 20 76 61 6c 75 65 20 28 63 6f 64 65 70 dex value (codep
6d10: 6f 69 6e 74 29 20 74 6f 20 61 20 63 68 61 72 61 oint) to a chara
6d20: 63 74 65 72 20 61 73 73 69 67 6e 65 64 0a 74 6f cter assigned.to
6d30: 20 74 68 65 20 6c 6f 63 61 74 69 6f 6e 20 69 6e the location in
6d40: 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20 73 the character s
6d50: 65 74 20 74 61 62 6c 65 20 69 64 65 6e 74 69 66 et table identif
6d60: 69 65 64 20 62 79 20 74 68 65 20 63 6f 64 65 70 ied by the codep
6d70: 6f 69 6e 74 2e 20 54 68 65 0a 49 53 4f 2d 31 30 oint. The.ISO-10
6d80: 36 34 36 20 65 66 66 6f 72 74 20 63 6f 6e 63 65 646 effort conce
6d90: 69 76 65 64 20 6f 66 20 61 20 74 61 62 6c 65 20 ived of a table
6da0: 77 69 74 68 20 34 2d 62 79 74 65 20 28 33 32 2d with 4-byte (32-
6db0: 62 69 74 29 20 63 6f 64 65 70 6f 69 6e 74 73 2c bit) codepoints,
6dc0: 20 77 69 74 68 0a 73 70 61 63 65 20 66 6f 72 20 with.space for
6dd0: 75 70 20 74 6f 20 32 5e 33 32 20 63 68 61 72 61 up to 2^32 chara
6de0: 63 74 65 72 73 2e 20 20 54 68 65 79 20 67 61 76 cters. They gav
6df0: 65 20 74 68 65 20 6e 61 6d 65 20 55 43 53 2d 34 e the name UCS-4
6e00: 20 74 6f 20 62 6f 74 68 20 74 68 69 73 0a 63 6f to both this.co
6e10: 6e 63 65 70 74 75 61 6c 20 63 68 61 72 61 63 74 nceptual charact
6e20: 65 72 20 73 65 74 20 61 6e 64 20 74 68 65 20 74 er set and the t
6e30: 72 69 76 69 61 6c 20 65 6e 63 6f 64 69 6e 67 20 rivial encoding
6e40: 6f 66 20 69 74 73 20 63 6f 64 65 70 6f 69 6e 74 of its codepoint
6e50: 73 0a 61 73 20 34 2d 62 79 74 65 20 69 6e 74 65 s.as 4-byte inte
6e60: 67 65 72 20 76 61 6c 75 65 73 2e 20 20 49 6e 20 ger values. In
6e70: 63 6f 6e 74 72 61 73 74 2c 20 74 68 65 20 55 6e contrast, the Un
6e80: 69 63 6f 64 65 20 65 66 66 6f 72 74 20 70 72 6f icode effort pro
6e90: 70 6f 73 65 64 0a 61 20 63 68 61 72 61 63 74 65 posed.a characte
6ea0: 72 20 73 65 74 20 74 61 62 6c 65 20 77 69 74 68 r set table with
6eb0: 20 75 70 20 74 6f 20 32 5e 31 36 20 63 68 61 72 up to 2^16 char
6ec0: 61 63 74 65 72 73 2c 20 69 6e 64 65 78 65 64 20 acters, indexed
6ed0: 62 79 20 32 2d 62 79 74 65 20 28 31 36 20 62 69 by 2-byte (16 bi
6ee0: 74 29 0a 69 6e 64 69 63 65 73 2e 20 20 54 68 69 t).indices. Thi
6ef0: 73 20 28 70 6f 74 65 6e 74 69 61 6c 6c 79 29 20 s (potentially)
6f00: 73 6d 61 6c 6c 65 72 20 63 68 61 72 61 63 74 65 smaller characte
6f10: 72 20 73 65 74 20 77 61 73 20 66 6f 72 6d 61 6c r set was formal
6f20: 6c 79 20 6b 6e 6f 77 6e 0a 61 73 20 55 43 53 2d ly known.as UCS-
6f30: 32 2c 20 54 68 65 20 74 72 69 76 69 61 6c 20 65 2, The trivial e
6f40: 6e 63 6f 64 69 6e 67 20 6f 66 20 69 74 73 20 63 ncoding of its c
6f50: 6f 64 65 70 6f 69 6e 74 73 20 61 73 20 32 2d 62 odepoints as 2-b
6f60: 79 74 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 yte integer valu
6f70: 65 73 0a 77 61 73 20 61 6c 73 6f 20 63 61 6c 6c es.was also call
6f80: 65 64 20 55 43 53 2d 32 2e 20 4c 65 73 73 20 66 ed UCS-2. Less f
6f90: 6f 72 6d 61 6c 6c 79 2c 20 62 75 74 20 76 65 72 ormally, but ver
6fa0: 79 20 63 6f 6d 6d 6f 6e 6c 79 20 74 68 65 20 63 y commonly the c
6fb0: 68 61 72 61 63 74 65 72 0a 73 65 74 20 55 43 53 haracter.set UCS
6fc0: 2d 32 20 77 61 73 20 63 61 6c 6c 65 64 20 22 55 -2 was called "U
6fd0: 6e 69 63 6f 64 65 22 2c 20 61 6e 64 20 74 77 6f nicode", and two
6fe0: 2d 62 79 74 65 20 63 6f 64 65 70 6f 69 6e 74 20 -byte codepoint
6ff0: 76 61 6c 75 65 73 20 77 65 72 65 20 63 61 6c 6c values were call
7000: 65 64 0a 22 55 6e 69 63 6f 64 65 20 63 68 61 72 ed."Unicode char
7010: 61 63 74 65 72 73 22 2c 20 65 6d 70 68 61 73 69 acters", emphasi
7020: 7a 69 6e 67 20 74 68 65 20 6d 75 63 68 20 73 6d zing the much sm
7030: 61 6c 6c 65 72 20 74 61 62 6c 65 2c 20 61 6e 64 aller table, and
7040: 20 73 6d 61 6c 6c 65 72 0a 63 6f 64 65 70 6f 69 smaller.codepoi
7050: 6e 74 73 20 6f 66 20 74 68 65 20 55 6e 69 63 6f nts of the Unico
7060: 64 65 20 70 72 6f 6a 65 63 74 2e 20 54 68 65 20 de project. The
7070: 6e 6f 74 61 74 69 6f 6e 20 2a 2a 55 2b 5f 48 48 notation **U+_HH
7080: 48 48 5f 2a 2a 20 66 6f 72 20 63 6f 64 65 70 6f HH_** for codepo
7090: 69 6e 74 0a 76 61 6c 75 65 73 20 77 61 73 20 61 int.values was a
70a0: 6c 73 6f 20 69 6e 20 75 73 65 2e 20 49 6e 20 74 lso in use. In t
70b0: 68 65 20 6d 69 64 2d 31 39 39 30 73 2c 20 6e 6f he mid-1990s, no
70c0: 20 63 6f 64 65 70 6f 69 6e 74 73 20 6f 75 74 73 codepoints outs
70d0: 69 64 65 20 55 43 53 2d 32 0a 77 65 72 65 20 61 ide UCS-2.were a
70e0: 73 73 69 67 6e 65 64 20 62 79 20 65 69 74 68 65 ssigned by eithe
70f0: 72 20 55 43 53 20 70 72 6f 6a 65 63 74 2e 0a 0a r UCS project...
7100: 41 74 20 74 68 65 20 74 69 6d 65 2c 20 61 20 6d At the time, a m
7110: 69 67 72 61 74 69 6f 6e 20 61 77 61 79 20 66 72 igration away fr
7120: 6f 6d 20 73 69 6e 67 6c 65 2d 62 79 74 65 20 65 om single-byte e
7130: 6e 63 6f 64 69 6e 67 73 20 6c 69 6b 65 20 41 53 ncodings like AS
7140: 43 49 49 0a 6f 72 20 49 53 4f 2d 38 38 35 39 2d CII.or ISO-8859-
7150: 31 20 74 6f 20 65 69 74 68 65 72 20 55 43 53 2d 1 to either UCS-
7160: 32 20 6f 72 20 55 43 53 2d 34 20 77 61 73 20 61 2 or UCS-4 was a
7170: 20 74 6f 75 67 68 20 73 65 6c 6c 2e 20 41 20 64 tough sell. A d
7180: 6f 75 62 6c 69 6e 67 0a 6f 72 20 71 75 61 64 72 oubling.or quadr
7190: 75 70 6c 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 upling of memory
71a0: 20 61 6e 64 20 6e 65 74 77 6f 72 6b 20 74 72 61 and network tra
71b0: 66 66 69 63 20 72 65 71 75 69 72 65 6d 65 6e 74 ffic requirement
71c0: 73 20 66 6f 72 20 74 68 65 20 73 61 6b 65 0a 6f s for the sake.o
71d0: 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 68 61 f additional cha
71e0: 72 61 63 74 65 72 73 20 74 68 61 74 20 6d 61 6e racters that man
71f0: 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 68 y applications h
7200: 61 64 20 6e 6f 20 6e 65 65 64 20 74 6f 20 68 61 ad no need to ha
7210: 6e 64 6c 65 0a 77 61 73 20 6e 6f 74 20 61 20 77 ndle.was not a w
7220: 65 6c 63 6f 6d 65 20 70 72 6f 70 6f 73 69 74 69 elcome propositi
7230: 6f 6e 2e 20 49 74 20 77 61 73 20 63 6c 65 61 72 on. It was clear
7240: 20 74 68 61 74 20 61 20 76 61 72 69 61 62 6c 65 that a variable
7250: 2d 6c 65 6e 67 74 68 20 65 6e 63 6f 64 69 6e 67 -length encoding
7260: 0a 74 68 61 74 20 62 65 74 74 65 72 20 6d 61 6e .that better man
7270: 61 67 65 64 20 74 68 65 20 63 6f 73 74 73 20 69 aged the costs i
7280: 6e 76 6f 6c 76 65 64 20 77 6f 75 6c 64 20 62 65 nvolved would be
7290: 20 6e 65 65 64 65 64 2e 20 41 70 70 65 6e 64 69 needed. Appendi
72a0: 78 20 46 20 6f 66 20 54 68 65 0a 55 6e 69 63 6f x F of The.Unico
72b0: 64 65 20 53 74 61 6e 64 61 72 64 2c 20 56 65 72 de Standard, Ver
72c0: 73 69 6f 6e 20 31 2e 31 20 28 31 39 39 33 29 20 sion 1.1 (1993)
72d0: 63 6f 6e 74 61 69 6e 73 20 61 20 64 65 73 63 72 contains a descr
72e0: 69 70 74 69 6f 6e 20 6f 66 0a 77 68 61 74 20 77 iption of.what w
72f0: 61 73 20 63 61 6c 6c 65 64 20 74 68 65 20 46 69 as called the Fi
7300: 6c 65 20 53 79 73 74 65 6d 20 53 61 66 65 20 55 le System Safe U
7310: 43 53 20 54 72 61 6e 73 66 6f 72 6d 61 74 69 6f CS Transformatio
7320: 6e 20 46 6f 72 6d 61 74 20 28 46 53 53 2d 55 54 n Format (FSS-UT
7330: 46 29 2e 0a 46 53 53 2d 55 54 46 20 69 73 20 61 F)..FSS-UTF is a
7340: 20 76 61 72 69 61 62 6c 65 2d 6c 65 6e 67 74 68 variable-length
7350: 20 62 79 74 65 2d 6f 72 69 65 6e 74 65 64 20 65 byte-oriented e
7360: 6e 63 6f 64 69 6e 67 20 6f 66 20 55 43 53 20 63 ncoding of UCS c
7370: 6f 64 65 70 6f 69 6e 74 73 2e 0a 54 68 65 20 69 odepoints..The i
7380: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 6f mplementation co
7390: 64 65 20 69 6e 20 54 63 6c 20 38 2e 31 20 6d 6f de in Tcl 8.1 mo
73a0: 72 65 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 re closely match
73b0: 65 73 20 74 68 69 73 20 73 70 65 63 69 66 69 63 es this specific
73c0: 61 74 69 6f 6e 0a 74 68 61 6e 20 61 6e 79 74 68 ation.than anyth
73d0: 69 6e 67 20 62 65 61 72 69 6e 67 20 74 68 65 20 ing bearing the
73e0: 6e 61 6d 65 20 55 54 46 2d 38 2e 20 20 54 68 65 name UTF-8. The
73f0: 20 65 6e 63 6f 64 69 6e 67 20 72 75 6c 65 73 20 encoding rules
7400: 6f 66 20 46 53 53 2d 55 54 46 20 61 72 65 0a 73 of FSS-UTF are.s
7410: 75 6d 6d 61 72 69 7a 65 64 20 69 6e 20 74 68 65 ummarized in the
7420: 20 74 61 62 6c 65 0a 0a 3c 70 72 65 3e 0a 60 60 table..<pre>.``
7430: 60 0a 09 43 6f 64 65 70 6f 69 6e 74 73 09 09 45 `..Codepoints..E
7440: 6e 63 6f 64 69 6e 67 0a 09 2d 2d 2d 2d 2d 2d 2d ncoding..-------
7450: 2d 2d 2d 09 09 2d 2d 2d 2d 2d 2d 2d 2d 0a 09 55 ---..--------..U
7460: 2b 30 30 30 30 20 2d 20 55 2b 30 30 37 46 09 09 +0000 - U+007F..
7470: 30 62 62 62 62 62 62 62 0a 09 55 2b 30 30 38 30 0bbbbbbb..U+0080
7480: 20 2d 20 55 2b 30 37 46 46 09 09 31 31 30 62 62 - U+07FF..110bb
7490: 62 62 62 20 31 30 62 62 62 62 62 62 0a 09 55 2b bbb 10bbbbbb..U+
74a0: 30 38 30 30 20 2d 20 55 2b 46 46 46 46 09 09 31 0800 - U+FFFF..1
74b0: 31 31 30 62 62 62 62 20 28 31 30 62 62 62 62 62 110bbbb (10bbbbb
74c0: 62 29 32 0a 0a 09 55 2b 30 30 30 31 30 30 30 30 b)2...U+00010000
74d0: 20 2d 20 55 2b 30 30 31 46 46 46 46 46 09 31 31 - U+001FFFFF.11
74e0: 31 31 30 62 62 62 20 28 31 30 62 62 62 62 62 62 110bbb (10bbbbbb
74f0: 29 33 0a 09 55 2b 30 30 32 30 30 30 30 30 20 2d )3..U+00200000 -
7500: 20 55 2b 30 33 46 46 46 46 46 46 09 31 31 31 31 U+03FFFFFF.1111
7510: 31 30 62 62 20 28 31 30 62 62 62 62 62 62 29 34 10bb (10bbbbbb)4
7520: 0a 09 55 2b 30 34 30 30 30 30 30 30 20 2d 20 55 ..U+04000000 - U
7530: 2b 37 46 46 46 46 46 46 46 09 31 31 31 31 31 31 +7FFFFFFF.111111
7540: 30 62 20 28 31 30 62 62 62 62 62 62 29 35 0a 60 0b (10bbbbbb)5.`
7550: 60 60 0a 3c 2f 70 72 65 3e 0a 0a 46 53 53 2d 55 ``.</pre>..FSS-U
7560: 54 46 20 65 6e 63 6f 64 65 73 20 65 61 63 68 20 TF encodes each
7570: 63 6f 64 65 70 6f 69 6e 74 20 69 6e 20 74 68 65 codepoint in the
7580: 20 41 53 43 49 49 20 72 61 6e 67 65 20 61 73 20 ASCII range as
7590: 61 20 73 69 6e 67 6c 65 2d 62 79 74 65 2c 0a 74 a single-byte,.t
75a0: 68 65 20 73 61 6d 65 20 62 79 74 65 20 61 6c 72 he same byte alr
75b0: 65 61 64 79 20 75 73 65 64 20 62 79 20 41 53 43 eady used by ASC
75c0: 49 49 20 66 6f 72 20 74 68 61 74 20 63 68 61 72 II for that char
75d0: 61 63 74 65 72 2e 20 20 4c 6f 6e 67 65 72 20 62 acter. Longer b
75e0: 79 74 65 20 73 65 71 65 75 6e 63 65 73 0a 65 6e yte seqeunces.en
75f0: 63 6f 64 65 20 68 69 67 68 65 72 20 63 6f 64 65 code higher code
7600: 70 6f 69 6e 74 73 20 74 68 61 74 20 77 65 72 65 points that were
7610: 20 6c 65 73 73 20 66 72 65 71 75 65 6e 74 6c 79 less frequently
7620: 20 75 73 65 64 2e 20 20 41 20 66 6f 6f 74 6e 6f used. A footno
7630: 74 65 0a 69 6e 20 41 70 70 65 6e 64 69 78 20 46 te.in Appendix F
7640: 20 6d 61 6b 65 73 20 74 68 65 20 6f 62 73 65 72 makes the obser
7650: 76 61 74 69 6f 6e 20 74 68 61 74 20 65 6e 63 6f vation that enco
7660: 64 65 64 20 73 65 71 75 65 6e 63 65 73 20 6f 66 ded sequences of
7670: 20 74 68 72 65 65 20 62 79 74 65 73 0a 61 72 65 three bytes.are
7680: 20 73 75 66 66 69 63 69 65 6e 74 20 74 6f 20 63 sufficient to c
7690: 6f 76 65 72 20 61 6c 6c 20 31 36 2d 62 69 74 20 over all 16-bit
76a0: 63 6f 64 65 70 6f 69 6e 74 73 20 6f 66 20 55 43 codepoints of UC
76b0: 53 2d 32 20 28 55 6e 69 63 6f 64 65 29 2e 20 54 S-2 (Unicode). T
76c0: 68 65 0a 6c 6f 6e 67 65 72 20 65 6e 63 6f 64 69 he.longer encodi
76d0: 6e 67 73 20 6f 66 20 66 6f 75 72 20 74 68 72 6f ngs of four thro
76e0: 75 67 68 20 73 69 78 20 62 79 74 65 73 20 70 72 ugh six bytes pr
76f0: 65 70 61 72 65 64 20 74 68 65 20 77 61 79 20 74 epared the way t
7700: 6f 20 63 6f 76 65 72 0a 63 6f 64 65 70 6f 69 6e o cover.codepoin
7710: 74 73 20 69 6e 20 55 43 53 2d 34 20 75 70 20 74 ts in UCS-4 up t
7720: 6f 20 33 31 20 62 69 74 73 2e 0a 0a 28 53 69 64 o 31 bits...(Sid
7730: 65 20 6f 62 73 65 72 76 61 74 69 6f 6e 3a 20 69 e observation: i
7740: 74 20 77 6f 75 6c 64 20 62 65 0a 73 74 72 61 69 t would be.strai
7750: 67 68 74 66 6f 72 77 61 72 64 20 74 6f 20 63 6f ghtforward to co
7760: 6e 74 69 6e 75 65 20 74 68 65 20 74 61 62 6c 65 ntinue the table
7770: 20 6f 66 20 65 6e 63 6f 64 69 6e 67 20 72 75 6c of encoding rul
7780: 65 73 20 62 79 20 6f 6e 65 20 6d 6f 72 65 0a 6c es by one more.l
7790: 69 6e 65 2c 20 75 73 69 6e 67 20 74 68 65 20 6c ine, using the l
77a0: 65 61 64 20 62 79 74 65 20 2a 2a 30 78 46 45 2a ead byte **0xFE*
77b0: 2a 20 74 6f 20 69 6e 74 72 6f 64 75 63 65 20 61 * to introduce a
77c0: 20 73 65 71 75 65 6e 63 65 20 6f 66 20 73 69 78 sequence of six
77d0: 20 74 72 61 69 6c 0a 62 79 74 65 73 2e 20 54 68 trail.bytes. Th
77e0: 69 73 20 77 6f 75 6c 64 20 62 65 20 61 20 73 65 is would be a se
77f0: 76 65 6e 20 62 79 74 65 20 65 6e 63 6f 64 69 6e ven byte encodin
7800: 67 20 74 68 61 74 20 63 6f 75 6c 64 20 65 6e 63 g that could enc
7810: 6f 64 65 20 75 70 20 74 6f 20 33 36 20 62 69 74 ode up to 36 bit
7820: 73 2c 0a 65 61 73 69 6c 79 20 63 6f 76 65 72 69 s,.easily coveri
7830: 6e 67 20 74 68 65 20 72 65 6d 61 69 6e 64 65 72 ng the remainder
7840: 20 6f 66 20 74 68 65 20 33 32 2d 62 69 74 20 72 of the 32-bit r
7850: 61 6e 67 65 20 6f 66 20 61 6c 6c 20 6f 66 20 55 ange of all of U
7860: 43 53 2d 34 2e 20 20 49 74 20 0a 73 65 65 6d 73 CS-4. It .seems
7870: 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 6b 65 the value of ke
7880: 65 70 69 6e 67 20 62 79 74 65 20 2a 2a 30 78 46 eping byte **0xF
7890: 45 2a 2a 20 6f 75 74 20 6f 66 20 65 6e 63 6f 64 E** out of encod
78a0: 65 64 20 73 74 72 65 61 6d 73 20 6f 75 74 77 65 ed streams outwe
78b0: 69 67 68 65 64 0a 74 68 65 20 66 61 69 6c 75 72 ighed.the failur
78c0: 65 20 74 6f 20 65 6e 63 6f 64 65 20 74 68 65 20 e to encode the
78d0: 75 70 70 65 72 20 68 61 6c 66 20 6f 66 20 55 43 upper half of UC
78e0: 53 2d 34 2c 20 77 68 69 63 68 20 68 61 64 20 6e S-4, which had n
78f0: 6f 20 66 6f 72 73 65 65 61 62 6c 65 20 75 73 65 o forseeable use
7900: 2e 0a 54 68 65 20 62 79 74 65 73 20 2a 2a 30 78 ..The bytes **0x
7910: 46 45 2a 2a 20 61 6e 64 20 2a 2a 30 78 46 46 2a FE** and **0xFF*
7920: 2a 20 74 6f 67 65 74 68 65 72 20 6d 61 6b 65 20 * together make
7930: 75 70 20 61 20 42 79 74 65 20 4f 72 64 65 72 20 up a Byte Order
7940: 4d 61 72 6b 20 74 68 61 74 0a 69 73 20 75 73 65 Mark that.is use
7950: 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 65 d to determine e
7960: 6e 64 69 61 6e 6e 65 73 73 20 6f 66 20 55 43 53 ndianness of UCS
7970: 2d 32 20 64 61 74 61 2e 20 57 68 65 6e 20 6e 65 -2 data. When ne
7980: 69 74 68 65 72 20 62 79 74 65 20 61 70 70 65 61 ither byte appea
7990: 72 73 0a 69 6e 20 55 54 46 2d 38 20 6f 72 20 46 rs.in UTF-8 or F
79a0: 53 53 2d 55 54 46 20 74 68 65 20 63 6f 6e 66 69 SS-UTF the confi
79b0: 64 65 6e 63 65 20 6f 66 20 74 68 61 74 20 69 6e dence of that in
79c0: 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
79d0: 62 6f 6c 64 65 6e 65 64 2e 29 0a 0a 49 6e 20 54 boldened.)..In T
79e0: 63 6c 20 38 2e 31 2c 20 65 6e 63 6f 64 69 6e 67 cl 8.1, encoding
79f0: 20 6f 66 20 55 6e 69 63 6f 64 65 20 63 6f 64 65 of Unicode code
7a00: 70 6f 69 6e 74 73 20 69 73 20 61 63 63 6f 6d 70 points is accomp
7a10: 6c 69 73 68 65 64 20 62 79 20 74 68 65 20 72 6f lished by the ro
7a20: 75 74 69 6e 65 0a 0a 3e 09 2a 2a 69 6e 74 2a 2a utine..>.**int**
7a30: 20 2a 2a 54 63 6c 5f 55 6e 69 43 68 61 72 54 6f **Tcl_UniCharTo
7a40: 55 74 66 2a 2a 20 28 20 2a 2a 69 6e 74 2a 2a 20 Utf** ( **int**
7a50: 2a 63 68 2a 2c 20 2a 2a 63 68 61 72 2a 2a 20 2a *ch*, **char** *
7a60: 5f 73 74 72 5f 29 3b 0a 0a 54 68 65 20 72 6f 75 _str_);..The rou
7a70: 74 69 6e 65 20 69 73 20 28 6e 65 61 72 6c 79 29 tine is (nearly)
7a80: 20 61 20 64 69 72 65 63 74 20 74 72 61 6e 73 6c a direct transl
7a90: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 74 61 62 ation of the tab
7aa0: 6c 65 20 6f 66 20 65 6e 63 6f 64 69 6e 67 20 72 le of encoding r
7ab0: 75 6c 65 73 0a 6f 66 20 46 53 53 2d 55 54 46 2e ules.of FSS-UTF.
7ac0: 20 20 48 6f 77 65 76 65 72 20 69 74 20 69 73 20 However it is
7ad0: 63 6c 65 61 72 20 74 68 61 74 20 61 20 64 65 63 clear that a dec
7ae0: 69 73 69 6f 6e 20 77 61 73 20 6d 61 64 65 20 74 ision was made t
7af0: 68 61 74 20 54 63 6c 20 77 6f 75 6c 64 0a 73 75 hat Tcl would.su
7b00: 70 70 6f 72 74 20 22 55 6e 69 63 6f 64 65 22 20 pport "Unicode"
7b10: 77 68 69 63 68 20 6d 65 61 6e 74 20 55 43 53 2d which meant UCS-
7b20: 32 20 77 68 69 63 68 20 6d 65 61 6e 74 20 31 36 2 which meant 16
7b30: 2d 62 69 74 20 63 6f 64 65 70 6f 69 6e 74 73 20 -bit codepoints
7b40: 61 73 0a 22 55 6e 69 63 6f 64 65 20 63 68 61 72 as."Unicode char
7b50: 61 63 74 65 72 73 22 2e 20 20 55 6e 69 63 6f 64 acters". Unicod
7b60: 65 20 63 68 61 72 61 63 74 65 72 73 20 72 65 71 e characters req
7b70: 75 69 72 65 20 61 20 6d 61 78 69 6d 75 6d 20 6f uire a maximum o
7b80: 66 0a 74 68 72 65 65 20 65 6e 63 6f 64 65 64 20 f.three encoded
7b90: 62 79 74 65 73 2c 20 61 6e 64 20 54 63 6c 20 38 bytes, and Tcl 8
7ba0: 2e 31 20 73 6f 75 72 63 65 20 63 6f 64 65 20 75 .1 source code u
7bb0: 73 65 73 20 2a 2a 54 43 4c 5c 5f 55 54 46 5c 5f ses **TCL\_UTF\_
7bc0: 4d 41 58 2a 2a 0a 74 6f 20 72 65 70 72 65 73 65 MAX**.to represe
7bd0: 6e 74 20 74 68 61 74 20 6c 69 6d 69 74 2e 20 49 nt that limit. I
7be0: 74 20 69 73 20 75 73 65 66 75 6c 20 69 6e 20 73 t is useful in s
7bf0: 69 7a 69 6e 67 20 62 75 66 66 65 72 73 20 77 68 izing buffers wh
7c00: 65 72 65 20 65 6e 63 6f 64 65 64 0a 73 74 72 69 ere encoded.stri
7c10: 6e 67 73 20 61 72 65 20 74 6f 20 62 65 20 77 72 ngs are to be wr
7c20: 69 74 74 65 6e 2e 20 20 54 68 65 20 70 75 62 6c itten. The publ
7c30: 69 63 20 68 65 61 64 65 72 20 66 6f 72 20 54 63 ic header for Tc
7c40: 6c 20 38 2e 31 20 69 6e 63 6c 75 64 65 73 0a 0a l 8.1 includes..
7c50: 3e 09 5c 23 64 65 66 69 6e 65 20 2a 2a 54 43 4c >.\#define **TCL
7c60: 5c 5f 55 54 46 5c 5f 4d 41 58 2a 2a 09 33 0a 0a \_UTF\_MAX**.3..
7c70: 61 6e 64 0a 0a 3e 09 74 79 70 65 64 65 66 20 2a and..>.typedef *
7c80: 2a 75 6e 73 69 67 6e 65 64 20 73 68 6f 72 74 20 *unsigned short
7c90: 54 63 6c 5f 55 6e 69 43 68 61 72 2a 2a 3b 0a 0a Tcl_UniChar**;..
7ca0: 48 6f 77 65 76 65 72 2c 20 74 68 65 20 62 6f 64 However, the bod
7cb0: 79 20 6f 66 20 2a 2a 54 63 6c 5f 55 6e 69 43 68 y of **Tcl_UniCh
7cc0: 61 72 54 6f 55 74 66 2a 2a 20 69 6e 63 6c 75 64 arToUtf** includ
7cd0: 65 73 20 63 6f 64 65 20 74 6f 0a 65 6e 63 6f 64 es code to.encod
7ce0: 65 20 75 70 20 74 6f 20 73 69 78 2d 62 79 74 65 e up to six-byte
7cf0: 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 70 72 sequences as pr
7d00: 65 73 63 72 69 62 65 64 20 62 79 20 46 53 53 2d escribed by FSS-
7d10: 55 54 46 20 72 65 70 72 65 73 65 6e 74 69 6e 67 UTF representing
7d20: 0a 75 70 20 74 6f 20 33 31 2d 62 69 74 20 63 6f .up to 31-bit co
7d30: 64 65 70 6f 69 6e 74 73 2c 20 70 72 6f 74 65 63 depoints, protec
7d40: 74 65 64 20 62 79 20 61 20 63 6f 6e 64 69 74 69 ted by a conditi
7d50: 6f 6e 61 6c 20 63 6f 6d 70 69 6c 65 72 20 64 69 onal compiler di
7d60: 72 65 63 74 69 76 65 0a 0a 3e 09 5c 23 69 66 20 rective..>.\#if
7d70: 2a 2a 54 43 4c 5c 5f 55 54 46 5c 5f 4d 41 58 2a **TCL\_UTF\_MAX*
7d80: 2a 20 3e 20 33 20 2e 0a 0a 57 69 74 68 20 74 68 * > 3 ...With th
7d90: 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
7da0: 67 2c 20 54 63 6c 20 69 73 20 61 62 6c 65 20 74 g, Tcl is able t
7db0: 6f 20 65 6e 63 6f 64 65 20 61 20 74 6f 74 61 6c o encode a total
7dc0: 20 6f 66 20 36 35 2c 35 33 36 0a 64 69 73 74 69 of 65,536.disti
7dd0: 6e 63 74 20 76 61 6c 75 65 73 20 6f 66 20 74 68 nct values of th
7de0: 65 20 2a 63 68 2a 20 63 6f 64 65 70 6f 69 6e 74 e *ch* codepoint
7df0: 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 73 65 argument. These
7e00: 20 61 72 65 20 61 6c 6c 20 74 68 65 0a 63 6f 64 are all the.cod
7e10: 65 70 6f 69 6e 74 73 20 6f 66 20 55 43 53 2d 32 epoints of UCS-2
7e20: 2c 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 63 , the complete c
7e30: 61 70 61 63 69 74 79 20 6f 66 20 55 6e 69 63 6f apacity of Unico
7e40: 64 65 20 31 2e 31 2e 20 57 68 65 6e 0a 2a 2a 54 de 1.1. When.**T
7e50: 63 6c 5f 55 6e 69 43 68 61 72 54 6f 55 74 66 2a cl_UniCharToUtf*
7e60: 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 2a 63 * is passed a *c
7e70: 68 2a 20 61 72 67 75 6d 65 6e 74 20 6f 75 74 73 h* argument outs
7e80: 69 64 65 20 74 68 61 74 20 73 75 70 70 6f 72 74 ide that support
7e90: 65 64 0a 72 61 6e 67 65 2c 20 74 68 65 20 63 6f ed.range, the co
7ea0: 64 65 70 6f 69 6e 74 20 2a 2a 55 2b 46 46 46 44 depoint **U+FFFD
7eb0: 2a 2a 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e ** is encoded in
7ec0: 20 69 74 73 20 70 6c 61 63 65 2e 20 55 6e 69 63 its place. Unic
7ed0: 6f 64 65 20 31 2e 31 0a 61 73 73 69 67 6e 73 20 ode 1.1.assigns
7ee0: 74 68 69 73 20 63 6f 64 65 70 6f 69 6e 74 20 74 this codepoint t
7ef0: 68 65 20 6e 61 6d 65 20 2a 2a 52 45 50 4c 41 43 he name **REPLAC
7f00: 45 4d 45 4e 54 20 43 48 41 52 41 43 54 45 52 2a EMENT CHARACTER*
7f10: 2a 2e 20 55 6e 69 63 6f 64 65 0a 70 72 65 73 63 *. Unicode.presc
7f20: 72 69 62 65 73 20 74 68 65 20 75 73 65 20 6f 66 ribes the use of
7f30: 20 2a 2a 55 2b 46 46 46 44 2a 2a 20 74 6f 20 72 **U+FFFD** to r
7f40: 65 70 6c 61 63 65 20 61 6e 20 69 6e 63 6f 6d 69 eplace an incomi
7f50: 6e 67 20 63 68 61 72 61 63 74 65 72 0a 77 68 6f ng character.who
7f60: 73 65 20 76 61 6c 75 65 20 69 73 20 75 6e 72 65 se value is unre
7f70: 70 72 65 73 65 6e 74 61 62 6c 65 2e 20 20 49 6e presentable. In
7f80: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e a configuration
7f90: 20 6f 66 20 54 63 6c 20 38 2e 31 20 77 69 74 68 of Tcl 8.1 with
7fa0: 0a 2a 2a 54 43 4c 5c 5f 55 54 46 5c 5f 4d 41 58 .**TCL\_UTF\_MAX
7fb0: 2a 2a 20 73 65 74 20 74 6f 20 36 2c 20 74 68 65 ** set to 6, the
7fc0: 20 2a 2a 52 45 50 4c 41 43 45 4d 45 4e 54 20 43 **REPLACEMENT C
7fd0: 48 41 52 41 43 54 45 52 2a 2a 20 77 6f 75 6c 64 HARACTER** would
7fe0: 0a 72 65 70 6c 61 63 65 20 6f 6e 6c 79 20 74 68 .replace only th
7ff0: 65 20 2a 63 68 2a 20 76 61 6c 75 65 73 20 69 6e e *ch* values in
8000: 20 74 68 65 20 75 70 70 65 72 20 68 61 6c 66 20 the upper half
8010: 6f 66 20 55 43 53 2d 34 2e 20 20 4e 6f 74 65 20 of UCS-4. Note
8020: 74 68 61 74 0a 54 63 6c 20 38 2e 31 20 68 61 73 that.Tcl 8.1 has
8030: 20 6d 61 64 65 20 61 20 64 65 73 69 67 6e 20 63 made a design c
8040: 68 6f 69 63 65 20 68 65 72 65 20 74 6f 20 68 61 hoice here to ha
8050: 6e 64 6c 65 20 75 6e 73 75 70 70 6f 72 74 65 64 ndle unsupported
8060: 20 69 6e 70 75 74 73 0a 76 69 61 20 72 65 70 6c inputs.via repl
8070: 61 63 65 6d 65 6e 74 2c 20 61 6e 64 20 6e 6f 74 acement, and not
8080: 20 76 69 61 20 72 61 69 73 69 6e 67 20 61 6e 20 via raising an
8090: 65 72 72 6f 72 2e 0a 0a 49 74 20 69 73 20 63 6c error...It is cl
80a0: 65 61 72 20 74 68 61 74 20 74 68 65 20 55 6e 69 ear that the Uni
80b0: 63 6f 64 65 20 73 75 70 70 6f 72 74 20 70 72 6f code support pro
80c0: 76 69 64 65 64 20 62 79 20 54 63 6c 20 38 2e 31 vided by Tcl 8.1
80d0: 20 77 61 73 20 69 6e 74 65 6e 74 69 6f 6e 61 6c was intentional
80e0: 6c 79 0a 6c 69 6d 69 74 65 64 20 74 6f 20 55 43 ly.limited to UC
80f0: 53 2d 32 2c 20 77 68 69 6c 65 20 63 6f 6e 76 65 S-2, while conve
8100: 6e 74 69 6f 6e 73 20 61 6e 64 20 6d 69 67 72 61 ntions and migra
8110: 74 69 6f 6e 20 73 75 70 70 6f 72 74 73 20 77 65 tion supports we
8120: 72 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 0a re put in place.
8130: 73 6f 20 74 68 61 74 20 61 20 66 75 74 75 72 65 so that a future
8140: 20 28 62 69 6e 61 72 79 20 69 6e 63 6f 6d 70 61 (binary incompa
8150: 74 69 62 6c 65 29 20 76 65 72 73 69 6f 6e 20 6f tible) version o
8160: 66 20 54 63 6c 20 77 6f 75 6c 64 20 65 78 70 61 f Tcl would expa
8170: 6e 64 20 69 74 73 20 73 75 70 70 6f 72 74 0a 74 nd its support.t
8180: 6f 20 55 43 53 2d 34 20 77 69 74 68 20 46 53 53 o UCS-4 with FSS
8190: 2d 55 54 46 20 65 6e 63 6f 64 69 6e 67 20 73 65 -UTF encoding se
81a0: 71 75 65 6e 63 65 73 20 6f 66 20 75 70 20 74 6f quences of up to
81b0: 20 73 69 78 20 62 79 74 65 73 2c 20 61 74 20 73 six bytes, at s
81c0: 6f 6d 65 20 70 6f 69 6e 74 0a 77 68 65 72 65 20 ome point.where
81d0: 74 68 65 20 63 6f 6e 73 69 64 65 72 61 62 6c 65 the considerable
81e0: 20 63 6f 73 74 20 69 6e 20 6d 65 6d 6f 72 79 20 cost in memory
81f0: 61 6e 64 20 70 72 6f 63 65 73 73 69 6e 67 20 62 and processing b
8200: 75 72 64 65 6e 20 74 72 61 64 65 64 20 6f 66 66 urden traded off
8210: 0a 61 67 61 69 6e 73 74 20 74 68 65 20 62 65 6e .against the ben
8220: 65 66 69 74 73 20 6f 66 20 73 75 70 70 6f 72 74 efits of support
8230: 20 66 6f 72 20 77 68 61 74 65 76 65 72 20 66 75 for whatever fu
8240: 74 75 72 65 20 63 6f 64 65 70 6f 69 6e 74 20 61 ture codepoint a
8250: 73 73 69 67 6e 6d 65 6e 74 73 0a 6f 75 74 73 69 ssignments.outsi
8260: 64 65 20 6f 66 20 55 43 53 2d 32 20 63 6f 6d 70 de of UCS-2 comp
8270: 65 6c 6c 65 64 20 73 75 70 70 6f 72 74 2e 0a 0a elled support...
8280: 54 68 65 20 63 61 70 61 63 69 74 79 20 6f 66 20 The capacity of
8290: 55 43 53 2d 32 20 69 73 20 61 20 74 61 62 6c 65 UCS-2 is a table
82a0: 20 6f 66 20 36 35 2c 35 33 36 20 63 6f 64 65 70 of 65,536 codep
82b0: 6f 69 6e 74 73 2e 20 48 6f 77 65 76 65 72 2c 20 oints. However,
82c0: 55 6e 69 63 6f 64 65 20 31 2e 31 0a 61 73 73 69 Unicode 1.1.assi
82d0: 67 6e 73 20 63 68 61 72 61 63 74 65 72 73 20 74 gns characters t
82e0: 6f 20 6f 6e 6c 79 20 34 30 2c 36 33 35 20 72 6f o only 40,635 ro
82f0: 77 73 20 69 6e 20 74 68 61 74 20 74 61 62 6c 65 ws in that table
8300: 2e 20 49 66 20 77 65 20 67 65 6e 65 72 61 74 65 . If we generate
8310: 20 61 6c 6c 0a 70 6f 73 73 69 62 6c 65 20 73 65 all.possible se
8320: 71 75 65 6e 63 65 73 20 6f 66 20 74 68 6f 73 65 quences of those
8330: 20 34 30 2c 36 33 35 20 61 73 73 69 67 6e 65 64 40,635 assigned
8340: 20 63 6f 64 65 70 6f 69 6e 74 73 2c 20 61 6e 64 codepoints, and
8350: 20 74 68 65 6e 20 65 6e 63 6f 64 65 0a 65 61 63 then encode.eac
8360: 68 20 73 65 71 75 65 6e 63 65 20 76 69 61 20 74 h sequence via t
8370: 68 65 20 46 53 53 2d 55 54 46 20 72 75 6c 65 73 he FSS-UTF rules
8380: 2c 20 77 65 20 67 65 6e 65 72 61 74 65 20 61 20 , we generate a
8390: 73 65 74 20 6f 66 20 62 79 74 65 20 73 65 71 75 set of byte sequ
83a0: 65 6e 63 65 73 0a 66 61 72 20 73 6d 61 6c 6c 65 ences.far smalle
83b0: 72 20 61 6e 64 20 6d 6f 72 65 20 63 6f 6e 73 74 r and more const
83c0: 72 61 69 6e 65 64 20 74 68 61 74 20 74 68 65 20 rained that the
83d0: 67 65 6e 65 72 61 6c 20 73 65 74 20 6f 66 20 61 general set of a
83e0: 6c 6c 20 62 79 74 65 20 73 65 71 75 65 6e 63 65 ll byte sequence
83f0: 73 2e 0a 57 68 65 6e 20 77 65 20 63 6c 61 69 6d s..When we claim
8400: 20 74 68 61 74 20 54 63 6c 20 38 2e 31 20 73 74 that Tcl 8.1 st
8410: 72 69 6e 67 73 20 61 72 65 20 6b 65 70 74 20 69 rings are kept i
8420: 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f n the UTF-8 enco
8430: 64 69 6e 67 2c 20 77 65 0a 69 6d 70 6c 79 20 74 ding, we.imply t
8440: 68 61 74 20 54 63 6c 20 38 2e 31 20 73 74 72 69 hat Tcl 8.1 stri
8450: 6e 67 73 20 61 72 65 20 63 6f 6e 73 74 72 61 69 ngs are constrai
8460: 6e 65 64 20 74 6f 20 61 20 6d 75 63 68 20 73 6d ned to a much sm
8470: 61 6c 6c 65 72 20 73 65 74 20 6f 66 20 62 79 74 aller set of byt
8480: 65 0a 73 65 71 75 65 6e 63 65 73 20 74 68 61 6e e.sequences than
8490: 20 77 65 72 65 20 70 65 72 6d 69 74 74 65 64 20 were permitted
84a0: 66 6f 72 20 54 63 6c 20 38 2e 30 20 73 74 72 69 for Tcl 8.0 stri
84b0: 6e 67 73 2e 20 20 54 68 69 73 20 72 61 69 73 65 ngs. This raise
84c0: 73 20 71 75 65 73 74 69 6f 6e 73 0a 61 62 6f 75 s questions.abou
84d0: 74 20 62 6f 74 68 20 63 6f 6d 70 61 74 69 62 69 t both compatibi
84e0: 6c 69 74 79 20 61 6e 64 20 77 68 61 74 20 61 20 lity and what a
84f0: 64 65 63 6f 64 65 72 20 73 68 6f 75 6c 64 20 64 decoder should d
8500: 6f 20 77 69 74 68 20 61 20 6e 6f 6e 2d 63 6f 6e o with a non-con
8510: 66 6f 72 6d 61 6e 74 0a 62 79 74 65 20 73 65 71 formant.byte seq
8520: 75 65 6e 63 65 2e 0a 0a 49 74 20 69 73 20 61 6e uence...It is an
8530: 20 65 78 70 65 63 74 65 64 20 66 65 61 74 75 72 expected featur
8540: 65 20 6f 66 20 74 68 65 20 55 6e 69 63 6f 64 65 e of the Unicode
8550: 20 63 68 61 72 61 63 74 65 72 20 73 65 74 20 74 character set t
8560: 68 61 74 20 6d 6f 72 65 20 63 68 61 72 61 63 74 hat more charact
8570: 65 72 73 0a 61 72 65 20 74 6f 20 62 65 20 61 64 ers.are to be ad
8580: 64 65 64 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 ded over time.
8590: 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 73 The number of as
85a0: 73 69 67 6e 65 64 20 63 6f 64 65 70 6f 69 6e 74 signed codepoint
85b0: 73 20 67 72 6f 77 73 20 61 73 20 6e 65 77 0a 76 s grows as new.v
85c0: 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 20 55 ersions of the U
85d0: 6e 69 63 6f 64 65 20 73 74 61 6e 64 61 72 64 20 nicode standard
85e0: 61 72 65 20 63 6f 64 69 66 69 65 64 20 61 6e 64 are codified and
85f0: 20 70 75 62 6c 69 73 68 65 64 2e 20 20 42 65 63 published. Bec
8600: 61 75 73 65 0a 73 75 70 70 6f 72 74 20 66 6f 72 ause.support for
8610: 20 73 74 61 6e 64 61 72 64 73 20 61 6c 77 61 79 standards alway
8620: 73 20 6c 61 67 73 20 74 68 65 69 72 20 70 75 62 s lags their pub
8630: 6c 69 63 61 74 69 6f 6e 2c 20 73 6f 66 74 77 61 lication, softwa
8640: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 0a 63 6f re written in.co
8650: 6e 66 6f 72 6d 61 6e 63 65 20 74 6f 20 6f 6e 65 nformance to one
8660: 20 76 65 72 73 69 6f 6e 20 6f 66 20 55 6e 69 63 version of Unic
8670: 6f 64 65 20 69 73 20 6c 69 6b 65 6c 79 20 74 6f ode is likely to
8680: 20 65 6e 63 6f 75 6e 74 65 72 20 64 61 74 61 20 encounter data
8690: 70 72 6f 64 75 63 65 64 0a 69 6e 20 63 6f 6e 66 produced.in conf
86a0: 6f 72 6d 61 6e 63 65 20 74 6f 20 61 20 6c 61 74 ormance to a lat
86b0: 65 72 20 76 65 72 73 69 6f 6e 2e 20 20 49 6e 20 er version. In
86c0: 6c 69 67 68 74 20 6f 66 20 74 68 69 73 2c 20 74 light of this, t
86d0: 68 65 20 62 65 73 74 20 70 72 61 63 74 69 63 65 he best practice
86e0: 20 69 73 0a 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 is.to accommoda
86f0: 74 65 20 61 6e 64 20 70 72 65 73 65 72 76 65 20 te and preserve
8700: 75 6e 61 73 73 69 67 6e 65 64 20 63 6f 64 65 70 unassigned codep
8710: 6f 69 6e 74 73 20 61 73 20 6d 75 63 68 20 61 73 oints as much as
8720: 20 70 6f 73 73 69 62 6c 65 2e 0a 53 6f 66 74 77 possible..Softw
8730: 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 73 are written to s
8740: 75 70 70 6f 72 74 20 55 6e 69 63 6f 64 65 20 31 upport Unicode 1
8750: 2e 31 20 63 61 6e 20 74 68 65 6e 20 61 63 63 65 .1 can then acce
8760: 70 74 20 55 6e 69 63 6f 64 65 20 32 20 64 61 74 pt Unicode 2 dat
8770: 61 20 73 74 72 65 61 6d 73 2c 70 61 73 73 20 74 a streams,pass t
8780: 68 65 6d 20 74 68 72 6f 75 67 68 20 61 6e 64 20 hem through and
8790: 6f 75 74 70 75 74 20 74 68 65 6d 20 61 67 61 69 output them agai
87a0: 6e 20 75 6e 64 61 6d 61 67 65 64 2e 20 49 6e 20 n undamaged. In
87b0: 74 68 69 73 20 77 61 79 20 61 20 6d 69 64 64 6c this way a middl
87c0: 65 77 61 72 65 0a 77 72 69 74 74 65 6e 20 74 6f eware.written to
87d0: 20 61 6e 20 6f 62 73 6f 6c 65 74 65 20 55 6e 69 an obsolete Uni
87e0: 63 6f 64 65 20 73 74 61 6e 64 61 72 64 20 63 61 code standard ca
87f0: 6e 20 73 74 69 6c 6c 20 73 75 70 70 6f 72 74 20 n still support
8800: 70 72 6f 76 69 64 65 72 73 20 61 6e 64 0a 63 6c providers and.cl
8810: 69 65 6e 74 73 20 74 68 61 74 20 73 65 65 6b 20 ients that seek
8820: 74 6f 20 75 73 65 20 63 68 61 72 61 63 74 65 72 to use character
8830: 73 20 61 73 73 69 67 6e 65 64 20 6f 6e 6c 79 20 s assigned only
8840: 69 6e 20 61 20 6c 61 74 65 72 20 73 74 61 6e 64 in a later stand
8850: 61 72 64 2e 0a 54 68 65 20 6d 69 64 64 6c 65 77 ard..The middlew
8860: 61 72 65 20 77 6f 75 6c 64 20 66 61 69 6c 20 74 are would fail t
8870: 6f 20 70 72 6f 70 65 72 6c 79 20 61 6e 73 77 65 o properly answe
8880: 72 20 61 6e 79 20 71 75 65 73 74 69 6f 6e 73 20 r any questions
8890: 61 62 6f 75 74 20 74 68 65 0a 6c 61 74 65 72 2d about the.later-
88a0: 61 73 73 69 67 6e 65 64 20 63 68 61 72 61 63 74 assigned charact
88b0: 65 72 73 2c 20 73 75 63 68 20 61 73 20 61 20 2a ers, such as a *
88c0: 2a 73 74 72 69 6e 67 20 69 73 20 61 6c 70 68 61 *string is alpha
88d0: 2a 2a 20 74 65 73 74 2c 20 62 75 74 20 63 6f 75 ** test, but cou
88e0: 6c 64 0a 73 74 69 6c 6c 20 6e 6f 74 20 62 65 20 ld.still not be
88f0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 73 65 6c immediately usel
8900: 65 73 73 2e 0a 55 6e 69 63 6f 64 65 20 31 2e 31 ess..Unicode 1.1
8910: 20 6c 65 66 74 20 6f 70 65 6e 20 74 68 65 20 70 left open the p
8920: 6f 73 73 69 62 69 6c 69 74 79 20 74 68 61 74 20 ossibility that
8930: 61 6e 79 20 63 6f 64 65 70 6f 69 6e 74 20 69 6e any codepoint in
8940: 20 55 43 53 2d 32 20 6d 69 67 68 74 0a 6f 6e 65 UCS-2 might.one
8950: 20 64 61 79 20 62 65 20 61 73 73 69 67 6e 65 64 day be assigned
8960: 2e 20 54 63 6c 20 38 2e 31 20 69 6d 70 6f 73 65 . Tcl 8.1 impose
8970: 73 20 6e 6f 20 63 6f 6e 64 69 74 69 6f 6e 73 20 s no conditions
8980: 6f 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 on the encoding
8990: 6f 66 20 61 6e 79 0a 2a 2a 54 63 6c 5f 55 6e 69 of any.**Tcl_Uni
89a0: 43 68 61 72 2a 2a 20 76 61 6c 75 65 20 61 74 20 Char** value at
89b0: 61 6c 6c 2e 0a 0a 54 68 65 20 73 74 61 6e 64 61 all...The standa
89c0: 72 64 73 20 73 70 65 63 69 66 79 69 6e 67 20 74 rds specifying t
89d0: 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 70 75 ext encodings pu
89e0: 62 6c 69 73 68 65 64 20 69 6e 20 74 68 65 20 6d blished in the m
89f0: 69 64 2d 31 39 39 30 73 20 77 65 72 65 20 71 75 id-1990s were qu
8a00: 69 74 65 0a 63 6c 65 61 72 20 61 6e 64 20 65 78 ite.clear and ex
8a10: 70 6c 69 63 69 74 20 61 62 6f 75 74 20 74 68 65 plicit about the
8a20: 20 72 69 67 68 74 20 77 61 79 20 74 6f 20 64 6f right way to do
8a30: 20 74 68 69 6e 67 73 2e 20 54 68 65 79 20 77 65 things. They we
8a40: 72 65 20 6f 66 74 65 6e 20 6c 65 73 73 0a 64 65 re often less.de
8a50: 6d 61 6e 64 69 6e 67 20 61 6e 64 20 73 70 65 63 manding and spec
8a60: 69 66 69 63 20 61 62 6f 75 74 20 68 6f 77 20 74 ific about how t
8a70: 6f 20 72 65 73 70 6f 6e 64 20 69 6e 20 74 68 65 o respond in the
8a80: 20 70 72 65 73 65 6e 63 65 20 6f 66 20 65 72 72 presence of err
8a90: 6f 72 73 2e 20 54 68 65 0a 73 70 69 72 69 74 20 ors. The.spirit
8aa0: 6f 66 20 74 68 65 20 50 6f 73 74 65 6c 20 52 6f of the Postel Ro
8ab0: 62 75 73 74 6e 65 73 73 20 50 72 69 6e 63 69 70 bustness Princip
8ac0: 6c 65 0a 0a 3e 09 2a 42 65 20 6c 69 62 65 72 61 le..>.*Be libera
8ad0: 6c 20 69 6e 20 77 68 61 74 20 79 6f 75 20 61 63 l in what you ac
8ae0: 63 65 70 74 2c 20 61 6e 64 20 63 6f 6e 73 65 72 cept, and conser
8af0: 76 61 74 69 76 65 20 69 6e 20 77 68 61 74 20 79 vative in what y
8b00: 6f 75 20 73 65 6e 64 2e 2a 0a 0a 68 65 6c 64 20 ou send.*..held
8b10: 63 6f 6e 73 69 64 65 72 61 62 6c 65 20 69 6e 66 considerable inf
8b20: 6c 75 65 6e 63 65 20 61 74 20 74 68 65 20 74 69 luence at the ti
8b30: 6d 65 2e 20 4d 61 6e 79 20 69 6d 70 6c 65 6d 65 me. Many impleme
8b40: 6e 74 61 74 69 6f 6e 73 20 63 68 6f 73 65 20 74 ntations chose t
8b50: 6f 0a 61 63 63 6f 6d 6d 6f 64 61 74 65 20 69 6e o.accommodate in
8b60: 70 75 74 20 65 72 72 6f 72 73 2c 20 65 73 70 65 put errors, espe
8b70: 63 69 61 6c 6c 79 20 77 68 65 6e 20 74 68 61 74 cially when that
8b80: 20 77 61 73 20 74 68 65 20 6e 61 74 75 72 61 6c was the natural
8b90: 20 72 65 73 75 6c 74 0a 6f 66 20 6c 61 7a 69 6e result.of lazin
8ba0: 65 73 73 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 ess. For example
8bb0: 2c 20 74 68 65 20 73 70 65 63 69 66 69 63 61 74 , the specificat
8bc0: 69 6f 6e 20 6f 66 20 46 53 53 2d 55 54 46 20 61 ion of FSS-UTF a
8bd0: 6e 64 20 61 6c 6c 20 73 70 65 63 69 66 69 63 61 nd all specifica
8be0: 74 69 6f 6e 73 0a 66 6f 72 20 55 54 46 2d 38 20 tions.for UTF-8
8bf0: 61 72 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 63 are completely c
8c00: 6c 65 61 72 20 61 6e 64 20 65 78 70 6c 69 63 69 lear and explici
8c10: 74 20 74 68 61 74 20 74 68 65 20 70 72 6f 70 65 t that the prope
8c20: 72 20 65 6e 63 6f 64 69 6e 67 0a 6f 66 20 74 68 r encoding.of th
8c30: 65 20 63 6f 64 65 70 6f 69 6e 74 20 2a 2a 55 2b e codepoint **U+
8c40: 30 30 30 30 2a 2a 20 69 73 20 74 68 65 20 62 79 0000** is the by
8c50: 74 65 20 76 61 6c 75 65 20 2a 2a 30 78 30 30 2a te value **0x00*
8c60: 2a 2c 20 28 6f 75 72 20 6f 6c 64 20 66 72 69 65 *, (our old frie
8c70: 6e 64 0a 74 68 65 20 2a 2a 4e 55 4c 2a 2a 20 62 nd.the **NUL** b
8c80: 79 74 65 21 29 2e 20 48 6f 77 65 76 65 72 2c 20 yte!). However,
8c90: 69 6e 73 70 65 63 74 69 6f 6e 20 6f 66 20 74 68 inspection of th
8ca0: 65 20 46 53 53 2d 55 54 46 20 65 6e 63 6f 64 69 e FSS-UTF encodi
8cb0: 6e 67 20 72 75 6c 65 73 0a 71 75 69 63 6b 6c 79 ng rules.quickly
8cc0: 20 72 65 76 65 61 6c 73 20 74 68 61 74 20 74 68 reveals that th
8cd0: 65 20 6d 75 6c 74 69 2d 62 79 74 65 20 65 6e 63 e multi-byte enc
8ce0: 6f 64 69 6e 67 20 73 74 72 61 74 65 67 69 65 73 oding strategies
8cf0: 20 68 61 76 65 20 72 6f 6f 6d 20 74 6f 0a 65 6e have room to.en
8d00: 63 6f 64 65 20 61 6c 6c 20 74 68 65 20 63 6f 64 code all the cod
8d10: 65 70 6f 69 6e 74 73 20 74 68 61 74 20 61 6c 72 epoints that alr
8d20: 65 61 64 79 20 68 61 76 65 20 61 20 70 72 6f 70 eady have a prop
8d30: 65 72 20 65 6e 63 6f 64 69 6e 67 20 61 73 20 61 er encoding as a
8d40: 20 73 69 6e 67 6c 65 0a 62 79 74 65 2e 20 20 55 single.byte. U
8d50: 6e 6c 65 73 73 20 77 65 20 74 61 6b 65 20 61 63 nless we take ac
8d60: 74 69 76 65 20 73 74 65 70 73 20 74 6f 20 70 72 tive steps to pr
8d70: 65 76 65 6e 74 20 69 74 2c 20 61 20 64 65 63 6f event it, a deco
8d80: 64 69 6e 67 20 70 72 6f 63 65 64 75 72 65 0a 77 ding procedure.w
8d90: 69 6c 6c 20 68 61 70 70 69 6c 79 20 64 65 63 6f ill happily deco
8da0: 64 65 20 74 68 65 20 62 79 74 65 20 73 65 71 75 de the byte sequ
8db0: 65 6e 63 65 73 20 28 2a 2a 30 78 43 30 2a 2a 2c ences (**0xC0**,
8dc0: 20 2a 2a 30 78 38 30 2a 2a 29 20 6f 72 0a 28 2a **0x80**) or.(*
8dd0: 2a 30 78 45 30 2a 2a 2c 20 2a 2a 30 78 38 30 2a *0xE0**, **0x80*
8de0: 2a 2c 20 2a 2a 30 78 38 30 2a 2a 29 20 61 73 20 *, **0x80**) as
8df0: 74 68 65 20 63 6f 64 65 70 6f 69 6e 74 20 2a 2a the codepoint **
8e00: 55 2b 30 30 30 30 2a 2a 2e 20 20 42 6f 74 68 0a U+0000**. Both.
8e10: 55 6e 69 63 6f 64 65 20 31 2e 31 20 61 6e 64 20 Unicode 1.1 and
8e20: 55 6e 69 63 6f 64 65 20 32 2e 30 20 69 6e 63 6c Unicode 2.0 incl
8e30: 75 64 65 20 73 61 6d 70 6c 65 20 64 65 63 6f 64 ude sample decod
8e40: 65 72 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 er routines that
8e50: 20 64 6f 0a 65 78 61 63 74 6c 79 20 74 68 61 74 do.exactly that
8e60: 2e 20 54 68 65 20 74 65 78 74 20 6f 66 20 41 70 . The text of Ap
8e70: 70 65 6e 64 69 78 20 41 2e 32 20 6f 66 20 54 68 pendix A.2 of Th
8e80: 65 20 55 6e 69 63 6f 64 65 20 53 74 61 6e 64 61 e Unicode Standa
8e90: 72 64 20 32 2e 30 0a 28 77 68 69 63 68 20 63 6f rd 2.0.(which co
8ea0: 6e 74 61 69 6e 73 20 6f 6e 65 20 64 65 66 69 6e ntains one defin
8eb0: 69 74 69 6f 6e 20 6f 66 20 55 54 46 2d 38 20 66 ition of UTF-8 f
8ec0: 72 6f 6d 20 31 39 39 36 29 20 65 78 70 6c 69 63 rom 1996) explic
8ed0: 69 74 6c 79 20 73 74 61 74 65 73 2c 0a 0a 3e 09 itly states,..>.
8ee0: 57 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 20 When converting
8ef0: 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 6e from UTF-8 to Un
8f00: 69 63 6f 64 65 20 76 61 6c 75 65 73 2c 20 68 6f icode values, ho
8f10: 77 65 76 65 72 2c 0a 3e 09 69 6d 70 6c 65 6d 65 wever,.>.impleme
8f20: 6e 74 61 74 69 6f 6e 73 20 64 6f 20 6e 6f 74 20 ntations do not
8f30: 6e 65 65 64 20 74 6f 20 63 68 65 63 6b 20 74 68 need to check th
8f40: 61 74 20 74 68 65 20 73 68 6f 72 74 65 73 74 20 at the shortest
8f50: 65 6e 63 6f 64 69 6e 67 0a 3e 09 69 73 20 62 65 encoding.>.is be
8f60: 69 6e 67 20 75 73 65 64 2c 20 77 68 69 63 68 20 ing used, which
8f70: 73 69 6d 70 6c 69 66 69 65 73 20 74 68 65 20 63 simplifies the c
8f80: 6f 6e 76 65 72 73 69 6f 6e 20 61 6c 67 6f 72 69 onversion algori
8f90: 74 68 6d 2e 0a 0a 57 68 65 74 68 65 72 20 6f 72 thm...Whether or
8fa0: 20 6e 6f 74 20 74 68 65 20 54 63 6c 20 64 65 76 not the Tcl dev
8fb0: 65 6c 6f 70 65 72 73 20 77 65 72 65 20 65 78 70 elopers were exp
8fc0: 6c 69 63 69 74 6c 79 20 66 6f 6c 6c 6f 77 69 6e licitly followin
8fd0: 67 20 74 68 69 73 20 61 64 76 69 63 65 2c 0a 74 g this advice,.t
8fe0: 68 65 20 72 6f 75 74 69 6e 65 20 69 6e 20 54 63 he routine in Tc
8ff0: 6c 20 38 2e 31 20 66 6f 72 20 64 65 63 6f 64 69 l 8.1 for decodi
9000: 6e 67 20 55 6e 69 63 6f 64 65 20 63 6f 64 65 70 ng Unicode codep
9010: 6f 69 6e 74 73 20 66 72 6f 6d 20 74 68 65 0a 65 oints from the.e
9020: 6e 63 6f 64 65 64 20 62 79 74 65 20 73 65 71 75 ncoded byte sequ
9030: 65 6e 63 65 73 2c 0a 0a 3e 09 2a 2a 69 6e 74 2a ences,..>.**int*
9040: 2a 20 2a 2a 54 63 6c 5f 55 74 66 54 6f 55 6e 69 * **Tcl_UtfToUni
9050: 43 68 61 72 2a 2a 20 28 20 2a 2a 63 6f 6e 73 74 Char** ( **const
9060: 20 63 68 61 72 2a 2a 20 2a 5f 73 74 72 5f 2c 20 char** *_str_,
9070: 2a 2a 54 63 6c 5f 55 6e 69 43 68 61 72 2a 2a 20 **Tcl_UniChar**
9080: 2a 5f 63 68 50 74 72 5f 29 2c 0a 0a 69 6d 70 6c *_chPtr_),..impl
9090: 65 6d 65 6e 74 73 20 74 68 65 20 73 61 6d 65 20 ements the same
90a0: 66 6f 72 67 69 76 69 6e 67 20 73 75 70 70 6f 72 forgiving suppor
90b0: 74 20 66 6f 72 20 6f 76 65 72 6c 6f 6e 67 20 62 t for overlong b
90c0: 79 74 65 20 73 65 71 75 65 6e 63 65 73 2e 0a 0a yte sequences...
90d0: 49 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f In the context o
90e0: 66 20 74 68 65 20 73 74 69 6c 6c 20 69 6e 63 6f f the still inco
90f0: 6d 70 6c 65 74 65 20 74 72 61 6e 73 69 74 69 6f mplete transitio
9100: 6e 20 66 72 6f 6d 20 74 68 65 20 54 63 6c 20 37 n from the Tcl 7
9110: 20 74 6f 0a 74 68 65 20 54 63 6c 20 38 2e 30 20 to.the Tcl 8.0
9120: 63 6f 6e 76 65 6e 74 69 6f 6e 73 20 66 6f 72 20 conventions for
9130: 73 74 72 69 6e 67 20 76 61 6c 75 65 73 2c 20 61 string values, a
9140: 6e 64 20 74 68 65 20 6c 69 6e 67 65 72 69 6e 67 nd the lingering
9150: 20 64 69 66 66 69 63 75 6c 74 69 65 73 0a 69 6e difficulties.in
9160: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 2a 2a handling the **
9170: 4e 55 4c 2a 2a 20 62 79 74 65 2c 20 74 68 65 20 NUL** byte, the
9180: 66 6f 72 67 69 76 69 6e 67 20 6e 61 74 75 72 65 forgiving nature
9190: 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 64 65 of the UTF-8 de
91a0: 63 6f 64 65 72 73 0a 70 72 65 73 65 6e 74 65 64 coders.presented
91b0: 20 61 20 63 6c 65 61 72 20 6f 70 70 6f 72 74 75 a clear opportu
91c0: 6e 69 74 79 2e 20 20 49 66 20 74 68 65 20 64 65 nity. If the de
91d0: 63 6f 64 65 72 20 69 73 20 65 71 75 61 6c 6c 79 coder is equally
91e0: 20 68 61 70 70 79 20 74 6f 20 72 65 63 65 69 76 happy to receiv
91f0: 65 0a 74 68 65 20 62 79 74 65 20 73 65 71 75 65 e.the byte seque
9200: 6e 63 65 20 28 2a 2a 30 78 43 30 2a 2a 2c 20 2a nce (**0xC0**, *
9210: 2a 30 78 38 30 2a 2a 29 20 61 73 20 61 20 72 65 *0x80**) as a re
9220: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 presentation of
9230: 2a 2a 55 2b 30 30 30 30 2a 2a 2c 0a 77 68 79 20 **U+0000**,.why
9240: 6e 6f 74 20 68 61 76 65 20 74 68 65 20 65 6e 63 not have the enc
9250: 6f 64 65 72 20 65 6e 63 6f 64 65 20 69 74 20 74 oder encode it t
9260: 68 61 74 20 77 61 79 20 69 6e 20 74 68 65 20 66 hat way in the f
9270: 69 72 73 74 20 70 6c 61 63 65 3f 20 20 57 69 74 irst place? Wit
9280: 68 0a 74 68 69 73 20 6d 6f 64 69 66 69 63 61 74 h.this modificat
9290: 69 6f 6e 2c 20 65 6e 63 6f 64 65 64 20 62 79 74 ion, encoded byt
92a0: 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 74 75 e sequences retu
92b0: 72 6e 20 74 6f 20 6e 6f 74 20 68 61 76 69 6e 67 rn to not having
92c0: 20 74 68 65 20 2a 2a 4e 55 4c 2a 2a 0a 62 79 74 the **NUL**.byt
92d0: 65 20 69 6e 20 74 68 65 6d 20 61 74 20 61 6c 6c e in them at all
92e0: 2c 20 61 6e 64 20 77 65 20 73 77 65 65 70 20 61 , and we sweep a
92f0: 77 61 79 20 74 68 65 20 72 65 6d 6e 61 6e 74 73 way the remnants
9300: 20 6f 66 20 61 20 64 69 66 66 69 63 75 6c 74 0a of a difficult.
9310: 74 72 61 6e 73 69 74 69 6f 6e 20 28 77 68 69 6c transition (whil
9320: 65 20 61 64 6d 69 74 74 65 64 6c 79 20 61 64 64 e admittedly add
9330: 69 6e 67 20 61 20 6e 65 77 20 6f 6e 65 29 2e 20 ing a new one).
9340: 20 54 63 6c 20 63 68 6f 73 65 20 74 6f 20 61 64 Tcl chose to ad
9350: 6f 70 74 0a 74 68 69 73 20 6d 6f 64 69 66 69 63 opt.this modific
9360: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 6e 63 ation of the enc
9370: 6f 64 69 6e 67 20 72 75 6c 65 73 2e 20 20 4a 61 oding rules. Ja
9380: 76 61 20 31 2e 31 2c 20 61 6e 6f 74 68 65 72 20 va 1.1, another
9390: 6c 61 6e 67 75 61 67 65 0a 64 65 76 65 6c 6f 70 language.develop
93a0: 65 64 20 62 79 20 53 75 6e 20 4d 69 63 72 6f 73 ed by Sun Micros
93b0: 79 73 74 65 6d 73 20 61 74 20 74 68 65 20 73 61 ystems at the sa
93c0: 6d 65 20 74 69 6d 65 2c 20 6d 61 64 65 20 74 68 me time, made th
93d0: 65 20 73 61 6d 65 20 6d 6f 64 69 66 69 63 61 74 e same modificat
93e0: 69 6f 6e 2e 0a 0a 54 68 65 20 6d 6f 64 69 66 69 ion...The modifi
93f0: 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 77 69 cation is not wi
9400: 74 68 6f 75 74 20 69 74 73 20 70 72 6f 62 6c 65 thout its proble
9410: 6d 73 2e 20 20 4f 6e 65 20 66 65 61 74 75 72 65 ms. One feature
9420: 20 6f 66 20 74 68 65 20 70 72 6f 70 65 72 0a 55 of the proper.U
9430: 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 73 63 TF-8 encoding sc
9440: 68 65 6d 65 20 69 73 20 74 68 61 74 20 61 20 73 heme is that a s
9450: 6f 72 74 69 6e 67 20 6f 66 20 65 6e 63 6f 64 65 orting of encode
9460: 64 20 62 79 74 65 20 73 65 71 75 65 6e 63 65 73 d byte sequences
9470: 20 6d 61 74 63 68 65 73 0a 74 68 65 20 73 6f 72 matches.the sor
9480: 74 69 6e 67 20 6f 66 20 74 68 65 20 55 43 53 2d ting of the UCS-
9490: 32 20 73 65 71 75 65 6e 63 65 73 20 74 68 65 79 2 sequences they
94a0: 20 65 6e 63 6f 64 65 2e 20 20 4e 6f 74 20 73 6f encode. Not so
94b0: 20 77 68 65 6e 20 63 75 73 74 6f 6d 0a 6d 6f 64 when custom.mod
94c0: 69 66 69 63 61 74 69 6f 6e 73 20 61 72 65 20 69 ifications are i
94d0: 6e 20 70 6c 61 63 65 2e 20 20 4c 69 6b 65 77 69 n place. Likewi
94e0: 73 65 2c 20 62 79 74 65 2d 66 6f 72 2d 62 79 74 se, byte-for-byt
94f0: 65 20 63 6f 6d 70 61 72 69 73 6f 6e 73 20 6f 66 e comparisons of
9500: 0a 62 79 74 65 20 73 65 71 75 65 6e 63 65 73 20 .byte sequences
9510: 69 6e 20 61 20 70 72 6f 70 65 72 20 55 54 46 2d in a proper UTF-
9520: 38 20 65 6e 63 6f 64 69 6e 67 20 72 65 6c 69 61 8 encoding relia
9530: 62 6c 79 20 74 72 61 6e 73 66 65 72 20 74 6f 0a bly transfer to.
9540: 63 68 61 72 61 63 74 65 72 2d 66 6f 72 2d 63 68 character-for-ch
9550: 61 72 61 63 74 65 72 20 63 6f 6d 70 61 72 69 73 aracter comparis
9560: 6f 6e 73 20 6f 66 20 74 68 65 20 55 43 53 2d 32 ons of the UCS-2
9570: 20 73 74 72 69 6e 67 73 20 74 68 65 79 20 65 6e strings they en
9580: 63 6f 64 65 2e 0a 54 68 69 73 20 69 73 20 65 73 code..This is es
9590: 70 65 63 69 61 6c 6c 79 20 69 6d 70 6f 72 74 61 pecially importa
95a0: 6e 74 20 77 68 65 6e 20 74 65 73 74 69 6e 67 20 nt when testing
95b0: 66 6f 72 20 65 71 75 61 6c 69 74 79 20 61 73 20 for equality as
95c0: 69 73 20 76 69 74 61 6c 0a 69 6e 20 73 65 61 72 is vital.in sear
95d0: 63 68 65 73 2e 20 57 68 65 6e 20 61 6e 79 20 63 ches. When any c
95e0: 68 61 72 61 63 74 65 72 20 68 61 73 20 6d 75 6c haracter has mul
95f0: 74 69 70 6c 65 20 61 63 63 65 70 74 61 62 6c 65 tiple acceptable
9600: 20 65 6e 63 6f 64 69 6e 67 73 2c 0a 74 68 65 20 encodings,.the
9610: 66 75 6c 6c 79 20 63 6f 72 72 65 63 74 20 69 6d fully correct im
9620: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
9630: 74 68 65 73 65 20 6d 61 74 74 65 72 73 20 62 65 these matters be
9640: 63 6f 6d 65 73 20 6d 75 63 68 20 6d 6f 72 65 0a comes much more.
9650: 63 6f 6d 70 6c 65 78 2e 20 20 49 74 20 69 73 20 complex. It is
9660: 61 6c 73 6f 20 61 20 63 6f 6d 70 6c 69 63 61 74 also a complicat
9670: 69 6f 6e 20 74 68 61 74 20 77 68 65 6e 20 61 20 ion that when a
9680: 63 75 73 74 6f 6d 20 65 6e 63 6f 64 69 6e 67 0a custom encoding.
9690: 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 does not match a
96a0: 6e 79 20 73 74 61 6e 64 61 72 64 20 73 70 65 63 ny standard spec
96b0: 69 66 69 63 61 74 69 6f 6e 2c 20 69 74 20 62 65 ification, it be
96c0: 63 6f 6d 65 73 20 69 6d 70 6f 73 73 69 62 6c 65 comes impossible
96d0: 20 74 6f 20 64 6f 63 75 6d 65 6e 74 0a 77 68 61 to document.wha
96e0: 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 73 75 t encoding is su
96f0: 70 70 6f 72 74 65 64 20 69 6e 20 73 68 6f 72 74 pported in short
9700: 20 61 6e 64 20 70 72 65 63 69 73 65 20 77 61 79 and precise way
9710: 73 2e 20 45 69 74 68 65 72 20 61 20 6c 6f 6e 67 s. Either a long
9720: 0a 64 6f 63 75 6d 65 6e 74 20 73 70 65 6c 6c 69 .document spelli
9730: 6e 67 20 6f 75 74 20 74 68 65 20 72 75 6c 65 73 ng out the rules
9740: 20 74 68 61 74 20 61 72 65 20 69 6e 20 70 6c 61 that are in pla
9750: 63 65 20 6d 75 73 74 20 62 65 20 77 72 69 74 74 ce must be writt
9760: 65 6e 2c 20 6f 72 0a 65 6c 73 65 20 66 61 6c 73 en, or.else fals
9770: 65 20 63 6c 61 69 6d 73 20 61 72 65 20 6d 61 64 e claims are mad
9780: 65 20 61 62 6f 75 74 20 75 73 69 6e 67 20 22 55 e about using "U
9790: 54 46 2d 38 22 20 73 75 70 70 6c 65 6d 65 6e 74 TF-8" supplement
97a0: 65 64 20 62 79 20 68 61 70 68 61 7a 61 72 64 0a ed by haphazard.
97b0: 72 65 76 65 6c 61 74 69 6f 6e 73 20 74 6f 20 74 revelations to t
97c0: 68 65 20 63 75 72 69 6f 75 73 20 71 75 65 73 74 he curious quest
97d0: 69 6f 6e 65 72 73 20 6f 66 20 61 6c 6c 20 74 68 ioners of all th
97e0: 65 20 65 78 63 65 70 74 69 6f 6e 73 0a 61 6e 64 e exceptions.and
97f0: 20 74 72 61 6e 73 67 72 65 73 73 69 6f 6e 73 20 transgressions
9800: 74 68 61 74 20 61 72 65 20 61 63 75 74 61 6c 6c that are acutall
9810: 79 20 69 6e 20 70 6c 61 63 65 2e 0a 0a 54 68 61 y in place...Tha
9820: 74 20 69 73 20 6e 6f 74 20 74 68 65 20 65 6e 64 t is not the end
9830: 2e 20 45 76 65 6e 20 77 68 65 6e 20 61 6c 6c 20 . Even when all
9840: 6f 76 65 72 6c 6f 6e 67 20 65 6e 63 6f 64 69 6e overlong encodin
9850: 67 73 20 6f 66 20 61 6c 6c 20 63 6f 64 65 70 6f gs of all codepo
9860: 69 6e 74 73 0a 6f 66 20 55 43 53 2d 32 20 61 72 ints.of UCS-2 ar
9870: 65 20 61 63 63 65 70 74 65 64 2c 20 74 68 65 72 e accepted, ther
9880: 65 20 61 72 65 20 73 74 69 6c 6c 20 6d 61 6e 79 e are still many
9890: 2c 20 6d 61 6e 79 20 6d 6f 72 65 20 62 79 74 65 , many more byte
98a0: 20 73 65 71 75 65 6e 63 65 73 0a 74 6f 20 63 6f sequences.to co
98b0: 6e 73 69 64 65 72 2e 20 20 41 20 73 63 68 65 6d nsider. A schem
98c0: 65 20 64 65 6d 61 6e 64 69 6e 67 20 55 54 46 2d e demanding UTF-
98d0: 38 20 65 6e 63 6f 64 69 6e 67 20 77 6f 75 6c 64 8 encoding would
98e0: 20 62 65 20 65 78 70 65 63 74 65 64 20 74 6f 0a be expected to.
98f0: 72 65 6a 65 63 74 20 74 68 65 73 65 20 6f 74 68 reject these oth
9900: 65 72 20 73 65 71 75 65 6e 63 65 73 2c 20 65 69 er sequences, ei
9910: 74 68 65 72 20 62 79 20 72 61 69 73 69 6e 67 20 ther by raising
9920: 61 6e 20 65 72 72 6f 72 2c 20 6f 72 20 62 79 20 an error, or by
9930: 69 6e 73 65 72 74 69 6e 67 0a 74 68 65 20 2a 2a inserting.the **
9940: 52 45 50 4c 41 43 45 4d 45 4e 54 20 43 48 41 52 REPLACEMENT CHAR
9950: 41 43 54 45 52 2a 2a 20 69 6e 20 73 75 69 74 61 ACTER** in suita
9960: 62 6c 65 20 70 6c 61 63 65 73 20 74 6f 20 6d 61 ble places to ma
9970: 72 6b 20 74 68 65 20 6e 6f 6e 2d 63 6f 6e 66 6f rk the non-confo
9980: 72 6d 61 6e 74 0a 69 6e 70 75 74 2e 20 20 54 68 rmant.input. Th
9990: 69 73 20 69 73 20 6e 6f 74 20 77 68 61 74 20 2a is is not what *
99a0: 2a 54 63 6c 5f 55 74 66 54 6f 55 6e 69 43 68 61 *Tcl_UtfToUniCha
99b0: 72 2a 2a 20 64 6f 65 73 2e 20 20 49 6e 73 74 65 r** does. Inste
99c0: 61 64 20 77 68 65 6e 20 61 6e 79 0a 62 79 74 65 ad when any.byte
99d0: 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 is encountered
99e0: 74 68 61 74 20 69 73 20 69 6e 76 61 6c 69 64 20 that is invalid
99f0: 62 79 20 74 68 65 20 6d 6f 64 69 66 69 65 64 20 by the modified
9a00: 72 75 6c 65 73 20 6f 66 20 55 54 46 2d 38 20 61 rules of UTF-8 a
9a10: 6c 72 65 61 64 79 0a 64 65 73 63 72 69 62 65 64 lready.described
9a20: 2c 20 74 68 61 74 20 62 79 74 65 20 69 73 20 74 , that byte is t
9a30: 61 6b 65 6e 20 61 73 20 61 6e 20 65 6e 63 6f 64 aken as an encod
9a40: 69 6e 67 20 6f 66 20 74 68 65 20 63 6f 64 65 2d ing of the code-
9a50: 70 6f 69 6e 74 20 77 69 74 68 20 74 68 65 0a 73 point with the.s
9a60: 61 6d 65 20 76 61 6c 75 65 20 61 73 20 74 68 65 ame value as the
9a70: 20 62 79 74 65 20 76 61 6c 75 65 2e 20 20 54 68 byte value. Th
9a80: 61 74 20 69 73 2c 20 77 68 65 6e 20 74 68 65 20 at is, when the
9a90: 6d 6f 64 69 66 69 65 64 20 55 54 46 2d 38 20 65 modified UTF-8 e
9aa0: 6e 63 6f 64 69 6e 67 0a 66 61 69 6c 73 20 74 6f ncoding.fails to
9ab0: 20 62 65 20 73 61 74 69 73 66 69 65 64 2c 20 74 be satisfied, t
9ac0: 68 65 20 49 53 4f 2d 38 38 35 39 2d 31 20 65 6e he ISO-8859-1 en
9ad0: 63 6f 64 69 6e 67 20 6f 66 20 54 63 6c 20 38 2e coding of Tcl 8.
9ae0: 30 20 69 73 20 61 73 73 75 6d 65 64 20 69 6e 73 0 is assumed ins
9af0: 74 65 61 64 2e 0a 46 75 72 74 68 65 72 6d 6f 72 tead..Furthermor
9b00: 65 2c 20 74 68 69 73 20 69 73 20 6e 6f 74 20 6a e, this is not j
9b10: 75 73 74 20 61 20 71 75 69 65 74 20 61 63 63 6f ust a quiet acco
9b20: 6d 6d 6f 64 61 74 69 6f 6e 2c 20 6f 72 20 70 65 mmodation, or pe
9b30: 72 68 61 70 73 20 61 6e 20 65 72 72 6f 72 0a 69 rhaps an error.i
9b40: 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
9b50: 2e 20 49 74 20 69 73 20 74 68 65 20 65 78 70 6c . It is the expl
9b60: 69 63 74 20 64 6f 63 75 6d 65 6e 74 65 64 20 62 ict documented b
9b70: 65 68 61 76 69 6f 72 20 6f 66 0a 2a 2a 54 63 6c ehavior of.**Tcl
9b80: 5f 55 74 66 54 6f 55 6e 69 43 68 61 72 2a 2a 20 _UtfToUniChar**
9b90: 69 6e 20 54 63 6c 20 38 2e 31 2e 0a 0a 3e 09 49 in Tcl 8.1...>.I
9ba0: 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e f the input is n
9bb0: 6f 74 20 69 6e 20 70 72 6f 70 65 72 20 55 54 46 ot in proper UTF
9bc0: e2 80 90 38 20 66 6f 72 6d 61 74 2c 20 54 63 6c ‐8 format, Tcl
9bd0: 5c 5f 55 74 66 54 6f 55 6e 69 43 68 61 72 20 77 \_UtfToUniChar w
9be0: 69 6c 6c 0a 3e 09 73 74 6f 72 65 20 74 68 65 20 ill.>.store the
9bf0: 66 69 72 73 74 20 62 79 74 65 20 6f 66 20 73 72 first byte of sr
9c00: 63 20 69 6e 20 2a 63 68 50 74 72 20 20 61 73 20 c in *chPtr as
9c10: 61 20 54 63 6c 5c 5f 55 6e 69 43 68 61 72 20 62 a Tcl\_UniChar b
9c20: 65 74 77 65 65 6e 0a 3e 09 30 78 30 30 30 30 20 etween.>.0x0000
9c30: 61 6e 64 20 30 78 30 30 66 66 20 61 6e 64 20 72 and 0x00ff and r
9c40: 65 74 75 72 6e 20 31 2e 0a 0a 54 68 65 20 72 65 eturn 1...The re
9c50: 61 73 6f 6e 69 6e 67 20 62 65 68 69 6e 64 20 74 asoning behind t
9c60: 68 69 73 20 65 6e 63 6f 64 69 6e 67 20 63 68 6f his encoding cho
9c70: 69 63 65 20 69 73 20 6e 6f 74 20 65 78 70 6c 69 ice is not expli
9c80: 63 69 74 6c 79 20 72 65 63 6f 72 64 65 64 0a 69 citly recorded.i
9c90: 6e 20 61 6e 79 20 6b 6e 6f 77 6e 20 70 6c 61 63 n any known plac
9ca0: 65 2e 20 20 54 68 69 73 20 64 6f 65 73 20 6e 6f e. This does no
9cb0: 74 20 61 70 70 65 61 72 20 74 6f 20 62 65 20 61 t appear to be a
9cc0: 20 63 68 6f 69 63 65 20 63 6f 70 69 65 64 20 66 choice copied f
9cd0: 72 6f 6d 0a 4a 61 76 61 2e 20 20 49 74 20 73 65 rom.Java. It se
9ce0: 65 6d 73 20 61 20 72 65 61 73 6f 6e 61 62 6c 65 ems a reasonable
9cf0: 20 67 75 65 73 73 20 74 6f 20 70 72 65 73 75 6d guess to presum
9d00: 65 20 74 68 69 73 20 69 73 20 69 6e 74 65 6e 64 e this is intend
9d10: 65 64 20 74 6f 20 6f 66 66 65 72 0a 73 6f 6d 65 ed to offer.some
9d20: 20 6d 65 61 73 75 72 65 20 6f 66 20 63 6f 6d 70 measure of comp
9d30: 61 74 69 62 69 6c 69 74 79 20 74 6f 20 64 65 70 atibility to dep
9d40: 6c 6f 79 65 64 20 63 61 6c 6c 65 72 73 20 6f 66 loyed callers of
9d50: 20 54 63 6c 20 37 20 61 6e 64 20 54 63 6c 20 38 Tcl 7 and Tcl 8
9d60: 2e 30 2c 0a 74 68 6f 75 67 68 20 74 68 65 20 65 .0,.though the e
9d70: 66 66 65 63 74 69 76 65 6e 65 73 73 20 6f 66 20 ffectiveness of
9d80: 74 68 61 74 20 73 74 72 61 74 65 67 79 20 69 73 that strategy is
9d90: 20 71 75 65 73 74 69 6f 6e 61 62 6c 65 20 74 6f questionable to
9da0: 20 73 61 79 20 74 68 65 20 6c 65 61 73 74 2e 0a say the least..
9db0: 41 20 54 63 6c 20 38 2e 31 20 74 68 61 74 20 63 A Tcl 8.1 that c
9dc0: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 74 72 65 61 ontinues to trea
9dd0: 74 20 74 68 65 20 62 79 74 65 20 73 65 71 75 65 t the byte seque
9de0: 6e 63 65 20 28 2a 2a 30 78 43 30 2a 2a 2c 20 2a nce (**0xC0**, *
9df0: 2a 30 78 32 30 2a 2a 29 0a 61 73 20 74 68 65 20 *0x20**).as the
9e00: 73 61 6d 65 20 74 77 6f 20 62 79 74 65 73 20 61 same two bytes a
9e10: 73 20 54 63 6c 20 38 2e 30 2c 20 62 75 74 20 62 s Tcl 8.0, but b
9e20: 65 67 69 6e 73 20 74 6f 20 74 72 65 61 74 20 74 egins to treat t
9e30: 68 65 20 62 79 74 65 0a 73 65 71 75 65 6e 63 65 he byte.sequence
9e40: 20 28 2a 2a 30 78 43 30 2a 2a 2c 20 2a 2a 30 78 (**0xC0**, **0x
9e50: 38 30 2a 2a 29 20 61 73 20 61 20 72 65 70 72 65 80**) as a repre
9e60: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 2a 2a 4e sentation of **N
9e70: 55 4c 2a 2a 20 69 73 20 6e 6f 74 0a 6d 75 63 68 UL** is not.much
9e80: 20 6f 66 20 61 20 63 6f 6d 70 61 74 69 62 69 6c of a compatibil
9e90: 69 74 79 20 61 63 63 6f 6d 6d 6f 64 61 74 69 6f ity accommodatio
9ea0: 6e 20 74 6f 20 72 65 6c 79 20 75 70 6f 6e 2e 0a n to rely upon..
9eb0: 0a 6d 61 6e 79 2d 74 6f 2d 6f 6e 65 2c 20 69 6e .many-to-one, in
9ec0: 74 65 72 70 72 65 74 69 76 65 20 66 72 65 65 64 terpretive freed
9ed0: 6f 6d 2c 20 28 70 61 72 73 65 20 6f 66 20 5c 6e om, (parse of \n
9ee0: 29 0a 76 61 72 69 61 62 6c 65 20 6c 65 6e 67 74 ).variable lengt
9ef0: 68 0a 0a 43 6f 6d 70 61 74 20 77 69 74 68 20 38 h..Compat with 8
9f00: 2e 30 0a 42 79 74 65 41 72 72 61 79 73 0a 0a 55 .0.ByteArrays..U
9f10: 43 53 2d 32 20 73 65 71 75 65 6e 63 65 73 0a 62 CS-2 sequences.b
9f20: 79 74 65 73 20 76 20 63 68 61 72 73 0a 0a 54 77 ytes v chars..Tw
9f30: 6f 2d 74 69 65 72 20 65 6e 63 6f 64 69 6e 67 2e o-tier encoding.
9f40: 20 0a 0a 54 68 72 65 61 64 69 6e 67 20 26 20 6d ..Threading & m
9f50: 65 6d 6f 72 79 20 76 61 6c 69 64 69 74 79 0a 0a emory validity..
9f60: 41 50 49 20 43 6f 75 6e 74 73 3f 0a 0a 4e 55 4c API Counts?..NUL
9f70: 20 6e 61 6d 69 6e 67 20 6c 69 6d 69 74 61 74 69 naming limitati
9f80: 6f 6e 73 0a 0a 55 54 46 2d 31 36 20 61 6e 64 20 ons..UTF-16 and
9f90: 73 75 72 72 6f 67 61 74 65 20 70 61 69 72 73 0a surrogate pairs.
9fa0: 0a 0a 0a 0a 44 75 72 69 6e 67 20 74 68 65 20 64 ....During the d
9fb0: 65 76 65 6c 6f 70 6d 65 6e 74 20 6f 66 20 54 63 evelopment of Tc
9fc0: 6c 20 38 2e 31 2c 20 74 68 65 20 70 72 65 76 61 l 8.1, the preva
9fd0: 69 6c 69 6e 67 20 55 6e 69 63 6f 64 65 20 73 74 iling Unicode st
9fe0: 61 6e 64 61 72 64 73 20 77 65 72 65 0a 55 6e 69 andards were.Uni
9ff0: 63 6f 64 65 20 32 2e 30 20 61 6e 64 20 32 2e 31 code 2.0 and 2.1
a000: 2e 20 49 6e 20 74 68 65 73 65 20 64 65 66 69 6e . In these defin
a010: 69 74 69 6f 6e 73 20 6f 66 20 55 6e 69 63 6f 64 itions of Unicod
a020: 65 2c 20 61 6c 6c 20 61 73 73 69 67 6e 65 64 20 e, all assigned
a030: 63 6f 64 65 70 6f 69 6e 74 73 0a 77 65 72 65 20 codepoints.were
a040: 69 6e 20 74 68 65 20 73 65 74 20 55 2b 30 30 30 in the set U+000
a050: 30 20 74 68 72 6f 75 67 68 20 55 2b 46 46 46 46 0 through U+FFFF
a060: 2c 20 74 68 65 20 73 65 74 20 6f 66 20 63 68 61 , the set of cha
a070: 72 61 63 74 65 72 73 20 77 69 74 68 69 6e 0a 55 racters within.U
a080: 43 53 2d 32 2c 20 61 6c 73 6f 20 63 61 6c 6c 65 CS-2, also calle
a090: 64 20 74 68 65 20 42 61 73 69 63 20 4d 75 6c 74 d the Basic Mult
a0a0: 69 6c 69 6e 67 75 61 6c 20 50 6c 61 6e 65 2e 0a ilingual Plane..
a0b0: 0a 54 68 65 20 70 75 62 6c 69 63 61 74 69 6f 6e .The publication
a0c0: 20 6f 66 20 52 46 43 20 32 30 34 34 20 64 65 73 of RFC 2044 des
a0d0: 63 72 69 62 69 6e 67 20 61 20 55 54 46 2d 38 0a cribing a UTF-8.
a0e0: 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 55 43 53 encoding for UCS
a0f0: 2d 32 20 69 6e 20 4f 63 74 6f 62 65 72 20 31 39 -2 in October 19
a100: 39 36 20 77 61 73 20 61 6c 73 6f 20 61 20 6b 65 96 was also a ke
a110: 79 20 65 76 65 6e 74 2e 0a 0a 4e 6f 74 65 20 74 y event...Note t
a120: 68 65 20 65 6e 64 20 6f 66 20 6f 76 65 72 6c 6f he end of overlo
a130: 6e 67 20 62 79 74 65 20 73 65 71 75 65 6e 63 65 ng byte sequence
a140: 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
a150: 28 6f 74 68 65 72 20 74 68 61 6e 20 4e 55 4c 29 (other than NUL)
a160: 0a 61 73 20 62 75 67 20 66 69 78 20 0a 68 74 74 .as bug fix .htt
a170: 70 73 3a 2f 2f 63 6f 72 65 2e 74 63 6c 2d 6c 61 ps://core.tcl-la
a180: 6e 67 2e 6f 72 67 2f 74 63 6c 2f 69 6e 66 6f 2f ng.org/tcl/info/
a190: 36 37 61 61 39 61 32 30 37 30 0a 54 68 69 73 20 67aa9a2070.This
a1a0: 64 69 64 6e 27 74 20 68 61 70 70 65 6e 20 61 74 didn't happen at
a1b0: 20 61 20 63 6c 65 61 6e 20 6d 69 6e 6f 72 20 76 a clean minor v
a1c0: 65 72 73 69 6f 6e 20 62 75 6d 70 2e 0a 0a 0a 0a ersion bump.....
a1d0: 4d 49 4c 45 53 54 4f 4e 45 3a 20 42 75 67 20 36 MILESTONE: Bug 6
a1e0: 37 61 61 39 61 32 30 37 30 20 77 61 73 20 66 69 7aa9a2070 was fi
a1f0: 78 65 64 20 69 6e 20 4a 75 6e 65 20 32 30 31 37 xed in June 2017
a200: 2c 20 66 69 72 73 74 20 72 65 6c 65 61 73 65 64 , first released
a210: 20 69 6e 20 54 63 6c 20 38 2e 36 2e 37 0a 69 6e in Tcl 8.6.7.in
a220: 20 41 75 67 75 73 74 20 32 30 31 37 2e 20 20 54 August 2017. T
a230: 68 69 73 20 69 73 20 77 68 65 6e 20 54 63 6c 20 his is when Tcl
a240: 73 74 6f 70 70 65 64 20 61 63 63 65 70 74 69 6e stopped acceptin
a250: 67 20 6f 76 65 72 6c 6f 6e 67 20 62 79 74 65 20 g overlong byte
a260: 73 65 71 75 65 6e 63 65 73 0a 69 6e 20 69 74 73 sequences.in its
a270: 20 69 6e 74 65 72 6e 61 6c 20 65 6e 63 6f 64 69 internal encodi
a280: 6e 67 20 61 73 20 76 61 6c 69 64 20 61 6c 74 65 ng as valid alte
a290: 72 6e 61 74 69 76 65 20 77 61 79 73 20 74 6f 20 rnative ways to
a2a0: 65 6e 63 6f 64 65 20 63 68 61 72 61 63 74 65 72 encode character
a2b0: 73 2e 0a 0a 4d 49 4c 45 53 54 4f 4e 45 3a 20 5b s...MILESTONE: [
a2c0: 38 61 36 34 30 63 37 37 31 65 65 39 32 37 63 38 8a640c771ee927c8
a2d0: 5d 2c 20 32 30 31 39 2d 31 31 2d 31 34 2c 20 66 ], 2019-11-14, f
a2e0: 69 72 73 74 20 72 65 6c 65 61 73 65 64 20 69 6e irst released in
a2f0: 20 54 63 6c 20 38 2e 36 2e 31 30 0a 69 6e 20 4e Tcl 8.6.10.in N
a300: 6f 76 65 6d 62 65 72 20 32 30 31 39 2e 20 54 68 ovember 2019. Th
a310: 69 73 20 69 73 20 77 68 65 6e 20 76 61 6c 69 64 is is when valid
a320: 20 34 2d 62 79 74 65 20 73 65 71 75 65 6e 63 65 4-byte sequence
a330: 73 20 73 74 61 72 74 65 64 20 62 65 69 6e 67 20 s started being
a340: 72 65 63 6f 67 6e 69 7a 65 64 0a 61 6e 64 20 74 recognized.and t
a350: 72 65 61 74 65 64 20 61 73 20 73 6f 6d 65 74 68 reated as someth
a360: 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 34 ing other than 4
a370: 20 69 6d 70 72 6f 70 65 72 6c 79 20 65 6e 63 6f improperly enco
a380: 64 65 64 20 49 53 4f 2d 38 38 35 39 2d 31 20 63 ded ISO-8859-1 c
a390: 68 61 72 73 2e 0a 0a 0a hars....
