0000: 44 20 32 30 32 34 2d 30 34 2d 31 34 54 31 31 3a D 2024-04-14T11:
0010: 32 38 3a 35 30 2e 34 30 35 0a 4c 20 4d 69 67 72 28:50.405.L Migr
0020: 61 74 69 6e 67 5c 73 43 5c 73 65 78 74 65 6e 73 ating\sC\sextens
0030: 69 6f 6e 73 5c 73 74 6f 5c 73 54 63 6c 5c 73 39 ions\sto\sTcl\s9
0040: 0a 4e 20 74 65 78 74 2f 78 2d 6d 61 72 6b 64 6f .N text/x-markdo
0050: 77 6e 0a 50 20 38 31 32 30 34 66 65 37 32 31 30 wn.P 81204fe7210
0060: 64 32 62 31 63 32 39 62 66 66 35 61 36 39 66 38 d2b1c29bff5a69f8
0070: 62 65 33 62 36 34 30 63 64 38 30 30 38 31 62 35 be3b640cd80081b5
0080: 30 34 34 30 63 64 63 66 36 63 66 34 39 33 31 37 0440cdcf6cf49317
0090: 61 65 36 64 38 0a 55 20 61 70 6e 61 64 6b 61 72 ae6d8.U apnadkar
00a0: 6e 69 0a 57 20 31 32 39 32 34 0a 28 57 6f 72 6b ni.W 12924.(Work
00b0: 20 69 6e 20 70 72 6f 67 72 65 73 73 2e 2e 2e 29 in progress...)
00c0: 0d 0a 0d 0a 41 6c 73 6f 20 73 65 65 20 5b 50 6f ....Also see [Po
00d0: 72 74 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 73 rting extensions
00e0: 20 74 6f 20 54 63 6c 20 39 5d 28 68 74 74 70 73 to Tcl 9](https
00f0: 3a 2f 2f 77 69 6b 69 2e 74 63 6c 2d 6c 61 6e 67 ://wiki.tcl-lang
0100: 2e 6f 72 67 2f 70 61 67 65 2f 50 6f 72 74 69 6e .org/page/Portin
0110: 67 2b 65 78 74 65 6e 73 69 6f 6e 73 2b 74 6f 2b g+extensions+to+
0120: 54 63 6c 2b 39 29 0d 0a 66 6f 72 20 61 6e 6f 74 Tcl+9)..for anot
0130: 68 65 72 20 70 6f 73 74 20 6f 6e 20 74 68 65 20 her post on the
0140: 74 6f 70 69 63 2e 0d 0a 0d 0a 23 23 20 49 6e 69 topic.....## Ini
0150: 74 20 73 74 75 62 73 20 61 6e 64 20 70 61 63 6b t stubs and pack
0160: 61 67 65 20 72 65 71 75 69 72 65 20 77 69 74 68 age require with
0170: 20 6f 70 65 6e 20 76 65 72 73 69 6f 6e 0d 0a 0d open version...
0180: 0a 54 68 65 20 6c 69 73 74 20 6f 66 20 76 65 72 .The list of ver
0190: 73 69 6f 6e 73 20 73 68 6f 75 6c 64 20 69 6e 63 sions should inc
01a0: 6c 75 64 65 20 54 43 4c 2f 54 6b 20 39 2e 20 48 lude TCL/Tk 9. H
01b0: 65 72 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c ere is an exampl
01c0: 65 20 66 6f 72 20 54 43 4c 20 38 2e 35 20 61 6e e for TCL 8.5 an
01d0: 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 76 65 72 73 d following vers
01e0: 69 6f 6e 73 2e 0d 0a 52 65 6d 61 72 6b 20 74 68 ions...Remark th
01f0: 65 20 22 2d 22 20 61 66 74 65 72 20 22 38 2e 35 e "-" after "8.5
0200: 22 2e 0d 0a 0d 0a 7e 7e 7e 0d 0a 23 69 66 64 65 ".....~~~..#ifde
0210: 66 20 55 53 45 5f 54 43 4c 5f 53 54 55 42 53 0d f USE_TCL_STUBS.
0220: 0a 20 20 20 20 69 66 20 28 54 63 6c 5f 49 6e 69 . if (Tcl_Ini
0230: 74 53 74 75 62 73 28 69 6e 74 65 72 70 2c 20 22 tStubs(interp, "
0240: 38 2e 35 2d 22 2c 20 30 29 20 3d 3d 20 4e 55 4c 8.5-", 0) == NUL
0250: 4c 29 0d 0a 23 65 6c 73 65 0d 0a 20 20 20 20 69 L)..#else.. i
0260: 66 20 28 54 63 6c 5f 50 6b 67 52 65 71 75 69 72 f (Tcl_PkgRequir
0270: 65 28 69 6e 74 65 72 70 2c 20 22 54 63 6c 22 2c e(interp, "Tcl",
0280: 20 22 38 2e 35 2d 22 2c 20 30 29 20 3d 3d 20 4e "8.5-", 0) == N
0290: 55 4c 4c 29 0d 0a 23 65 6e 64 69 66 0d 0a 20 20 ULL)..#endif..
02a0: 20 20 7b 0d 0a 20 20 20 20 20 20 20 20 72 65 74 {.. ret
02b0: 75 72 6e 20 54 43 4c 5f 45 52 52 4f 52 3b 0d 0a urn TCL_ERROR;..
02c0: 20 20 20 20 7d 0d 0a 7e 7e 7e 0d 0a 0d 0a 23 23 }..~~~....##
02d0: 20 36 34 2d 62 69 74 20 64 61 74 61 20 73 75 70 64-bit data sup
02e0: 70 6f 72 74 0d 0a 0d 0a 4f 6e 20 36 34 2d 62 69 port....On 64-bi
02f0: 74 20 70 6c 61 74 66 6f 72 6d 73 2c 20 54 63 6c t platforms, Tcl
0300: 20 39 20 6e 6f 20 6c 6f 6e 67 65 72 20 6c 69 6d 9 no longer lim
0310: 69 74 73 20 64 61 74 61 20 73 69 7a 65 20 28 6c its data size (l
0320: 65 6e 67 74 68 73 20 6f 66 20 73 74 72 69 6e 67 engths of string
0330: 73 2c 20 6c 69 73 74 73 0d 0a 65 74 63 2e 29 20 s, lists..etc.)
0340: 61 6e 64 20 69 6e 64 69 63 65 73 20 74 6f 20 33 and indices to 3
0350: 32 2d 62 69 74 73 2e 20 46 6f 72 20 70 6f 72 74 2-bits. For port
0360: 61 62 69 6c 69 74 79 20 6f 66 20 65 78 74 65 6e ability of exten
0370: 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 33 32 sions between 32
0380: 2d 20 61 6e 64 0d 0a 36 34 2d 62 69 74 20 70 6c - and..64-bit pl
0390: 61 74 66 6f 72 6d 73 2c 20 61 20 6e 65 77 20 74 atforms, a new t
03a0: 79 70 65 64 65 66 20 60 54 63 6c 5f 53 69 7a 65 ypedef `Tcl_Size
03b0: 60 20 68 61 73 20 62 65 65 6e 20 64 65 66 69 6e ` has been defin
03c0: 65 64 2e 20 54 68 69 73 20 6d 61 70 73 20 74 6f ed. This maps to
03d0: 20 61 0d 0a 36 34 2d 62 69 74 20 6f 72 20 33 32 a..64-bit or 32
03e0: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
03f0: 67 65 72 20 74 79 70 65 20 6f 6e 20 74 68 65 20 ger type on the
0400: 72 65 73 70 65 63 74 69 76 65 20 70 6c 61 74 66 respective platf
0410: 6f 72 6d 73 2e 20 54 68 69 73 20 61 66 66 65 63 orms. This affec
0420: 74 73 0d 0a 61 6c 6c 20 70 75 62 6c 69 63 20 73 ts..all public s
0430: 74 72 75 63 74 75 72 65 73 20 61 6e 64 20 70 61 tructures and pa
0440: 72 61 6d 65 74 65 72 20 74 79 70 65 73 20 61 73 rameter types as
0450: 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 56 61 appropriate. Va
0460: 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 6f 6c riables that hol
0470: 64 0d 0a 6c 65 6e 67 74 68 73 20 6f 72 20 69 6e d..lengths or in
0480: 64 69 63 65 73 20 74 68 61 74 20 77 65 72 65 20 dices that were
0490: 74 79 70 65 64 20 61 73 20 60 69 6e 74 60 20 66 typed as `int` f
04a0: 6f 72 20 54 63 6c 20 38 20 73 68 6f 75 6c 64 20 or Tcl 8 should
04b0: 62 65 20 63 68 61 6e 67 65 64 20 74 6f 20 62 65 be changed to be
04c0: 20 6f 66 0d 0a 74 79 70 65 20 60 54 63 6c 5f 53 of..type `Tcl_S
04d0: 69 7a 65 60 2e 20 43 61 72 65 20 6d 75 73 74 20 ize`. Care must
04e0: 62 65 20 74 61 6b 65 6e 20 74 68 61 74 20 72 65 be taken that re
04f0: 6c 61 74 65 64 20 76 61 72 69 61 62 6c 65 73 2c lated variables,
0500: 20 66 6f 72 20 65 78 61 6d 70 6c 65 20 6c 6f 6f for example loo
0510: 70 0d 0a 69 74 65 72 61 74 6f 72 73 2c 20 61 72 p..iterators, ar
0520: 65 20 61 6c 73 6f 20 6d 6f 64 69 66 69 65 64 20 e also modified
0530: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0d 0a 0d 0a accordingly.....
0540: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 For example, in
0550: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 72 the following fr
0560: 61 67 6d 65 6e 74 0d 0a 0d 0a 60 60 60 0d 0a 69 agment....```..i
0570: 6e 74 20 6c 65 6e 3b 0d 0a 69 6e 74 20 69 3b 0d nt len;..int i;.
0580: 0a 54 63 6c 5f 4c 69 73 74 4f 62 6a 4c 65 6e 67 .Tcl_ListObjLeng
0590: 74 68 28 69 6e 74 65 72 70 2c 20 6f 62 6a 50 74 th(interp, objPt
05a0: 72 2c 20 26 6c 65 6e 29 3b 0d 0a 66 6f 72 20 28 r, &len);..for (
05b0: 69 20 3d 20 30 3b 20 69 20 3c 20 6c 65 6e 3b 20 i = 0; i < len;
05c0: 2b 2b 69 29 20 7b 0d 0a 20 20 20 2e 2e 2e 2e 0d ++i) {.. .....
05d0: 0a 7d 0d 0a 60 60 60 0d 0a 0d 0a 74 68 65 20 64 .}..```....the d
05e0: 65 63 6c 61 72 61 74 69 6f 6e 20 6f 66 20 62 6f eclaration of bo
05f0: 74 68 20 60 69 60 20 61 6e 64 20 60 6c 65 6e 60 th `i` and `len`
0600: 20 73 68 6f 75 6c 64 20 62 65 20 63 68 61 6e 67 should be chang
0610: 65 64 0d 0a 0d 0a 60 60 60 0d 0a 54 63 6c 5f 53 ed....```..Tcl_S
0620: 69 7a 65 20 6c 65 6e 3b 0d 0a 54 63 6c 5f 53 69 ize len;..Tcl_Si
0630: 7a 65 20 69 3b 0d 0a 60 60 60 0d 0a 0d 0a 57 68 ze i;..```....Wh
0640: 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 20 73 69 en converting si
0650: 7a 65 73 20 61 6e 64 20 69 6e 64 69 63 65 73 20 zes and indices
0660: 74 6f 20 61 6e 64 20 66 72 6f 6d 20 73 74 72 69 to and from stri
0670: 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f ng representatio
0680: 6e 2c 0d 0a 72 65 70 6c 61 63 65 20 74 68 65 20 n,..replace the
0690: 75 73 65 20 6f 66 20 60 54 63 6c 5f 47 65 74 49 use of `Tcl_GetI
06a0: 6e 74 46 72 6f 6d 4f 62 6a 60 20 61 6e 64 20 60 ntFromObj` and `
06b0: 54 63 6c 5f 4e 65 77 49 6e 74 4f 62 6a 60 20 77 Tcl_NewIntObj` w
06c0: 69 74 68 20 74 68 65 0d 0a 60 54 63 6c 5f 53 69 ith the..`Tcl_Si
06d0: 7a 65 60 20 61 6e 61 6c 6f 67 75 65 73 20 60 54 ze` analogues `T
06e0: 63 6c 5f 47 65 74 53 69 7a 65 49 6e 74 46 72 6f cl_GetSizeIntFro
06f0: 6d 4f 62 6a 60 20 61 6e 64 20 60 54 63 6c 5f 4e mObj` and `Tcl_N
0700: 65 77 53 69 7a 65 49 6e 74 4f 62 6a 60 2e 0d 0a ewSizeIntObj`...
0710: 0d 0a 57 68 65 6e 20 63 68 65 63 6b 69 6e 67 20 ..When checking
0720: 73 74 72 69 6e 67 20 6c 69 6d 69 74 73 20 65 74 string limits et
0730: 63 2e 20 61 70 70 72 6f 70 72 69 61 74 65 6c 79 c. appropriately
0740: 20 66 6f 72 20 62 6f 74 68 20 70 6c 61 74 66 6f for both platfo
0750: 72 6d 20 77 69 64 74 68 73 2c 0d 0a 74 68 65 20 rm widths,..the
0760: 63 6f 6e 73 74 61 6e 74 20 60 54 43 4c 5f 53 49 constant `TCL_SI
0770: 5a 45 5f 4d 41 58 60 20 73 68 6f 75 6c 64 20 62 ZE_MAX` should b
0780: 65 20 75 73 65 64 20 69 6e 20 6c 69 65 75 20 6f e used in lieu o
0790: 66 20 60 49 4e 54 5f 4d 41 58 60 2e 0d 0a 0d 0a f `INT_MAX`.....
07a0: 57 68 65 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 When formatting
07b0: 61 73 20 61 20 73 74 72 69 6e 67 20 74 68 72 6f as a string thro
07c0: 75 67 68 20 61 20 60 70 72 69 6e 74 66 60 20 73 ugh a `printf` s
07d0: 74 79 6c 65 20 76 61 72 61 72 67 73 20 66 75 6e tyle varargs fun
07e0: 63 74 69 6f 6e 2c 20 61 20 73 69 7a 65 0d 0a 6d ction, a size..m
07f0: 6f 64 69 66 69 65 72 20 61 70 70 72 6f 70 72 69 odifier appropri
0800: 61 74 65 20 66 6f 72 20 74 68 65 20 70 6c 61 74 ate for the plat
0810: 66 6f 72 6d 20 77 69 64 74 68 20 6e 65 65 64 73 form width needs
0820: 20 74 6f 20 62 65 20 75 73 65 64 2e 20 54 68 69 to be used. Thi
0830: 73 20 69 73 20 64 65 66 69 6e 65 64 0d 0a 61 73 s is defined..as
0840: 20 60 54 43 4c 5f 53 49 5a 45 5f 4d 4f 44 49 46 `TCL_SIZE_MODIF
0850: 49 45 52 60 2e 20 46 6f 72 20 65 78 61 6d 70 6c IER`. For exampl
0860: 65 2c 0d 0a 0d 0a 60 60 60 0d 0a 54 63 6c 5f 53 e,....```..Tcl_S
0870: 69 7a 65 20 6c 65 6e 3b 0d 0a 54 63 6c 5f 4f 62 ize len;..Tcl_Ob
0880: 6a 20 2a 6f 62 6a 50 20 3d 20 54 63 6c 5f 4f 62 j *objP = Tcl_Ob
0890: 6a 50 72 69 6e 74 66 28 22 54 68 65 20 6c 65 6e jPrintf("The len
08a0: 67 74 68 20 69 73 20 25 22 20 54 43 4c 5f 53 49 gth is %" TCL_SI
08b0: 5a 45 5f 4d 4f 44 49 46 49 45 52 20 22 64 2e 22 ZE_MODIFIER "d."
08c0: 2c 20 6c 65 6e 29 3b 0d 0a 60 60 60 0d 0a 0d 0a , len);..```....
08d0: 49 66 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 If the ability t
08e0: 6f 20 62 75 69 6c 64 20 61 67 61 69 6e 73 74 20 o build against
08f0: 54 63 6c 20 38 20 69 73 20 64 65 73 69 72 65 64 Tcl 8 is desired
0900: 20 61 66 74 65 72 20 6d 61 6b 69 6e 67 20 74 68 after making th
0910: 65 20 61 62 6f 76 65 0d 0a 63 68 61 6e 67 65 73 e above..changes
0920: 20 72 65 71 75 69 72 65 20 66 6f 72 20 54 63 6c require for Tcl
0930: 20 39 2c 20 61 64 64 20 74 68 65 20 66 6f 6c 6c 9, add the foll
0940: 6f 77 69 6e 67 20 66 72 61 67 6d 65 6e 74 20 74 owing fragment t
0950: 6f 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 o the appropriat
0960: 65 0d 0a 68 65 61 64 65 72 20 66 6f 72 20 74 68 e..header for th
0970: 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0d 0a 0d 0a e extension.....
0980: 60 60 60 0d 0a 23 69 66 6e 64 65 66 20 54 43 4c ```..#ifndef TCL
0990: 5f 53 49 5a 45 5f 4d 41 58 0d 0a 23 20 64 65 66 _SIZE_MAX..# def
09a0: 69 6e 65 20 54 63 6c 5f 47 65 74 53 69 7a 65 49 ine Tcl_GetSizeI
09b0: 6e 74 46 72 6f 6d 4f 62 6a 20 54 63 6c 5f 47 65 ntFromObj Tcl_Ge
09c0: 74 49 6e 74 46 72 6f 6d 4f 62 6a 0d 0a 23 20 64 tIntFromObj..# d
09d0: 65 66 69 6e 65 20 54 43 4c 5f 53 49 5a 45 5f 4d efine TCL_SIZE_M
09e0: 41 58 20 20 20 20 20 20 49 4e 54 5f 4d 41 58 0d AX INT_MAX.
09f0: 0a 23 20 64 65 66 69 6e 65 20 54 43 4c 5f 53 49 .# define TCL_SI
0a00: 5a 45 5f 4d 4f 44 49 46 49 45 52 20 22 22 0d 0a ZE_MODIFIER ""..
0a10: 23 65 6e 64 69 66 0d 0a 0d 0a 60 60 60 0d 0a 0d #endif....```...
0a20: 0a 22 54 63 6c 5f 53 69 7a 65 22 20 69 74 73 65 ."Tcl_Size" itse
0a30: 6c 66 20 64 6f 65 73 6e 27 74 20 6e 65 65 64 20 lf doesn't need
0a40: 74 6f 20 62 65 20 70 72 6f 76 69 64 65 64 20 61 to be provided a
0a50: 73 20 6c 6f 6e 67 20 61 73 20 79 6f 75 20 75 70 s long as you up
0a60: 64 61 74 65 20 74 68 65 20 65 78 74 65 6e 73 69 date the extensi
0a70: 6f 6e 20 74 6f 20 74 68 65 20 6c 61 74 65 73 74 on to the latest
0a80: 20 74 63 6c 63 6f 6e 66 69 67 20 72 65 6c 65 61 tclconfig relea
0a90: 73 65 2e 20 54 45 41 20 28 6c 61 74 65 73 74 20 se. TEA (latest
0aa0: 74 63 6c 2e 6d 34 2f 72 75 6c 65 73 2e 76 63 20 tcl.m4/rules.vc
0ab0: 66 69 6c 65 73 29 20 74 61 6b 65 73 20 63 61 72 files) takes car
0ac0: 65 20 6f 66 20 70 72 6f 76 69 64 69 6e 67 20 61 e of providing a
0ad0: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 70 72 n appropriate pr
0ae0: 65 70 72 6f 63 65 73 73 6f 72 20 23 64 65 66 69 eprocessor #defi
0af0: 6e 65 20 66 6f 72 20 60 54 63 6c 5f 53 69 7a 65 ne for `Tcl_Size
0b00: 60 2e 0d 0a 0d 0a 4e 6f 74 65 20 74 68 65 72 65 `.....Note there
0b10: 20 69 73 20 6e 6f 20 63 6f 6d 70 6c 65 6d 65 6e is no complemen
0b20: 74 61 72 79 20 60 54 63 6c 5f 4e 65 77 53 69 7a tary `Tcl_NewSiz
0b30: 65 49 6e 74 46 72 6f 6d 4f 62 6a 60 2e 20 55 73 eIntFromObj`. Us
0b40: 65 20 60 54 63 6c 5f 4e 65 77 57 69 64 65 49 6e e `Tcl_NewWideIn
0b50: 74 4f 62 6a 60 20 69 6e 20 69 74 73 20 73 74 65 tObj` in its ste
0b60: 61 64 20 74 6f 20 77 72 61 70 20 60 54 63 6c 5f ad to wrap `Tcl_
0b70: 53 69 7a 65 60 20 76 61 6c 75 65 73 2e 20 44 6f Size` values. Do
0b80: 20 2a 2a 6e 6f 74 2a 2a 20 75 73 65 20 60 54 63 **not** use `Tc
0b90: 6c 5f 4e 65 77 49 6e 74 4f 62 6a 60 20 61 73 20 l_NewIntObj` as
0ba0: 69 74 20 77 69 6c 6c 20 74 72 75 6e 63 61 74 65 it will truncate
0bb0: 20 76 61 6c 75 65 73 20 61 62 6f 76 65 20 34 47 values above 4G
0bc0: 62 2e 0d 0a 0d 0a 50 61 75 6c 20 4f 62 65 72 6d b.....Paul Oberm
0bd0: 65 69 65 72 27 73 20 76 65 72 79 20 75 73 65 66 eier's very usef
0be0: 75 6c 20 70 6f 73 74 20 5b 54 63 6c 20 39 20 66 ul post [Tcl 9 f
0bf0: 75 6e 63 74 69 6f 6e 73 20 75 73 69 6e 67 20 54 unctions using T
0c00: 63 6c 5f 53 69 7a 65 5d 28 68 74 74 70 73 3a 2f cl_Size](https:/
0c10: 2f 77 69 6b 69 2e 74 63 6c 2d 6c 61 6e 67 2e 6f /wiki.tcl-lang.o
0c20: 72 67 2f 70 61 67 65 2f 54 63 6c 2b 39 2b 66 75 rg/page/Tcl+9+fu
0c30: 6e 63 74 69 6f 6e 73 2b 75 73 69 6e 67 2b 54 63 nctions+using+Tc
0c40: 6c 25 35 46 53 69 7a 65 29 0d 0a 65 6e 75 6d 65 l%5FSize)..enume
0c50: 72 61 74 65 73 20 74 68 65 20 66 75 6e 63 74 69 rates the functi
0c60: 6f 6e 73 20 69 6e 20 74 68 65 20 54 63 6c 20 41 ons in the Tcl A
0c70: 50 49 20 61 66 66 65 63 74 65 64 20 62 79 20 74 PI affected by t
0c80: 68 69 73 20 63 68 61 6e 67 65 0d 0a 61 6e 64 20 his change..and
0c90: 70 72 6f 76 69 64 65 73 20 61 20 73 63 72 69 70 provides a scrip
0ca0: 74 20 74 6f 20 6c 6f 63 61 74 65 20 74 68 65 20 t to locate the
0cb0: 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e use of these fun
0cc0: 63 74 69 6f 6e 73 20 77 69 74 68 69 6e 0d 0a 65 ctions within..e
0cd0: 78 74 65 6e 73 69 6f 6e 73 20 61 6e 64 20 61 70 xtensions and ap
0ce0: 70 6c 69 63 61 74 69 6f 6e 73 2e 0d 0a 0d 0a 53 plications.....S
0cf0: 65 65 20 5b 54 49 50 20 36 36 30 5d 28 68 74 74 ee [TIP 660](htt
0d00: 70 73 3a 2f 2f 63 6f 72 65 2e 74 63 6c 2d 6c 61 ps://core.tcl-la
0d10: 6e 67 2e 6f 72 67 2f 74 69 70 73 2f 64 6f 63 2f ng.org/tips/doc/
0d20: 74 72 75 6e 6b 2f 74 69 70 2f 36 36 30 2e 6d 64 trunk/tip/660.md
0d30: 29 0d 0a 0d 0a 23 23 20 55 6e 69 63 6f 64 65 20 )....## Unicode
0d40: 73 75 70 70 6f 72 74 0d 0a 0d 0a 23 23 23 20 60 support....### `
0d50: 54 63 6c 5f 55 6e 69 43 68 61 72 60 20 61 6e 64 Tcl_UniChar` and
0d60: 20 60 54 43 4c 5f 55 54 46 5f 4d 41 58 60 0d 0a `TCL_UTF_MAX`..
0d70: 0d 0a 41 73 20 70 61 72 74 20 6f 66 20 74 68 65 ..As part of the
0d80: 20 63 68 61 6e 67 65 73 20 74 6f 20 73 75 70 70 changes to supp
0d90: 6f 72 74 20 74 68 65 20 66 75 6c 6c 20 72 61 6e ort the full ran
0da0: 67 65 20 6f 66 20 55 6e 69 63 6f 64 65 20 63 6f ge of Unicode co
0db0: 64 65 20 70 6f 69 6e 74 73 2c 20 74 68 65 0d 0a de points, the..
0dc0: 60 54 63 6c 5f 55 6e 69 43 68 61 72 60 20 74 79 `Tcl_UniChar` ty
0dd0: 70 65 20 68 61 73 20 63 68 61 6e 67 65 64 20 74 pe has changed t
0de0: 6f 20 61 20 33 32 2d 62 69 74 20 69 6e 74 65 67 o a 32-bit integ
0df0: 65 72 20 74 79 70 65 2e 20 43 6f 72 72 65 73 70 er type. Corresp
0e00: 6f 6e 64 69 6e 67 6c 79 2c 20 74 68 65 0d 0a 64 ondingly, the..d
0e10: 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6f 66 20 efault value of
0e20: 60 54 43 4c 5f 55 54 46 5f 4d 41 58 60 20 69 73 `TCL_UTF_MAX` is
0e30: 20 6e 6f 77 20 34 2e 0d 0a 0d 0a 54 68 69 73 20 now 4.....This
0e40: 6d 65 61 6e 73 20 74 68 61 74 20 65 6e 63 6f 64 means that encod
0e50: 69 6e 67 20 41 50 49 27 73 20 73 75 63 68 20 61 ing API's such a
0e60: 73 20 60 54 63 6c 5f 47 65 74 55 6e 69 63 6f 64 s `Tcl_GetUnicod
0e70: 65 46 72 6f 6d 4f 62 6a 60 20 74 68 61 74 20 77 eFromObj` that w
0e80: 6f 72 6b 20 77 69 74 68 0d 0a 60 54 63 6c 5f 55 ork with..`Tcl_U
0e90: 6e 69 43 68 61 72 60 20 73 74 72 69 6e 67 73 20 niChar` strings
0ea0: 63 61 6e 20 6e 6f 20 6c 6f 6e 67 65 72 20 62 65 can no longer be
0eb0: 20 75 73 65 64 20 74 6f 20 70 61 73 73 20 76 61 used to pass va
0ec0: 6c 75 65 73 20 74 6f 20 65 78 74 65 72 6e 61 6c lues to external
0ed0: 20 41 50 49 27 73 0d 0a 74 68 61 74 20 65 78 70 API's..that exp
0ee0: 65 63 74 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 ect UTF-16 encod
0ef0: 65 64 20 73 74 72 69 6e 67 73 2e 20 54 68 69 73 ed strings. This
0f00: 20 69 73 20 70 61 72 74 69 63 75 6c 61 72 6c 79 is particularly
0f10: 20 72 65 6c 65 76 61 6e 74 20 6f 6e 20 57 69 6e relevant on Win
0f20: 64 6f 77 73 0d 0a 70 6c 61 74 66 6f 72 6d 73 20 dows..platforms
0f30: 77 68 65 72 65 20 69 74 20 77 61 73 20 63 6f 6d where it was com
0f40: 6d 6f 6e 20 69 6e 20 54 63 6c 20 38 20 74 6f 20 mon in Tcl 8 to
0f50: 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 use these functi
0f60: 6f 6e 73 20 74 6f 20 74 72 61 6e 73 66 6f 72 6d ons to transform
0f70: 0d 0a 73 74 72 69 6e 67 73 20 74 6f 20 74 68 65 ..strings to the
0f80: 20 55 54 46 2d 31 36 20 2f 20 55 43 53 2d 32 20 UTF-16 / UCS-2
0f90: 66 6f 72 6d 20 65 78 70 65 63 74 65 64 20 62 79 form expected by
0fa0: 20 74 68 65 20 57 69 6e 33 32 20 41 50 49 2e 20 the Win32 API.
0fb0: 49 6e 73 74 65 61 64 2c 20 75 73 65 20 65 69 74 Instead, use eit
0fc0: 68 65 72 0d 0a 0d 0a 2a 20 74 68 65 20 55 54 46 her....* the UTF
0fd0: 2d 31 36 20 73 70 65 63 69 66 69 63 20 60 54 63 -16 specific `Tc
0fe0: 6c 5f 43 68 61 72 31 36 54 6f 55 74 66 44 53 74 l_Char16ToUtfDSt
0ff0: 72 69 6e 67 60 2c 20 60 54 63 6c 5f 55 74 66 54 ring`, `Tcl_UtfT
1000: 6f 43 68 61 72 31 36 44 53 74 72 69 6e 67 60 2c oChar16DString`,
1010: 0d 0a 60 54 63 6c 5f 55 74 66 54 6f 43 68 61 72 ..`Tcl_UtfToChar
1020: 31 36 60 20 66 75 6e 63 74 69 6f 6e 73 2c 20 6f 16` functions, o
1030: 72 0d 0a 0d 0a 2a 20 74 68 65 20 67 65 6e 65 72 r....* the gener
1040: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 60 54 63 ic functions `Tc
1050: 6c 5f 55 74 66 54 6f 45 78 74 65 72 6e 61 6c 44 l_UtfToExternalD
1060: 53 74 72 69 6e 67 45 78 60 2c 20 60 54 63 6c 5f StringEx`, `Tcl_
1070: 45 78 74 65 72 6e 61 6c 74 6f 55 74 66 44 53 74 ExternaltoUtfDSt
1080: 72 69 6e 67 45 78 60 2c 0d 0a 60 54 63 6c 5f 55 ringEx`,..`Tcl_U
1090: 74 66 54 6f 45 78 74 65 72 6e 61 6c 60 2c 20 60 tfToExternal`, `
10a0: 54 63 6c 5f 45 78 74 65 72 6e 61 6c 54 6f 55 74 Tcl_ExternalToUt
10b0: 66 60 20 77 69 74 68 20 74 68 65 20 60 75 74 66 f` with the `utf
10c0: 2d 31 36 60 20 65 6e 63 6f 64 69 6e 67 2e 0d 0a -16` encoding...
10d0: 0d 0a 23 23 23 20 45 6e 63 6f 64 69 6e 67 20 74 ..### Encoding t
10e0: 72 61 6e 73 66 6f 72 6d 73 0d 0a 0d 0a 54 63 6c ransforms....Tcl
10f0: 20 39 20 73 75 70 70 6f 72 74 73 20 2a 65 6e 63 9 supports *enc
1100: 6f 64 69 6e 67 20 70 72 6f 66 69 6c 65 73 2a 20 oding profiles*
1110: 74 68 61 74 20 61 6c 6c 6f 77 20 63 6f 6e 74 72 that allow contr
1120: 6f 6c 20 6f 66 20 68 6f 77 20 65 72 72 6f 72 73 ol of how errors
1130: 20 61 72 65 20 68 61 6e 64 6c 65 64 0d 0a 69 6e are handled..in
1140: 20 65 6e 63 6f 64 69 6e 67 20 74 72 61 6e 73 66 encoding transf
1150: 6f 72 6d 73 2e 20 41 74 20 74 68 65 20 43 20 41 orms. At the C A
1160: 50 49 20 6c 65 76 65 6c 2c 20 70 72 6f 66 69 6c PI level, profil
1170: 65 73 20 61 72 65 20 70 61 73 73 65 64 20 62 79 es are passed by
1180: 20 6f 72 2d 69 6e 67 20 6f 6e 65 20 6f 66 0d 0a or-ing one of..
1190: 74 68 65 20 60 54 43 4c 5f 50 52 4f 46 49 4c 45 the `TCL_PROFILE
11a0: 5f 2a 60 20 76 61 6c 75 65 73 20 61 73 20 70 61 _*` values as pa
11b0: 72 74 20 6f 66 20 74 68 65 20 60 66 6c 61 67 73 rt of the `flags
11c0: 60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 ` parameter to e
11d0: 6e 63 6f 64 69 6e 67 0d 0a 74 72 61 6e 73 66 6f ncoding..transfo
11e0: 72 6d 20 66 75 6e 63 74 69 6f 6e 73 20 6c 69 6b rm functions lik
11f0: 65 20 60 54 63 6c 5f 45 78 74 65 72 6e 61 6c 54 e `Tcl_ExternalT
1200: 6f 55 74 66 60 20 61 6e 64 20 60 54 63 6c 5f 55 oUtf` and `Tcl_U
1210: 74 66 54 6f 45 78 74 65 72 6e 61 6c 60 2e 0d 0a tfToExternal`...
1220: 0d 0a 45 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 ..Extensions tha
1230: 74 20 6f 72 2d 65 64 20 60 54 43 4c 5f 45 4e 43 t or-ed `TCL_ENC
1240: 4f 44 49 4e 47 5f 53 54 4f 50 4f 4e 45 52 52 4f ODING_STOPONERRO
1250: 52 60 20 69 6e 20 74 68 65 20 60 66 6c 61 67 73 R` in the `flags
1260: 60 20 70 61 72 61 6d 65 74 65 72 0d 0a 74 6f 20 ` parameter..to
1270: 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
1280: 69 6e 20 54 63 6c 20 38 20 73 68 6f 75 6c 64 20 in Tcl 8 should
1290: 6e 6f 77 20 75 73 65 20 60 54 43 4c 5f 45 4e 43 now use `TCL_ENC
12a0: 4f 44 49 4e 47 5f 50 52 4f 46 49 4c 45 5f 53 54 ODING_PROFILE_ST
12b0: 52 49 43 54 60 0d 0a 69 6e 73 74 65 61 64 20 6f RICT`..instead o
12c0: 72 20 6e 6f 74 20 73 70 65 63 69 66 79 20 61 20 r not specify a
12d0: 70 72 6f 66 69 6c 65 20 61 74 20 61 6c 6c 20 61 profile at all a
12e0: 73 20 60 73 74 72 69 63 74 60 20 69 73 20 74 68 s `strict` is th
12f0: 65 20 64 65 66 61 75 6c 74 20 69 6e 20 61 6e 79 e default in any
1300: 20 63 61 73 65 2e 0d 0a 0d 0a 45 78 74 65 6e 73 case.....Extens
1310: 69 6f 6e 73 20 74 68 61 74 20 64 69 64 20 6e 6f ions that did no
1320: 74 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 60 54 t make use of `T
1330: 43 4c 5f 45 4e 43 4f 44 49 4e 47 5f 53 54 4f 50 CL_ENCODING_STOP
1340: 4f 4e 45 52 52 4f 52 60 20 77 69 6c 6c 20 73 65 ONERROR` will se
1350: 65 0d 0a 61 20 63 68 61 6e 67 65 20 69 6e 20 74 e..a change in t
1360: 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hat the function
1370: 73 20 64 65 66 61 75 6c 74 20 74 6f 20 74 68 65 s default to the
1380: 20 73 74 72 69 63 74 20 70 72 6f 66 69 6c 65 20 strict profile
1390: 61 6e 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 0d and will return.
13a0: 0a 61 6e 20 65 72 72 6f 72 20 6f 6e 20 69 6e 76 .an error on inv
13b0: 61 6c 69 64 20 65 6e 63 6f 64 69 6e 67 20 62 79 alid encoding by
13c0: 74 65 73 2e 20 54 6f 20 72 65 76 65 72 74 20 74 tes. To revert t
13d0: 6f 20 54 63 6c 20 38 20 62 65 68 61 76 69 6f 72 o Tcl 8 behavior
13e0: 2c 20 74 68 65 0d 0a 60 54 43 4c 5f 45 4e 43 4f , the..`TCL_ENCO
13f0: 44 49 4e 47 5f 50 52 4f 46 49 4c 45 5f 54 43 4c DING_PROFILE_TCL
1400: 38 60 20 6d 75 73 74 20 62 65 20 73 70 65 63 69 8` must be speci
1410: 66 69 65 64 2e 20 41 6c 74 65 72 6e 61 74 69 76 fied. Alternativ
1420: 65 6c 79 2c 0d 0a 60 54 43 4c 5f 45 4e 43 4f 44 ely,..`TCL_ENCOD
1430: 49 4e 47 5f 50 52 4f 46 49 4c 45 5f 52 45 50 4c ING_PROFILE_REPL
1440: 41 43 45 60 20 6d 61 79 20 62 65 20 75 73 65 64 ACE` may be used
1450: 20 74 6f 20 77 68 69 63 68 20 69 73 20 73 74 61 to which is sta
1460: 6e 64 61 72 64 2d 63 6f 6d 70 6c 69 61 6e 74 0d ndard-compliant.
1470: 0a 62 75 74 20 64 6f 65 73 20 6e 6f 74 20 72 61 .but does not ra
1480: 69 73 65 20 61 6e 20 65 72 72 6f 72 20 6f 6e 20 ise an error on
1490: 69 6e 76 61 6c 69 64 20 65 6e 63 6f 64 69 6e 67 invalid encoding
14a0: 73 2e 0d 0a 0d 0a 53 65 65 20 5b 54 49 50 20 36 s.....See [TIP 6
14b0: 35 36 5d 28 68 74 74 70 73 3a 2f 2f 63 6f 72 65 56](https://core
14c0: 2e 74 63 6c 2d 6c 61 6e 67 2e 6f 72 67 2f 74 69 .tcl-lang.org/ti
14d0: 70 73 2f 64 6f 63 2f 74 72 75 6e 6b 2f 74 69 70 ps/doc/trunk/tip
14e0: 2f 36 35 36 2e 6d 64 29 0d 0a 0d 0a 23 23 20 45 /656.md)....## E
14f0: 6e 63 6f 64 69 6e 67 20 65 72 72 6f 72 73 20 6f ncoding errors o
1500: 6e 20 49 2f 4f 0d 0a 0d 0a 49 6e 20 54 63 6c 20 n I/O....In Tcl
1510: 38 2c 20 61 6e 79 20 69 6e 76 61 6c 69 64 20 62 8, any invalid b
1520: 79 74 65 20 73 65 71 75 65 6e 63 65 20 65 6e 63 yte sequence enc
1530: 6f 75 6e 74 65 72 65 64 20 69 6e 20 63 68 61 6e ountered in chan
1540: 6e 65 6c 20 69 6e 70 75 74 20 77 65 72 65 20 73 nel input were s
1550: 69 6c 65 6e 74 6c 79 0d 0a 68 61 6e 64 6c 65 64 ilently..handled
1560: 20 62 79 20 74 72 65 61 74 69 6e 67 20 74 68 65 by treating the
1570: 20 69 6e 76 61 6c 69 64 20 62 79 74 65 73 20 61 invalid bytes a
1580: 73 20 69 73 6f 38 38 35 39 2d 31 20 65 6e 63 6f s iso8859-1 enco
1590: 64 65 64 20 62 79 74 65 73 2e 20 53 69 6d 69 6c ded bytes. Simil
15a0: 61 72 6c 79 2c 20 6f 6e 0d 0a 6f 75 74 70 75 74 arly, on..output
15b0: 20 54 63 6c 20 72 65 70 6c 61 63 65 64 20 63 68 Tcl replaced ch
15c0: 61 72 61 63 74 65 72 73 20 74 68 61 74 20 63 6f aracters that co
15d0: 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 70 72 65 uld not be repre
15e0: 73 65 6e 74 65 64 20 69 6e 20 74 68 65 20 63 68 sented in the ch
15f0: 61 6e 6e 65 6c 0d 0a 65 6e 63 6f 64 69 6e 67 20 annel..encoding
1600: 77 69 74 68 20 61 6e 20 65 6e 63 6f 64 69 6e 67 with an encoding
1610: 2d 73 70 65 63 69 66 69 63 20 72 65 70 6c 61 63 -specific replac
1620: 65 6d 65 6e 74 20 63 68 61 72 61 63 74 65 72 2c ement character,
1630: 20 75 73 75 61 6c 6c 79 20 60 3f 60 2e 20 49 6e usually `?`. In
1640: 0d 0a 63 6f 6e 74 72 61 73 74 2c 20 63 68 61 6e ..contrast, chan
1650: 6e 65 6c 20 49 2f 4f 20 69 6e 20 54 63 6c 20 39 nel I/O in Tcl 9
1660: 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 20 73 is by default s
1670: 75 62 6a 65 63 74 20 74 6f 20 74 68 65 20 60 73 ubject to the `s
1680: 74 72 69 63 74 60 20 65 6e 63 6f 64 69 6e 67 0d trict` encoding.
1690: 0a 70 72 6f 66 69 6c 65 20 61 6e 64 20 74 68 65 .profile and the
16a0: 20 61 62 6f 76 65 20 61 72 65 20 74 72 65 61 74 above are treat
16b0: 65 64 20 61 73 20 65 72 72 6f 72 20 63 6f 6e 64 ed as error cond
16c0: 69 74 69 6f 6e 73 2e 20 46 75 6e 63 74 69 6f 6e itions. Function
16d0: 73 20 6c 69 6b 65 0d 0a 60 54 63 6c 5f 52 65 61 s like..`Tcl_Rea
16e0: 64 60 2c 20 60 54 63 6c 5f 47 65 74 73 60 20 65 d`, `Tcl_Gets` e
16f0: 74 63 2e 20 6f 6e 20 69 6e 70 75 74 20 61 6e 64 tc. on input and
1700: 20 60 54 63 6c 5f 57 72 69 74 65 60 20 65 74 63 `Tcl_Write` etc
1710: 2e 20 6f 6e 20 6f 75 74 70 75 74 20 77 69 6c 6c . on output will
1720: 20 72 61 69 73 65 0d 0a 61 6e 20 65 72 72 6f 72 raise..an error
1730: 20 66 6f 72 20 74 68 65 73 65 20 63 61 73 65 73 for these cases
1740: 2e 0d 0a 0d 0a 41 70 70 6c 69 63 61 74 69 6f 6e .....Application
1750: 73 20 61 6e 64 20 65 78 74 65 6e 73 69 6f 6e 73 s and extensions
1760: 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 6d 61 that need to ma
1770: 74 63 68 20 54 63 6c 20 38 20 62 65 68 61 76 69 tch Tcl 8 behavi
1780: 6f 72 20 66 6f 72 20 63 6f 6d 70 61 74 69 62 69 or for compatibi
1790: 6c 69 74 79 0d 0a 72 65 61 73 6f 6e 73 20 63 61 lity..reasons ca
17a0: 6e 20 73 65 74 20 74 68 65 20 60 2d 70 72 6f 66 n set the `-prof
17b0: 69 6c 65 60 20 63 6f 6e 66 69 67 75 72 61 74 69 ile` configurati
17c0: 6f 6e 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 on option for th
17d0: 65 20 63 68 61 6e 6e 65 6c 20 74 6f 20 60 74 63 e channel to `tc
17e0: 6c 38 60 20 76 69 61 0d 0a 74 68 65 20 60 54 63 l8` via..the `Tc
17f0: 6c 5f 53 65 74 43 68 61 6e 6e 65 6c 4f 70 74 69 l_SetChannelOpti
1800: 6f 6e 60 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 on` function. Th
1810: 69 73 20 69 73 20 68 6f 77 65 76 65 72 20 6e 6f is is however no
1820: 6e 2d 63 6f 6e 66 6f 72 6d 61 6e 74 20 77 69 74 n-conformant wit
1830: 68 20 74 68 65 0d 0a 55 6e 69 63 6f 64 65 20 73 h the..Unicode s
1840: 74 61 6e 64 61 72 64 20 61 6e 64 20 69 73 20 6e tandard and is n
1850: 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 20 ot recommended.
1860: 41 20 73 74 61 6e 64 61 72 64 2d 63 6f 6e 66 6f A standard-confo
1870: 72 6d 61 6e 74 20 61 6c 74 65 72 6e 61 74 69 76 rmant alternativ
1880: 65 20 69 73 0d 0a 74 6f 20 73 65 74 20 74 68 65 e is..to set the
1890: 20 70 72 6f 66 69 6c 65 20 74 6f 20 60 72 65 70 profile to `rep
18a0: 6c 61 63 65 60 20 69 6e 73 74 65 61 64 2e 0d 0a lace` instead...
18b0: 0d 0a 53 65 65 20 5b 54 49 50 20 36 35 37 5d 28 ..See [TIP 657](
18c0: 68 74 74 70 73 3a 2f 2f 63 6f 72 65 2e 74 63 6c https://core.tcl
18d0: 2d 6c 61 6e 67 2e 6f 72 67 2f 74 69 70 73 2f 64 -lang.org/tips/d
18e0: 6f 63 2f 74 72 75 6e 6b 2f 74 69 70 2f 36 35 37 oc/trunk/tip/657
18f0: 2e 6d 64 29 0d 0a 0d 0a 23 23 20 60 54 63 6c 5f .md)....## `Tcl_
1900: 4f 62 6a 54 79 70 65 60 20 76 65 72 73 69 6f 6e ObjType` version
1910: 69 6e 67 0d 0a 0d 0a 54 68 65 20 54 63 6c 20 76 ing....The Tcl v
1920: 61 6c 75 65 20 73 79 73 74 65 6d 20 68 61 73 20 alue system has
1930: 62 65 65 6e 20 65 78 74 65 6e 64 65 64 2e 20 54 been extended. T
1940: 68 65 20 60 54 63 6c 5f 4f 62 6a 54 79 70 65 60 he `Tcl_ObjType`
1950: 20 68 61 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 has additional
1960: 28 6f 70 74 69 6f 6e 61 6c 29 20 66 69 65 6c 64 (optional) field
1970: 73 2e 20 20 41 6e 79 20 54 63 6c 20 65 78 74 65 s. Any Tcl exte
1980: 6e 73 69 6f 6e 73 2c 20 6f 72 20 65 6d 62 65 64 nsions, or embed
1990: 64 65 64 20 69 6e 74 65 67 72 61 74 69 6f 6e 20 ded integration
19a0: 77 69 74 68 20 54 63 6c 2c 20 74 68 61 74 20 68 with Tcl, that h
19b0: 61 73 20 61 20 63 75 73 74 6f 6d 20 60 54 63 6c as a custom `Tcl
19c0: 5f 4f 62 6a 54 79 70 65 60 20 76 61 6c 75 65 20 _ObjType` value
19d0: 64 65 66 69 6e 65 64 2c 20 73 68 6f 75 6c 64 20 defined, should
19e0: 72 65 76 69 65 77 20 74 68 65 73 65 20 63 68 61 review these cha
19f0: 6e 67 65 73 2e 20 20 45 78 69 73 74 69 6e 67 20 nges. Existing
1a00: 63 6f 64 65 20 73 68 6f 75 6c 64 20 63 6f 6d 70 code should comp
1a10: 69 6c 65 20 61 6e 64 20 65 78 65 63 75 74 65 20 ile and execute
1a20: 6a 75 73 74 20 66 69 6e 65 2c 20 75 6e 6c 65 73 just fine, unles
1a30: 73 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 s the particular
1a40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1a50: 69 73 20 75 73 69 6e 67 20 61 6e 79 20 22 63 72 is using any "cr
1a60: 65 61 74 69 76 65 22 20 70 72 6f 67 72 61 6d 6d eative" programm
1a70: 69 6e 67 2e 20 49 6e 20 73 69 6d 70 6c 65 72 20 ing. In simpler
1a80: 74 65 72 6d 73 2c 20 74 68 65 20 60 54 63 6c 5f terms, the `Tcl_
1a90: 4f 62 6a 54 79 70 65 60 20 73 74 72 75 63 74 75 ObjType` structu
1aa0: 72 65 20 69 73 20 6c 61 72 67 65 72 2e 20 49 74 re is larger. It
1ab0: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 69 74 69 should be initi
1ac0: 61 6c 69 7a 65 64 20 70 72 6f 70 65 72 6c 79 20 alized properly
1ad0: 77 69 74 68 6f 75 74 20 61 6e 79 20 63 68 61 6e without any chan
1ae0: 67 65 73 20 6e 65 65 64 65 64 2c 20 62 75 74 20 ges needed, but
1af0: 59 4d 4d 56 2e 0d 0a 0d 0a 50 6c 65 61 73 65 20 YMMV.....Please
1b00: 73 65 65 20 74 68 65 20 60 54 63 6c 5f 52 65 67 see the `Tcl_Reg
1b10: 69 73 74 65 72 4f 62 6a 54 79 70 65 60 20 6d 61 isterObjType` ma
1b20: 6e 75 61 6c 20 70 61 67 65 20 66 6f 72 20 6d 6f nual page for mo
1b30: 72 65 20 64 65 74 61 69 6c 73 2c 20 61 73 20 77 re details, as w
1b40: 65 6c 6c 20 61 73 20 54 49 50 27 73 20 5b 36 33 ell as TIP's [63
1b50: 36 5d 28 68 74 74 70 73 3a 2f 2f 63 6f 72 65 2e 6](https://core.
1b60: 74 63 6c 2d 6c 61 6e 67 2e 6f 72 67 2f 74 69 70 tcl-lang.org/tip
1b70: 73 2f 64 6f 63 2f 74 72 75 6e 6b 2f 74 69 70 2f s/doc/trunk/tip/
1b80: 36 33 36 2e 6d 64 29 20 61 6e 64 20 5b 36 34 34 636.md) and [644
1b90: 5d 28 68 74 74 70 73 3a 2f 2f 63 6f 72 65 2e 74 ](https://core.t
1ba0: 63 6c 2d 6c 61 6e 67 2e 6f 72 67 2f 74 69 70 73 cl-lang.org/tips
1bb0: 2f 64 6f 63 2f 74 72 75 6e 6b 2f 74 69 70 2f 36 /doc/trunk/tip/6
1bc0: 34 34 2e 6d 64 29 2e 0d 0a 0d 0a 23 23 20 41 62 44.md).....## Ab
1bd0: 73 74 72 61 63 74 20 6c 69 73 74 73 0d 0a 0d 0a stract lists....
1be0: 41 6e 20 61 62 73 74 72 61 63 74 20 6c 69 73 74 An abstract list
1bf0: 20 69 73 20 61 20 63 75 73 74 6f 6d 20 54 63 6c is a custom Tcl
1c00: 20 76 61 6c 75 65 20 28 63 75 73 74 6f 6d 20 60 value (custom `
1c10: 54 63 6c 5f 4f 62 6a 54 79 70 65 60 29 20 74 68 Tcl_ObjType`) th
1c20: 61 74 20 63 61 6e 20 62 65 20 74 72 65 61 74 65 at can be treate
1c30: 64 20 61 73 20 61 20 54 63 6c 20 6c 69 73 74 20 d as a Tcl list
1c40: 61 74 20 74 68 65 20 73 63 72 69 70 74 20 6c 65 at the script le
1c50: 76 65 6c 20 77 69 74 68 6f 75 74 20 63 61 75 73 vel without caus
1c60: 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 74 6f ing the value to
1c70: 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f be converted to
1c80: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 4c 69 the internal Li
1c90: 73 74 20 74 79 70 65 2e 20 54 6f 20 6d 61 6b 65 st type. To make
1ca0: 20 74 68 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 this possible,
1cb0: 74 68 65 20 63 75 73 74 6f 6d 20 74 79 70 65 20 the custom type
1cc0: 6d 75 73 74 20 69 6d 70 6c 65 6d 65 6e 74 20 61 must implement a
1cd0: 20 73 65 74 20 6f 66 20 61 63 63 65 73 73 6f 72 set of accessor
1ce0: 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 72 72 65 functions corre
1cf0: 73 70 6f 6e 64 69 6e 67 20 74 6f 20 6c 69 73 74 sponding to list
1d00: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 0d 0a 0d operations. ...
1d10: 0a 53 65 65 20 74 68 65 20 60 54 63 6c 5f 52 65 .See the `Tcl_Re
1d20: 67 69 73 74 65 72 4f 62 6a 54 79 70 65 60 20 6d gisterObjType` m
1d30: 61 6e 75 61 6c 20 70 61 67 65 20 66 6f 72 20 6d anual page for m
1d40: 6f 72 65 20 64 65 74 61 69 6c 73 2c 20 61 73 20 ore details, as
1d50: 77 65 6c 6c 20 61 73 20 54 49 50 27 73 20 5b 36 well as TIP's [6
1d60: 33 36 5d 28 68 74 74 70 73 3a 2f 2f 63 6f 72 65 36](https://core
1d70: 2e 74 63 6c 2d 6c 61 6e 67 2e 6f 72 67 2f 74 69 .tcl-lang.org/ti
1d80: 70 73 2f 64 6f 63 2f 74 72 75 6e 6b 2f 74 69 70 ps/doc/trunk/tip
1d90: 2f 36 33 36 2e 6d 64 29 20 61 6e 64 20 5b 36 34 /636.md) and [64
1da0: 34 5d 28 68 74 74 70 73 3a 2f 2f 63 6f 72 65 2e 4](https://core.
1db0: 74 63 6c 2d 6c 61 6e 67 2e 6f 72 67 2f 74 69 70 tcl-lang.org/tip
1dc0: 73 2f 64 6f 63 2f 74 72 75 6e 6b 2f 74 69 70 2f s/doc/trunk/tip/
1dd0: 36 34 34 2e 6d 64 29 2e 0d 0a 0d 0a 23 23 23 20 644.md).....###
1de0: 4d 65 6d 6f 72 79 20 6d 61 6e 61 67 65 6d 65 6e Memory managemen
1df0: 74 20 6f 66 20 6c 69 73 74 20 65 6c 65 6d 65 6e t of list elemen
1e00: 74 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 54 ts returned by T
1e10: 63 6c 5f 4c 69 73 74 4f 62 6a 49 6e 64 65 78 0d cl_ListObjIndex.
1e20: 0a 0d 0a 57 68 65 6e 20 64 65 61 6c 69 6e 67 20 ...When dealing
1e30: 77 69 74 68 20 6c 69 73 74 20 65 6c 65 6d 65 6e with list elemen
1e40: 74 73 2c 20 61 20 63 6f 6d 6d 6f 6e 20 6d 69 63 ts, a common mic
1e50: 72 6f 2d 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 ro-optimization
1e60: 70 72 61 63 74 69 63 65 20 69 6e 76 6f 6c 76 65 practice involve
1e70: 73 0d 0a 73 6b 69 70 70 69 6e 67 20 60 54 63 6c s..skipping `Tcl
1e80: 5f 49 6e 63 72 52 65 66 43 6f 75 6e 74 60 20 61 _IncrRefCount` a
1e90: 6e 64 20 60 54 63 6c 5f 44 65 63 72 52 65 66 43 nd `Tcl_DecrRefC
1ea0: 6f 75 6e 74 60 20 73 65 71 75 65 6e 63 65 73 20 ount` sequences
1eb0: 66 6f 72 20 61 20 60 54 63 6c 5f 4f 62 6a 60 0d for a `Tcl_Obj`.
1ec0: 0a 65 6c 65 6d 65 6e 74 20 72 65 74 75 72 6e 65 .element returne
1ed0: 64 20 62 79 20 60 54 63 6c 5f 4c 69 73 74 4f 62 d by `Tcl_ListOb
1ee0: 6a 49 6e 64 65 78 60 20 77 68 65 6e 20 74 68 65 jIndex` when the
1ef0: 20 75 73 65 20 69 73 20 6c 6f 63 61 6c 20 61 6e use is local an
1f00: 64 20 74 65 6d 70 6f 72 61 72 79 2e 20 49 6e 0d d temporary. In.
1f10: 0a 54 63 6c 20 38 2c 20 74 68 69 73 20 70 6f 73 .Tcl 8, this pos
1f20: 65 64 20 6e 6f 20 69 73 73 75 65 73 20 62 65 63 ed no issues bec
1f30: 61 75 73 65 20 74 68 65 20 6c 69 73 74 20 69 6d ause the list im
1f40: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
1f50: 65 72 6e 61 6c 6c 79 20 68 65 6c 64 20 61 0d 0a ernally held a..
1f60: 72 65 66 65 72 65 6e 63 65 20 74 6f 20 65 61 63 reference to eac
1f70: 68 20 65 6c 65 6d 65 6e 74 2c 20 65 6e 73 75 72 h element, ensur
1f80: 69 6e 67 20 74 68 61 74 20 74 68 65 20 65 6c 65 ing that the ele
1f90: 6d 65 6e 74 20 77 6f 75 6c 64 20 62 65 20 66 72 ment would be fr
1fa0: 65 65 64 20 28 61 73 73 75 6d 69 6e 67 20 6e 6f eed (assuming no
1fb0: 0d 0a 6f 74 68 65 72 20 72 65 66 65 72 65 6e 63 ..other referenc
1fc0: 65 73 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 es) along with t
1fd0: 68 65 20 70 61 72 65 6e 74 20 6c 69 73 74 2e 0d he parent list..
1fe0: 0a 0d 0a 48 6f 77 65 76 65 72 2c 20 77 69 74 68 ...However, with
1ff0: 20 74 68 65 20 69 6e 74 72 6f 64 75 63 74 69 6f the introductio
2000: 6e 20 6f 66 20 41 62 73 74 72 61 63 74 20 4c 69 n of Abstract Li
2010: 73 74 73 20 69 6e 20 54 63 6c 20 39 2c 20 74 68 sts in Tcl 9, th
2020: 69 73 20 67 75 61 72 61 6e 74 65 65 20 6e 6f 0d is guarantee no.
2030: 0a 6c 6f 6e 67 65 72 20 68 6f 6c 64 73 2e 20 41 .longer holds. A
2040: 62 73 74 72 61 63 74 20 6c 69 73 74 73 20 6d 61 bstract lists ma
2050: 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 72 65 74 y or may not ret
2060: 61 69 6e 20 61 20 72 65 66 65 72 65 6e 63 65 20 ain a reference
2070: 74 6f 20 60 54 63 6c 5f 4f 62 6a 60 0d 0a 65 6c to `Tcl_Obj`..el
2080: 65 6d 65 6e 74 73 20 72 65 74 75 72 6e 65 64 20 ements returned
2090: 66 72 6f 6d 20 60 54 63 6c 5f 4c 69 73 74 4f 62 from `Tcl_ListOb
20a0: 6a 49 6e 64 65 78 60 2e 20 53 70 65 63 69 66 69 jIndex`. Specifi
20b0: 63 61 6c 6c 79 2c 20 69 74 20 69 73 20 70 6f 73 cally, it is pos
20c0: 73 69 62 6c 65 20 66 6f 72 0d 0a 65 6c 65 6d 65 sible for..eleme
20d0: 6e 74 73 20 74 6f 20 62 65 20 63 72 65 61 74 65 nts to be create
20e0: 64 20 6f 6e 20 64 65 6d 61 6e 64 20 61 6e 64 20 d on demand and
20f0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 returned by the
2100: 69 6e 64 65 78 20 6f 70 65 72 61 74 69 6f 6e 20 index operation
2110: 77 69 74 68 6f 75 74 20 61 6e 0d 0a 69 6e 74 65 without an..inte
2120: 72 6e 61 6c 20 72 65 66 65 72 65 6e 63 65 20 62 rnal reference b
2130: 65 69 6e 67 20 68 65 6c 64 2e 20 49 6e 20 74 68 eing held. In th
2140: 65 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 60 e absence of a `
2150: 54 63 6c 5f 44 65 63 72 52 65 66 43 6f 75 6e 74 Tcl_DecrRefCount
2160: 60 20 63 61 6c 6c 0d 0a 6f 6e 20 74 68 65 20 65 ` call..on the e
2170: 6c 65 6d 65 6e 74 2c 20 74 68 65 20 60 54 63 6c lement, the `Tcl
2180: 5f 4f 62 6a 60 20 77 6f 75 6c 64 20 6e 65 76 65 _Obj` would neve
2190: 72 20 62 65 20 66 72 65 65 64 20 72 65 73 75 6c r be freed resul
21a0: 74 69 6e 67 20 69 6e 20 61 20 6d 65 6d 6f 72 79 ting in a memory
21b0: 20 6c 65 61 6b 2e 0d 0a 54 68 65 20 63 61 6c 6c leak...The call
21c0: 65 72 20 6e 65 65 64 73 20 74 6f 20 65 78 70 6c er needs to expl
21d0: 69 63 69 74 6c 79 20 63 61 6c 6c 20 60 54 63 6c icitly call `Tcl
21e0: 5f 44 65 63 72 52 65 66 43 6f 75 6e 74 60 20 6f _DecrRefCount` o
21f0: 6e 20 74 68 65 20 65 6c 65 6d 65 6e 74 0d 0a 60 n the element..`
2200: 54 63 6c 5f 4f 62 6a 60 20 74 6f 20 65 6e 73 75 Tcl_Obj` to ensu
2210: 72 65 20 69 74 20 69 73 20 66 72 65 65 64 2e 0d re it is freed..
2220: 0a 0d 0a 4f 6e 20 74 68 65 20 66 6c 69 70 20 73 ...On the flip s
2230: 69 64 65 2c 20 61 6e 20 61 62 73 74 72 61 63 74 ide, an abstract
2240: 20 6c 69 73 74 20 69 6d 70 6c 65 6d 65 6e 74 61 list implementa
2250: 74 69 6f 6e 20 6d 61 79 20 6d 69 6d 69 63 20 54 tion may mimic T
2260: 63 6c 20 38 20 62 65 68 61 76 69 6f 72 20 62 79 cl 8 behavior by
2270: 0d 0a 72 65 74 75 72 6e 69 6e 67 20 61 6e 20 65 ..returning an e
2280: 78 69 73 74 69 6e 67 20 69 6e 74 65 72 6e 61 6c xisting internal
2290: 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 61 20 reference to a
22a0: 60 54 63 6c 5f 4f 62 6a 60 20 77 69 74 68 6f 75 `Tcl_Obj` withou
22b0: 74 20 69 6e 63 72 65 6d 65 6e 74 69 6e 67 20 69 t incrementing i
22c0: 74 73 0d 0a 72 65 66 65 72 65 6e 63 65 20 63 6f ts..reference co
22d0: 75 6e 74 2e 20 49 6e 20 73 75 63 68 20 69 6e 73 unt. In such ins
22e0: 74 61 6e 63 65 73 2c 20 63 61 6c 6c 69 6e 67 20 tances, calling
22f0: 60 54 63 6c 5f 44 65 63 72 52 65 66 43 6f 75 6e `Tcl_DecrRefCoun
2300: 74 60 20 6f 6e 20 74 68 65 20 65 6c 65 6d 65 6e t` on the elemen
2310: 74 0d 0a 77 69 74 68 6f 75 74 20 61 20 63 6f 72 t..without a cor
2320: 72 65 73 70 6f 6e 64 69 6e 67 20 60 54 63 6c 5f responding `Tcl_
2330: 49 6e 63 72 52 65 66 43 6f 75 6e 74 60 20 77 6f IncrRefCount` wo
2340: 75 6c 64 20 72 65 6c 65 61 73 65 20 61 6e 20 69 uld release an i
2350: 6e 74 65 72 6e 61 6c 20 72 65 66 65 72 65 6e 63 nternal referenc
2360: 65 0d 0a 68 65 6c 64 20 62 79 20 74 68 65 20 61 e..held by the a
2370: 62 73 74 72 61 63 74 20 6c 69 73 74 20 69 6d 70 bstract list imp
2380: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 lementation and
2390: 70 72 65 6d 61 74 75 72 65 6c 79 20 66 72 65 65 prematurely free
23a0: 20 74 68 65 20 65 6c 65 6d 65 6e 74 20 72 65 73 the element res
23b0: 75 6c 74 69 6e 67 0d 0a 69 6e 20 75 73 65 2d 61 ulting..in use-a
23c0: 66 74 65 72 2d 66 72 65 65 20 62 75 67 73 2e 0d fter-free bugs..
23d0: 0a 0d 0a 54 6f 20 68 61 6e 64 6c 65 20 62 6f 74 ...To handle bot
23e0: 68 20 74 79 70 65 73 20 6f 66 20 69 6d 70 6c 65 h types of imple
23f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 63 6f 72 72 65 mentations corre
2400: 63 74 6c 79 2c 20 74 68 65 20 63 61 6c 6c 65 72 ctly, the caller
2410: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 20 75 should always u
2420: 73 65 0d 0a 74 68 65 20 60 54 63 6c 5f 42 6f 75 se..the `Tcl_Bou
2430: 6e 63 65 52 65 66 43 6f 75 6e 74 60 20 66 75 6e nceRefCount` fun
2440: 63 74 69 6f 6e 20 6f 6e 20 74 68 65 20 72 65 74 ction on the ret
2450: 75 72 6e 65 64 20 65 6c 65 6d 65 6e 74 20 60 54 urned element `T
2460: 63 6c 5f 4f 62 6a 60 20 77 68 65 6e 0d 0a 66 69 cl_Obj` when..fi
2470: 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
2480: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 77 69 This function wi
2490: 6c 6c 20 66 72 65 65 20 74 68 65 20 70 61 73 73 ll free the pass
24a0: 65 64 20 60 54 63 6c 5f 4f 62 6a 60 20 69 66 2c ed `Tcl_Obj` if,
24b0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 2c 20 74 68 and only if, th
24c0: 65 72 65 20 61 72 65 0d 0a 6e 6f 20 65 78 69 73 ere are..no exis
24d0: 74 69 6e 67 20 72 65 66 65 72 65 6e 63 65 73 20 ting references
24e0: 74 6f 20 69 74 2e 0d 0a 0d 0a 49 66 20 74 68 65 to it.....If the
24f0: 20 65 78 74 65 6e 73 69 6f 6e 20 6e 65 65 64 73 extension needs
2500: 20 74 6f 20 6d 61 69 6e 74 61 69 6e 20 63 6f 6d to maintain com
2510: 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 patibility with
2520: 54 63 6c 20 38 2e 36 2c 20 61 6e 20 61 6c 74 65 Tcl 8.6, an alte
2530: 72 6e 61 74 69 76 65 0d 0a 61 70 70 72 6f 61 63 rnative..approac
2540: 68 20 69 73 20 74 6f 20 70 65 72 66 6f 72 6d 20 h is to perform
2550: 61 20 70 61 69 72 20 6f 66 20 60 54 63 6c 5f 49 a pair of `Tcl_I
2560: 6e 63 72 52 65 66 43 6f 75 6e 74 60 20 61 6e 64 ncrRefCount` and
2570: 20 60 54 63 6c 5f 44 65 63 72 52 65 66 43 6f 75 `Tcl_DecrRefCou
2580: 6e 74 60 20 63 61 6c 6c 73 0d 0a 6f 6e 20 74 68 nt` calls..on th
2590: 65 20 65 6c 65 6d 65 6e 74 2e 20 57 68 69 6c 65 e element. While
25a0: 20 74 68 69 73 20 61 63 68 69 65 76 65 73 20 74 this achieves t
25b0: 68 65 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 he same effect a
25c0: 73 20 74 68 65 20 60 54 63 6c 5f 42 6f 75 6e 63 s the `Tcl_Bounc
25d0: 65 52 65 66 43 6f 75 6e 74 60 0d 0a 66 75 6e 63 eRefCount`..func
25e0: 74 69 6f 6e 2c 20 69 74 20 63 6f 6d 65 73 20 61 tion, it comes a
25f0: 74 20 74 68 65 20 63 6f 73 74 20 6f 66 20 61 20 t the cost of a
2600: 73 6c 69 67 68 74 20 65 66 66 69 63 69 65 6e 63 slight efficienc
2610: 79 20 74 72 61 64 65 2d 6f 66 66 2e 0d 0a 0d 0a y trade-off.....
2620: 23 23 23 20 50 72 65 66 65 72 20 54 63 6c 5f 4c ### Prefer Tcl_L
2630: 69 73 74 4f 62 6a 49 6e 64 65 78 20 74 6f 20 54 istObjIndex to T
2640: 63 6c 5f 4c 69 73 74 4f 62 6a 47 65 74 45 6c 65 cl_ListObjGetEle
2650: 6d 65 6e 74 73 20 66 6f 72 20 6c 61 72 67 65 20 ments for large
2660: 6c 69 73 74 73 0d 0a 0d 0a 54 68 65 20 69 6e 74 lists....The int
2670: 72 6f 64 75 63 74 69 6f 6e 20 6f 66 20 61 62 73 roduction of abs
2680: 74 72 61 63 74 20 6c 69 73 74 20 69 6d 70 6c 65 tract list imple
2690: 6d 65 6e 74 61 74 69 6f 6e 73 20 68 61 73 20 61 mentations has a
26a0: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e n additional con
26b0: 73 65 71 75 65 6e 63 65 0d 0a 72 65 6c 61 74 65 sequence..relate
26c0: 64 20 74 6f 20 69 74 65 72 61 74 69 6f 6e 20 6f d to iteration o
26d0: 76 65 72 20 6c 69 73 74 73 2e 20 49 6e 20 54 63 ver lists. In Tc
26e0: 6c 20 38 2c 20 69 74 20 77 61 73 20 63 6f 6d 6d l 8, it was comm
26f0: 6f 6e 20 70 72 61 63 74 69 63 65 20 74 6f 20 69 on practice to i
2700: 74 65 72 61 74 65 0d 0a 6f 76 65 72 20 6c 69 73 terate..over lis
2710: 74 20 65 6c 65 6d 65 6e 74 73 20 62 79 20 63 61 t elements by ca
2720: 6c 6c 69 6e 67 20 60 54 63 6c 5f 4c 69 73 74 4f lling `Tcl_ListO
2730: 62 6a 47 65 74 45 6c 65 6d 65 6e 74 73 60 20 77 bjGetElements` w
2740: 68 69 63 68 20 72 65 74 75 72 6e 65 64 20 61 20 hich returned a
2750: 70 6f 69 6e 74 65 72 0d 0a 74 6f 20 74 68 65 20 pointer..to the
2760: 61 72 72 61 79 20 6f 66 20 60 54 63 6c 5f 4f 62 array of `Tcl_Ob
2770: 6a 20 2a 60 20 65 6c 65 6d 65 6e 74 73 20 73 74 j *` elements st
2780: 6f 72 65 64 20 69 6e 20 74 68 65 20 69 6e 74 65 ored in the inte
2790: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
27a0: 69 6f 6e 20 6f 66 20 61 0d 0a 6c 69 73 74 2e 20 ion of a..list.
27b0: 49 6e 20 54 63 6c 20 39 2c 20 74 68 65 20 69 6e In Tcl 9, the in
27c0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
27d0: 61 74 69 6f 6e 20 6d 61 79 20 74 61 6b 65 20 61 ation may take a
27e0: 20 64 69 66 66 65 72 65 6e 74 20 66 6f 72 6d 20 different form
27f0: 61 6e 64 20 75 73 65 20 6f 66 0d 0a 74 68 69 73 and use of..this
2800: 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 63 65 73 function forces
2810: 20 67 65 6e 65 72 61 74 69 6f 6e 20 6f 66 20 61 generation of a
2820: 6e 20 61 72 72 61 79 20 77 69 74 68 20 70 6f 74 n array with pot
2830: 65 6e 74 69 61 6c 6c 79 20 73 69 67 6e 69 66 69 entially signifi
2840: 63 61 6e 74 6c 79 0d 0a 68 69 67 68 65 72 20 6d cantly..higher m
2850: 65 6d 6f 72 79 20 75 73 61 67 65 2e 20 46 6f 72 emory usage. For
2860: 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 60 6c example, the `l
2870: 73 65 71 60 20 63 6f 6d 6d 61 6e 64 20 77 68 69 seq` command whi
2880: 63 68 20 69 73 20 75 73 65 64 20 74 6f 20 63 72 ch is used to cr
2890: 65 61 74 65 20 61 0d 0a 6c 69 73 74 20 6f 66 20 eate a..list of
28a0: 69 6e 74 65 67 65 72 73 20 68 61 73 20 61 6e 20 integers has an
28b0: 65 78 74 72 65 6d 65 6c 79 20 63 6f 6d 70 61 63 extremely compac
28c0: 74 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 t internal repre
28d0: 73 65 6e 74 61 74 69 6f 6e 2e 20 41 20 6c 69 73 sentation. A lis
28e0: 74 20 6f 66 20 61 0d 0a 6d 69 6c 6c 69 6f 6e 20 t of a..million
28f0: 63 6f 6e 73 65 63 75 74 69 76 65 20 69 6e 74 65 consecutive inte
2900: 67 65 72 73 20 74 61 6b 65 73 20 75 70 20 75 6e gers takes up un
2910: 64 65 72 20 61 20 68 75 6e 64 72 65 64 20 62 79 der a hundred by
2920: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 20 48 tes of memory. H
2930: 6f 77 65 76 65 72 2c 0d 0a 69 66 20 60 54 63 6c owever,..if `Tcl
2940: 5f 4c 69 73 74 4f 62 6a 47 65 74 45 6c 65 6d 65 _ListObjGetEleme
2950: 6e 74 73 60 20 69 73 20 63 61 6c 6c 65 64 20 6f nts` is called o
2960: 6e 20 74 68 69 73 20 6c 69 73 74 2c 20 69 74 20 n this list, it
2970: 69 73 20 66 6f 72 63 65 64 20 74 6f 20 61 6c 6c is forced to all
2980: 6f 63 61 74 65 20 61 6e 0d 0a 61 72 72 61 79 20 ocate an..array
2990: 6f 66 20 61 20 6d 69 6c 6c 69 6f 6e 20 70 6f 69 of a million poi
29a0: 6e 74 65 72 73 20 65 61 63 68 20 70 6f 69 6e 74 nters each point
29b0: 69 6e 67 20 74 6f 20 61 20 60 54 63 6c 5f 4f 62 ing to a `Tcl_Ob
29c0: 6a 60 20 68 6f 6c 64 69 6e 67 20 61 6e 20 69 6e j` holding an in
29d0: 74 65 67 65 72 20 2d 2d 0d 0a 6d 6f 72 65 20 74 teger --..more t
29e0: 68 61 6e 20 35 30 4d 42 20 6f 66 20 6d 65 6d 6f han 50MB of memo
29f0: 72 79 2e 0d 0a 0d 0a 49 74 20 69 73 20 74 68 65 ry.....It is the
2a00: 72 65 66 6f 72 65 20 72 65 63 6f 6d 6d 65 6e 64 refore recommend
2a10: 65 64 20 74 68 61 74 20 69 6e 20 63 61 73 65 73 ed that in cases
2a20: 20 77 68 65 72 65 20 61 6e 20 65 78 74 65 6e 73 where an extens
2a30: 69 6f 6e 20 6d 61 79 20 62 65 20 64 65 61 6c 69 ion may be deali
2a40: 6e 67 20 77 69 74 68 0d 0a 6c 61 72 67 65 20 6c ng with..large l
2a50: 69 73 74 73 2c 20 69 74 65 72 61 74 69 6f 6e 20 ists, iteration
2a60: 62 65 20 64 6f 6e 65 20 75 73 69 6e 67 20 74 68 be done using th
2a70: 65 20 60 54 63 6c 5f 4c 69 73 74 4f 62 6a 49 6e e `Tcl_ListObjIn
2a80: 64 65 78 60 20 66 75 6e 63 74 69 6f 6e 20 69 6e dex` function in
2a90: 73 74 65 61 64 0d 0a 6f 66 20 60 54 63 6c 5f 4c stead..of `Tcl_L
2aa0: 69 73 74 4f 62 6a 47 65 74 45 6c 65 6d 65 6e 74 istObjGetElement
2ab0: 73 60 2e 20 4e 6f 74 65 20 68 6f 77 65 76 65 72 s`. Note however
2ac0: 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 61 that there is a
2ad0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 72 61 performance tra
2ae0: 64 65 6f 66 66 20 68 65 72 65 0d 0a 61 73 20 69 deoff here..as i
2af0: 74 65 72 61 74 69 6e 67 20 75 73 69 6e 67 20 60 terating using `
2b00: 54 63 6c 5f 4c 69 73 74 4f 62 6a 47 65 74 45 6c Tcl_ListObjGetEl
2b10: 65 6d 65 6e 74 73 60 20 69 73 20 66 61 73 74 65 ements` is faste
2b20: 72 20 61 73 20 74 68 65 20 72 65 74 75 72 6e 65 r as the returne
2b30: 64 20 61 72 72 61 79 20 63 61 6e 0d 0a 62 65 20 d array can..be
2b40: 64 69 72 65 63 74 6c 79 20 61 63 63 65 73 73 65 directly accesse
2b50: 64 20 77 69 74 68 6f 75 74 20 61 20 66 75 6e 63 d without a func
2b60: 74 69 6f 6e 20 63 61 6c 6c 20 66 6f 72 20 65 61 tion call for ea
2b70: 63 68 20 65 6c 65 6d 65 6e 74 2e 0d 0a 0d 0a 23 ch element.....#
2b80: 23 20 54 6f 6d 6d 61 74 68 0d 0a 0d 0a 54 63 6c # Tommath....Tcl
2b90: 20 39 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 61 6c 9 optionally al
2ba0: 6c 6f 77 73 20 74 68 65 20 6c 69 6e 6b 69 6e 67 lows the linking
2bb0: 20 6f 66 20 61 6e 20 65 78 74 65 72 6e 61 6c 20 of an external
2bc0: 60 6c 69 62 74 6f 6d 6d 61 74 68 60 20 6c 69 62 `libtommath` lib
2bd0: 72 61 72 79 20 66 6f 72 20 6d 75 6c 74 69 70 6c rary for multipl
2be0: 65 2d 70 72 65 63 69 73 69 6f 6e 0d 0a 69 6e 74 e-precision..int
2bf0: 65 67 65 72 20 61 72 69 74 68 6d 65 74 69 63 20 eger arithmetic
2c00: 69 6e 20 6c 69 65 75 20 6f 66 20 54 63 6c 27 73 in lieu of Tcl's
2c10: 20 69 6e 74 65 72 6e 61 6c 20 76 65 72 73 69 6f internal versio
2c20: 6e 2e 20 54 68 69 73 20 68 61 73 20 73 6f 6d 65 n. This has some
2c30: 20 63 6f 6e 73 65 71 75 65 6e 63 65 73 20 66 6f consequences fo
2c40: 72 20 65 78 74 65 6e 73 69 6f 6e 73 3a 0d 0a 0d r extensions:...
2c50: 0a 2a 20 49 66 20 69 6e 63 6c 75 64 69 6e 67 20 .* If including
2c60: 60 74 63 6c 54 6f 6d 4d 61 74 68 2e 68 60 2c 20 `tclTomMath.h`,
2c70: 54 63 6c 27 73 20 73 74 75 62 73 20 69 6e 74 65 Tcl's stubs inte
2c80: 72 66 61 63 65 20 74 6f 20 60 6c 69 62 74 6f 6d rface to `libtom
2c90: 6d 61 74 68 60 20 69 73 20 75 73 65 64 20 61 6e math` is used an
2ca0: 64 20 6f 6e 6c 79 20 61 20 73 75 62 73 65 74 20 d only a subset
2cb0: 6f 66 0d 0a 60 6c 69 62 74 6f 6d 6d 61 74 68 60 of..`libtommath`
2cc0: 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 functions are a
2cd0: 76 61 69 6c 61 62 6c 65 2e 20 49 66 20 69 6e 63 vailable. If inc
2ce0: 6c 75 64 69 6e 67 20 60 74 6f 6d 6d 61 74 68 2e luding `tommath.
2cf0: 68 60 20 28 65 78 74 65 72 6e 61 6c 20 6c 69 62 h` (external lib
2d00: 72 61 72 79 29 2c 20 61 6c 6c 20 60 6c 69 62 74 rary), all `libt
2d10: 6f 6d 6d 61 74 68 60 0d 0a 66 75 6e 63 74 69 6f ommath`..functio
2d20: 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 ns are available
2d30: 2e 0d 0a 0d 0a 2a 20 45 78 74 65 6e 73 69 6f 6e .....* Extension
2d40: 73 20 75 73 69 6e 67 20 74 68 65 20 64 65 66 69 s using the defi
2d50: 6e 69 74 69 6f 6e 73 20 6f 66 20 60 6d 70 5f 64 nitions of `mp_d
2d60: 69 67 69 74 60 2c 20 60 6d 70 5f 77 6f 72 64 60 igit`, `mp_word`
2d70: 20 6f 72 20 60 6d 70 5f 69 6e 74 60 20 6e 65 65 or `mp_int` nee
2d80: 64 20 74 6f 20 69 6e 63 6c 75 64 65 20 65 69 74 d to include eit
2d90: 68 65 72 0d 0a 20 60 74 63 6c 54 6f 6d 4d 61 74 her.. `tclTomMat
2da0: 68 2e 68 60 20 6f 72 20 60 74 6f 6d 6d 61 74 68 h.h` or `tommath
2db0: 2e 68 60 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 .h` in addition
2dc0: 60 74 63 6c 2e 68 60 2e 0d 0a 0d 0a 53 65 65 20 `tcl.h`.....See
2dd0: 53 65 65 20 5b 54 49 50 20 35 33 38 5d 28 68 74 See [TIP 538](ht
2de0: 74 70 73 3a 2f 2f 63 6f 72 65 2e 74 63 6c 2d 6c tps://core.tcl-l
2df0: 61 6e 67 2e 6f 72 67 2f 74 69 70 73 2f 64 6f 63 ang.org/tips/doc
2e00: 2f 74 72 75 6e 6b 2f 74 69 70 2f 35 33 38 2e 6d /trunk/tip/538.m
2e10: 64 29 2e 0d 0a 0d 0a 23 23 20 42 75 69 6c 64 69 d).....## Buildi
2e20: 6e 67 0d 0a 0d 0a 23 23 23 20 42 75 69 6c 64 69 ng....### Buildi
2e30: 6e 67 20 77 69 74 68 20 61 75 74 6f 74 6f 6f 6c ng with autotool
2e40: 73 0d 0a 0d 0a 2a 20 55 70 64 61 74 65 20 54 45 s....* Update TE
2e50: 41 20 74 6f 20 74 68 65 20 6c 61 74 65 73 74 20 A to the latest
2e60: 5b 74 63 6c 63 6f 6e 66 69 67 5d 28 68 74 74 70 [tclconfig](http
2e70: 73 3a 2f 2f 63 6f 72 65 2e 74 63 6c 2d 6c 61 6e s://core.tcl-lan
2e80: 67 2e 6f 72 67 2f 74 63 6c 63 6f 6e 66 69 67 29 g.org/tclconfig)
2e90: 2e 0d 0a 0d 0a 2a 20 57 69 74 68 69 6e 20 79 6f .....* Within yo
2ea0: 75 72 20 60 63 6f 6e 66 69 67 75 72 65 2e 61 63 ur `configure.ac
2eb0: 60 20 6f 72 20 60 63 6f 6e 66 69 67 75 72 65 2e ` or `configure.
2ec0: 69 6e 60 20 66 69 6c 65 2c 20 63 68 61 6e 67 65 in` file, change
2ed0: 20 74 68 65 20 60 54 45 41 5f 49 4e 49 54 60 20 the `TEA_INIT`
2ee0: 63 61 6c 6c 20 74 6f 20 72 65 71 75 69 72 65 20 call to require
2ef0: 2a 2a 33 2e 31 33 2a 2a 20 6f 72 20 77 68 61 74 **3.13** or what
2f00: 65 76 65 72 20 74 68 65 20 6c 61 74 65 73 74 20 ever the latest
2f10: 76 65 72 73 69 6f 6e 20 68 61 70 70 65 6e 73 20 version happens
2f20: 74 6f 20 62 65 2e 0d 0a 0d 0a 2a 20 52 75 6e 20 to be.....* Run
2f30: 60 61 75 74 6f 63 6f 6e 66 60 20 74 6f 20 72 65 `autoconf` to re
2f40: 67 65 6e 65 72 61 74 65 20 63 6f 6e 66 69 67 75 generate configu
2f50: 72 65 2e 0d 0a 0d 0a 2a 20 57 68 65 6e 20 72 75 re.....* When ru
2f60: 6e 6e 69 6e 67 20 60 63 6f 6e 66 69 67 75 72 65 nning `configure
2f70: 60 2c 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 `, in addition t
2f80: 6f 20 74 68 65 20 60 2d 2d 77 69 74 68 2d 74 63 o the `--with-tc
2f90: 6c 60 20 6f 70 74 69 6f 6e 20 61 6c 73 6f 20 73 l` option also s
2fa0: 70 65 63 69 66 79 20 74 68 65 20 60 2d 2d 77 69 pecify the `--wi
2fb0: 74 68 2d 74 63 6c 69 6e 63 6c 75 64 65 60 2e 20 th-tclinclude`.
2fc0: 49 74 27 73 20 70 6f 73 73 69 62 6c 65 20 74 68 It's possible th
2fd0: 69 73 20 69 73 20 6f 6e 6c 79 20 72 65 71 75 69 is is only requi
2fe0: 72 65 64 20 6f 6e 20 4d 69 6e 67 57 20 61 6e 64 red on MingW and
2ff0: 20 73 65 65 6d 73 20 6c 69 6b 65 20 61 20 5b 62 seems like a [b
3000: 75 67 5d 28 68 74 74 70 73 3a 2f 2f 63 6f 72 65 ug](https://core
3010: 2e 74 63 6c 2d 6c 61 6e 67 2e 6f 72 67 2f 74 63 .tcl-lang.org/tc
3020: 6c 2f 74 6b 74 76 69 65 77 2f 36 66 32 32 63 37 l/tktview/6f22c7
3030: 61 31 66 63 29 20 69 6e 20 54 45 41 20 62 75 74 a1fc) in TEA but
3040: 20 49 20 61 6d 20 6e 6f 74 20 73 75 66 66 69 63 I am not suffic
3050: 69 65 6e 74 6c 79 20 76 65 72 73 65 64 20 69 6e iently versed in
3060: 20 54 45 41 20 74 6f 20 74 65 6c 6c 20 66 6f 72 TEA to tell for
3070: 20 73 75 72 65 2e 0d 0a 0d 0a 57 69 74 68 6f 75 sure.....Withou
3080: 74 20 74 68 6f 73 65 20 6f 70 74 69 6f 6e 73 2c t those options,
3090: 20 74 68 65 20 6c 6f 61 64 20 63 6f 6d 6d 61 6e the load comman
30a0: 64 20 28 64 69 72 65 63 74 6c 79 20 6f 72 20 76 d (directly or v
30b0: 69 61 20 60 70 61 63 6b 61 67 65 20 72 65 71 75 ia `package requ
30c0: 69 72 65 60 29 20 6d 61 79 20 72 61 69 73 65 20 ire`) may raise
30d0: 74 68 65 20 65 72 72 6f 72 20 0d 0a 0d 0a 2a 69 the error ....*i
30e0: 6e 74 65 72 70 72 65 74 65 72 20 75 73 65 73 20 nterpreter uses
30f0: 61 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 an incompatible
3100: 73 74 75 62 73 20 6d 65 63 68 61 6e 69 73 6d 2a stubs mechanism*
3110: 2e 0d 0a 0d 0a 54 68 69 73 20 2a 6d 61 79 2a 20 .....This *may*
3120: 68 61 70 70 65 6e 20 77 68 65 6e 20 62 75 69 6c happen when buil
3130: 64 69 6e 67 20 61 67 61 69 6e 73 74 20 61 20 70 ding against a p
3140: 72 69 76 61 74 65 20 54 63 6c 20 39 20 69 6e 73 rivate Tcl 9 ins
3150: 74 61 6c 6c 61 74 69 6f 6e 20 77 69 74 68 20 61 tallation with a
3160: 20 73 79 73 74 65 6d 20 69 6e 73 74 61 6c 6c 65 system installe
3170: 64 20 54 63 6c 20 38 20 76 65 72 73 69 6f 6e 2e d Tcl 8 version.
3180: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 For example, if
3190: 20 79 6f 75 20 64 6f 0d 0a 0d 0a 60 60 60 0d 0a you do....```..
31a0: 25 20 70 61 74 68 2f 74 6f 2f 65 78 74 65 6e 73 % path/to/extens
31b0: 69 6f 6e 2f 63 6f 6e 66 69 67 75 72 65 20 2d 2d ion/configure --
31c0: 77 69 74 68 2d 74 63 6c 3d 2f 70 61 74 68 2f 74 with-tcl=/path/t
31d0: 6f 2f 74 63 6c 39 2f 6c 69 62 0d 0a 25 20 6d 61 o/tcl9/lib..% ma
31e0: 6b 65 0d 0a 60 60 60 0d 0a 0d 0a 54 6f 20 72 65 ke..```....To re
31f0: 73 6f 6c 76 65 2c 20 61 6c 73 6f 20 73 70 65 63 solve, also spec
3200: 69 66 79 20 74 68 65 20 60 2d 2d 77 69 74 68 2d ify the `--with-
3210: 74 63 6c 69 6e 63 6c 75 64 65 60 20 6f 70 74 69 tclinclude` opti
3220: 6f 6e 20 74 6f 20 60 63 6f 6e 66 69 67 75 72 65 on to `configure
3230: 60 2e 0d 0a 0d 0a 60 60 60 0d 0a 25 20 70 61 74 `.....```..% pat
3240: 68 2f 74 6f 2f 65 78 74 65 6e 73 69 6f 6e 2f 63 h/to/extension/c
3250: 6f 6e 66 69 67 75 72 65 20 2d 2d 77 69 74 68 2d onfigure --with-
3260: 74 63 6c 3d 2f 70 61 74 68 2f 74 6f 2f 74 63 6c tcl=/path/to/tcl
3270: 39 2f 6c 69 62 20 2d 2d 77 69 74 68 2d 74 63 6c 9/lib --with-tcl
3280: 69 6e 63 6c 75 64 65 3d 2f 70 61 74 68 2f 74 6f include=/path/to
3290: 2f 74 63 6c 39 2f 69 6e 63 6c 75 64 65 0d 0a 25 /tcl9/include..%
32a0: 20 6d 61 6b 65 0d 0a 60 60 60 0d 0a 0d 0a 53 65 make..```....Se
32b0: 65 20 74 68 65 20 5b 74 69 63 6b 65 74 5d 28 68 e the [ticket](h
32c0: 74 74 70 73 3a 2f 2f 63 6f 72 65 2e 74 63 6c 2d ttps://core.tcl-
32d0: 6c 61 6e 67 2e 6f 72 67 2f 74 63 6c 2f 74 6b 74 lang.org/tcl/tkt
32e0: 76 69 65 77 2f 36 66 32 32 63 37 61 31 66 63 29 view/6f22c7a1fc)
32f0: 20 66 6f 72 20 74 68 65 20 73 70 65 63 69 66 69 for the specifi
3300: 63 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 c circumstances
3310: 77 68 65 6e 20 74 68 69 73 20 6d 61 79 20 68 61 when this may ha
3320: 70 70 65 6e 2e 0d 0a 0a 5a 20 66 64 62 32 39 37 ppen....Z fdb297
3330: 30 66 34 32 30 62 37 64 31 62 64 36 61 38 37 36 0f420b7d1bd6a876
3340: 39 61 39 63 66 35 62 63 61 36 0a 9a9cf5bca6.
