0000: 27 5c 22 0a 27 5c 22 20 43 6f 70 79 72 69 67 68 '\".'\" Copyrigh
0010: 74 20 28 63 29 20 31 39 39 34 2d 31 39 39 37 20 t (c) 1994-1997
0020: 53 75 6e 20 4d 69 63 72 6f 73 79 73 74 65 6d 73 Sun Microsystems
0030: 2c 20 49 6e 63 2e 0a 27 5c 22 0a 27 5c 22 20 53 , Inc..'\".'\" S
0040: 65 65 20 74 68 65 20 66 69 6c 65 20 22 6c 69 63 ee the file "lic
0050: 65 6e 73 65 2e 74 65 72 6d 73 22 20 66 6f 72 20 ense.terms" for
0060: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6f 6e 20 75 information on u
0070: 73 61 67 65 20 61 6e 64 20 72 65 64 69 73 74 72 sage and redistr
0080: 69 62 75 74 69 6f 6e 0a 27 5c 22 20 6f 66 20 74 ibution.'\" of t
0090: 68 69 73 20 66 69 6c 65 2c 20 61 6e 64 20 66 6f his file, and fo
00a0: 72 20 61 20 44 49 53 43 4c 41 49 4d 45 52 20 4f r a DISCLAIMER O
00b0: 46 20 41 4c 4c 20 57 41 52 52 41 4e 54 49 45 53 F ALL WARRANTIES
00c0: 2e 0a 27 5c 22 0a 2e 54 48 20 54 63 6c 5f 53 74 ..'\"..TH Tcl_St
00d0: 72 69 6e 67 4f 62 6a 20 33 20 38 2e 31 20 54 63 ringObj 3 8.1 Tc
00e0: 6c 20 22 54 63 6c 20 4c 69 62 72 61 72 79 20 50 l "Tcl Library P
00f0: 72 6f 63 65 64 75 72 65 73 22 0a 2e 73 6f 20 6d rocedures"..so m
0100: 61 6e 2e 6d 61 63 72 6f 73 0a 2e 42 53 0a 2e 53 an.macros..BS..S
0110: 48 20 4e 41 4d 45 0a 54 63 6c 5f 4e 65 77 53 74 H NAME.Tcl_NewSt
0120: 72 69 6e 67 4f 62 6a 2c 20 54 63 6c 5f 4e 65 77 ringObj, Tcl_New
0130: 55 6e 69 63 6f 64 65 4f 62 6a 2c 20 54 63 6c 5f UnicodeObj, Tcl_
0140: 53 65 74 53 74 72 69 6e 67 4f 62 6a 2c 20 54 63 SetStringObj, Tc
0150: 6c 5f 53 65 74 55 6e 69 63 6f 64 65 4f 62 6a 2c l_SetUnicodeObj,
0160: 20 54 63 6c 5f 47 65 74 53 74 72 69 6e 67 46 72 Tcl_GetStringFr
0170: 6f 6d 4f 62 6a 2c 20 54 63 6c 5f 47 65 74 53 74 omObj, Tcl_GetSt
0180: 72 69 6e 67 2c 20 54 63 6c 5f 47 65 74 55 6e 69 ring, Tcl_GetUni
0190: 63 6f 64 65 46 72 6f 6d 4f 62 6a 2c 20 54 63 6c codeFromObj, Tcl
01a0: 5f 47 65 74 55 6e 69 63 6f 64 65 2c 20 54 63 6c _GetUnicode, Tcl
01b0: 5f 47 65 74 55 6e 69 43 68 61 72 2c 20 54 63 6c _GetUniChar, Tcl
01c0: 5f 47 65 74 43 68 61 72 4c 65 6e 67 74 68 2c 20 _GetCharLength,
01d0: 54 63 6c 5f 47 65 74 52 61 6e 67 65 2c 20 54 63 Tcl_GetRange, Tc
01e0: 6c 5f 41 70 70 65 6e 64 54 6f 4f 62 6a 2c 20 54 l_AppendToObj, T
01f0: 63 6c 5f 41 70 70 65 6e 64 55 6e 69 63 6f 64 65 cl_AppendUnicode
0200: 54 6f 4f 62 6a 2c 20 54 63 6c 5f 41 70 70 65 6e ToObj, Tcl_Appen
0210: 64 4f 62 6a 54 6f 4f 62 6a 2c 20 54 63 6c 5f 41 dObjToObj, Tcl_A
0220: 70 70 65 6e 64 53 74 72 69 6e 67 73 54 6f 4f 62 ppendStringsToOb
0230: 6a 2c 20 54 63 6c 5f 41 70 70 65 6e 64 4c 69 6d j, Tcl_AppendLim
0240: 69 74 65 64 54 6f 4f 62 6a 2c 20 54 63 6c 5f 46 itedToObj, Tcl_F
0250: 6f 72 6d 61 74 2c 20 54 63 6c 5f 41 70 70 65 6e ormat, Tcl_Appen
0260: 64 46 6f 72 6d 61 74 54 6f 4f 62 6a 2c 20 54 63 dFormatToObj, Tc
0270: 6c 5f 4f 62 6a 50 72 69 6e 74 66 2c 20 54 63 6c l_ObjPrintf, Tcl
0280: 5f 41 70 70 65 6e 64 50 72 69 6e 74 66 54 6f 4f _AppendPrintfToO
0290: 62 6a 2c 20 54 63 6c 5f 53 65 74 4f 62 6a 4c 65 bj, Tcl_SetObjLe
02a0: 6e 67 74 68 2c 20 54 63 6c 5f 41 74 74 65 6d 70 ngth, Tcl_Attemp
02b0: 74 53 65 74 4f 62 6a 4c 65 6e 67 74 68 2c 20 54 tSetObjLength, T
02c0: 63 6c 5f 43 6f 6e 63 61 74 4f 62 6a 20 5c 2d 20 cl_ConcatObj \-
02d0: 6d 61 6e 69 70 75 6c 61 74 65 20 54 63 6c 20 76 manipulate Tcl v
02e0: 61 6c 75 65 73 20 61 73 20 73 74 72 69 6e 67 73 alues as strings
02f0: 0a 2e 53 48 20 53 59 4e 4f 50 53 49 53 0a 2e 6e ..SH SYNOPSIS..n
0300: 66 0a 5c 66 42 23 69 6e 63 6c 75 64 65 20 3c 74 f.\fB#include <t
0310: 63 6c 2e 68 3e 5c 66 52 0a 2e 73 70 0a 54 63 6c cl.h>\fR..sp.Tcl
0320: 5f 4f 62 6a 20 2a 0a 5c 66 42 54 63 6c 5f 4e 65 _Obj *.\fBTcl_Ne
0330: 77 53 74 72 69 6e 67 4f 62 6a 5c 66 52 28 5c 66 wStringObj\fR(\f
0340: 49 62 79 74 65 73 2c 20 6c 65 6e 67 74 68 5c 66 Ibytes, length\f
0350: 52 29 0a 2e 73 70 0a 54 63 6c 5f 4f 62 6a 20 2a R)..sp.Tcl_Obj *
0360: 0a 5c 66 42 54 63 6c 5f 4e 65 77 55 6e 69 63 6f .\fBTcl_NewUnico
0370: 64 65 4f 62 6a 5c 66 52 28 5c 66 49 75 6e 69 63 deObj\fR(\fIunic
0380: 6f 64 65 2c 20 6e 75 6d 43 68 61 72 73 5c 66 52 ode, numChars\fR
0390: 29 0a 2e 73 70 0a 76 6f 69 64 0a 5c 66 42 54 63 )..sp.void.\fBTc
03a0: 6c 5f 53 65 74 53 74 72 69 6e 67 4f 62 6a 5c 66 l_SetStringObj\f
03b0: 52 28 5c 66 49 6f 62 6a 50 74 72 2c 20 62 79 74 R(\fIobjPtr, byt
03c0: 65 73 2c 20 6c 65 6e 67 74 68 5c 66 52 29 0a 2e es, length\fR)..
03d0: 73 70 0a 76 6f 69 64 0a 5c 66 42 54 63 6c 5f 53 sp.void.\fBTcl_S
03e0: 65 74 55 6e 69 63 6f 64 65 4f 62 6a 5c 66 52 28 etUnicodeObj\fR(
03f0: 5c 66 49 6f 62 6a 50 74 72 2c 20 75 6e 69 63 6f \fIobjPtr, unico
0400: 64 65 2c 20 6e 75 6d 43 68 61 72 73 5c 66 52 29 de, numChars\fR)
0410: 0a 2e 73 70 0a 63 68 61 72 20 2a 0a 5c 66 42 54 ..sp.char *.\fBT
0420: 63 6c 5f 47 65 74 53 74 72 69 6e 67 46 72 6f 6d cl_GetStringFrom
0430: 4f 62 6a 5c 66 52 28 5c 66 49 6f 62 6a 50 74 72 Obj\fR(\fIobjPtr
0440: 2c 20 6c 65 6e 67 74 68 50 74 72 5c 66 52 29 0a , lengthPtr\fR).
0450: 2e 73 70 0a 63 68 61 72 20 2a 0a 5c 66 42 54 63 .sp.char *.\fBTc
0460: 6c 5f 47 65 74 53 74 72 69 6e 67 5c 66 52 28 5c l_GetString\fR(\
0470: 66 49 6f 62 6a 50 74 72 5c 66 52 29 0a 2e 73 70 fIobjPtr\fR)..sp
0480: 0a 54 63 6c 5f 55 6e 69 43 68 61 72 20 2a 0a 5c .Tcl_UniChar *.\
0490: 66 42 54 63 6c 5f 47 65 74 55 6e 69 63 6f 64 65 fBTcl_GetUnicode
04a0: 46 72 6f 6d 4f 62 6a 5c 66 52 28 5c 66 49 6f 62 FromObj\fR(\fIob
04b0: 6a 50 74 72 2c 20 6c 65 6e 67 74 68 50 74 72 5c jPtr, lengthPtr\
04c0: 66 52 29 0a 2e 73 70 0a 54 63 6c 5f 55 6e 69 43 fR)..sp.Tcl_UniC
04d0: 68 61 72 20 2a 0a 5c 66 42 54 63 6c 5f 47 65 74 har *.\fBTcl_Get
04e0: 55 6e 69 63 6f 64 65 5c 66 52 28 5c 66 49 6f 62 Unicode\fR(\fIob
04f0: 6a 50 74 72 5c 66 52 29 0a 2e 73 70 0a 69 6e 74 jPtr\fR)..sp.int
0500: 0a 5c 66 42 54 63 6c 5f 47 65 74 55 6e 69 43 68 .\fBTcl_GetUniCh
0510: 61 72 5c 66 52 28 5c 66 49 6f 62 6a 50 74 72 2c ar\fR(\fIobjPtr,
0520: 20 69 6e 64 65 78 5c 66 52 29 0a 2e 73 70 0a 73 index\fR)..sp.s
0530: 69 7a 65 5f 74 0a 5c 66 42 54 63 6c 5f 47 65 74 ize_t.\fBTcl_Get
0540: 43 68 61 72 4c 65 6e 67 74 68 5c 66 52 28 5c 66 CharLength\fR(\f
0550: 49 6f 62 6a 50 74 72 5c 66 52 29 0a 2e 73 70 0a IobjPtr\fR)..sp.
0560: 54 63 6c 5f 4f 62 6a 20 2a 0a 5c 66 42 54 63 6c Tcl_Obj *.\fBTcl
0570: 5f 47 65 74 52 61 6e 67 65 5c 66 52 28 5c 66 49 _GetRange\fR(\fI
0580: 6f 62 6a 50 74 72 2c 20 66 69 72 73 74 2c 20 6c objPtr, first, l
0590: 61 73 74 5c 66 52 29 0a 2e 73 70 0a 76 6f 69 64 ast\fR)..sp.void
05a0: 0a 5c 66 42 54 63 6c 5f 41 70 70 65 6e 64 54 6f .\fBTcl_AppendTo
05b0: 4f 62 6a 5c 66 52 28 5c 66 49 6f 62 6a 50 74 72 Obj\fR(\fIobjPtr
05c0: 2c 20 62 79 74 65 73 2c 20 6c 65 6e 67 74 68 5c , bytes, length\
05d0: 66 52 29 0a 2e 73 70 0a 76 6f 69 64 0a 5c 66 42 fR)..sp.void.\fB
05e0: 54 63 6c 5f 41 70 70 65 6e 64 55 6e 69 63 6f 64 Tcl_AppendUnicod
05f0: 65 54 6f 4f 62 6a 5c 66 52 28 5c 66 49 6f 62 6a eToObj\fR(\fIobj
0600: 50 74 72 2c 20 75 6e 69 63 6f 64 65 2c 20 6e 75 Ptr, unicode, nu
0610: 6d 43 68 61 72 73 5c 66 52 29 0a 2e 73 70 0a 76 mChars\fR)..sp.v
0620: 6f 69 64 0a 5c 66 42 54 63 6c 5f 41 70 70 65 6e oid.\fBTcl_Appen
0630: 64 4f 62 6a 54 6f 4f 62 6a 5c 66 52 28 5c 66 49 dObjToObj\fR(\fI
0640: 6f 62 6a 50 74 72 2c 20 61 70 70 65 6e 64 4f 62 objPtr, appendOb
0650: 6a 50 74 72 5c 66 52 29 0a 2e 73 70 0a 76 6f 69 jPtr\fR)..sp.voi
0660: 64 0a 5c 66 42 54 63 6c 5f 41 70 70 65 6e 64 53 d.\fBTcl_AppendS
0670: 74 72 69 6e 67 73 54 6f 4f 62 6a 5c 66 52 28 5c tringsToObj\fR(\
0680: 66 49 6f 62 6a 50 74 72 2c 20 73 74 72 69 6e 67 fIobjPtr, string
0690: 2c 20 73 74 72 69 6e 67 2c 20 2e 2e 2e 20 5c 66 , string, ... \f
06a0: 42 28 63 68 61 72 20 2a 29 20 4e 55 4c 4c 5c 66 B(char *) NULL\f
06b0: 52 29 0a 2e 73 70 0a 76 6f 69 64 0a 5c 66 42 54 R)..sp.void.\fBT
06c0: 63 6c 5f 41 70 70 65 6e 64 4c 69 6d 69 74 65 64 cl_AppendLimited
06d0: 54 6f 4f 62 6a 5c 66 52 28 5c 66 49 6f 62 6a 50 ToObj\fR(\fIobjP
06e0: 74 72 2c 20 62 79 74 65 73 2c 20 6c 65 6e 67 74 tr, bytes, lengt
06f0: 68 2c 20 6c 69 6d 69 74 2c 20 65 6c 6c 69 70 73 h, limit, ellips
0700: 69 73 5c 66 52 29 0a 2e 73 70 0a 54 63 6c 5f 4f is\fR)..sp.Tcl_O
0710: 62 6a 20 2a 0a 5c 66 42 54 63 6c 5f 46 6f 72 6d bj *.\fBTcl_Form
0720: 61 74 5c 66 52 28 5c 66 49 69 6e 74 65 72 70 2c at\fR(\fIinterp,
0730: 20 66 6f 72 6d 61 74 2c 20 6f 62 6a 63 2c 20 6f format, objc, o
0740: 62 6a 76 5c 66 52 29 0a 2e 73 70 0a 69 6e 74 0a bjv\fR)..sp.int.
0750: 5c 66 42 54 63 6c 5f 41 70 70 65 6e 64 46 6f 72 \fBTcl_AppendFor
0760: 6d 61 74 54 6f 4f 62 6a 5c 66 52 28 5c 66 49 69 matToObj\fR(\fIi
0770: 6e 74 65 72 70 2c 20 6f 62 6a 50 74 72 2c 20 66 nterp, objPtr, f
0780: 6f 72 6d 61 74 2c 20 6f 62 6a 63 2c 20 6f 62 6a ormat, objc, obj
0790: 76 5c 66 52 29 0a 2e 73 70 0a 54 63 6c 5f 4f 62 v\fR)..sp.Tcl_Ob
07a0: 6a 20 2a 0a 5c 66 42 54 63 6c 5f 4f 62 6a 50 72 j *.\fBTcl_ObjPr
07b0: 69 6e 74 66 5c 66 52 28 5c 66 49 66 6f 72 6d 61 intf\fR(\fIforma
07c0: 74 2c 20 2e 2e 2e 5c 66 52 29 0a 2e 73 70 0a 76 t, ...\fR)..sp.v
07d0: 6f 69 64 0a 5c 66 42 54 63 6c 5f 41 70 70 65 6e oid.\fBTcl_Appen
07e0: 64 50 72 69 6e 74 66 54 6f 4f 62 6a 5c 66 52 28 dPrintfToObj\fR(
07f0: 5c 66 49 6f 62 6a 50 74 72 2c 20 66 6f 72 6d 61 \fIobjPtr, forma
0800: 74 2c 20 2e 2e 2e 5c 66 52 29 0a 2e 73 70 0a 76 t, ...\fR)..sp.v
0810: 6f 69 64 0a 5c 66 42 54 63 6c 5f 53 65 74 4f 62 oid.\fBTcl_SetOb
0820: 6a 4c 65 6e 67 74 68 5c 66 52 28 5c 66 49 6f 62 jLength\fR(\fIob
0830: 6a 50 74 72 2c 20 6e 65 77 4c 65 6e 67 74 68 5c jPtr, newLength\
0840: 66 52 29 0a 2e 73 70 0a 69 6e 74 0a 5c 66 42 54 fR)..sp.int.\fBT
0850: 63 6c 5f 41 74 74 65 6d 70 74 53 65 74 4f 62 6a cl_AttemptSetObj
0860: 4c 65 6e 67 74 68 5c 66 52 28 5c 66 49 6f 62 6a Length\fR(\fIobj
0870: 50 74 72 2c 20 6e 65 77 4c 65 6e 67 74 68 5c 66 Ptr, newLength\f
0880: 52 29 0a 2e 73 70 0a 54 63 6c 5f 4f 62 6a 20 2a R)..sp.Tcl_Obj *
0890: 0a 5c 66 42 54 63 6c 5f 43 6f 6e 63 61 74 4f 62 .\fBTcl_ConcatOb
08a0: 6a 5c 66 52 28 5c 66 49 6f 62 6a 63 2c 20 6f 62 j\fR(\fIobjc, ob
08b0: 6a 76 5c 66 52 29 0a 2e 53 48 20 41 52 47 55 4d jv\fR)..SH ARGUM
08c0: 45 4e 54 53 0a 2e 41 53 20 22 63 6f 6e 73 74 20 ENTS..AS "const
08d0: 54 63 6c 5f 55 6e 69 43 68 61 72 22 20 2a 61 70 Tcl_UniChar" *ap
08e0: 70 65 6e 64 4f 62 6a 50 74 72 20 69 6e 2f 6f 75 pendObjPtr in/ou
08f0: 74 0a 2e 41 50 20 22 63 6f 6e 73 74 20 63 68 61 t..AP "const cha
0900: 72 22 20 2a 62 79 74 65 73 20 69 6e 0a 50 6f 69 r" *bytes in.Poi
0910: 6e 74 73 20 74 6f 20 74 68 65 20 66 69 72 73 74 nts to the first
0920: 20 62 79 74 65 20 6f 66 20 61 6e 20 61 72 72 61 byte of an arra
0930: 79 20 6f 66 20 55 54 46 2d 38 2d 65 6e 63 6f 64 y of UTF-8-encod
0940: 65 64 20 62 79 74 65 73 0a 75 73 65 64 20 74 6f ed bytes.used to
0950: 20 73 65 74 20 6f 72 20 61 70 70 65 6e 64 20 74 set or append t
0960: 6f 20 61 20 73 74 72 69 6e 67 20 76 61 6c 75 65 o a string value
0970: 2e 0a 54 68 69 73 20 62 79 74 65 20 61 72 72 61 ..This byte arra
0980: 79 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 65 6d y may contain em
0990: 62 65 64 64 65 64 20 6e 75 6c 6c 20 63 68 61 72 bedded null char
09a0: 61 63 74 65 72 73 0a 75 6e 6c 65 73 73 20 5c 66 acters.unless \f
09b0: 49 6e 75 6d 43 68 61 72 73 5c 66 52 20 69 73 20 InumChars\fR is
09c0: 5c 66 42 54 43 4c 5f 49 4e 44 45 58 5f 4e 4f 4e \fBTCL_INDEX_NON
09d0: 45 5c 66 52 2e 20 20 28 41 70 70 6c 69 63 61 74 E\fR. (Applicat
09e0: 69 6f 6e 73 20 6e 65 65 64 69 6e 67 20 6e 75 6c ions needing nul
09f0: 6c 20 62 79 74 65 73 0a 73 68 6f 75 6c 64 20 72 l bytes.should r
0a00: 65 70 72 65 73 65 6e 74 20 74 68 65 6d 20 61 73 epresent them as
0a10: 20 74 68 65 20 74 77 6f 2d 62 79 74 65 20 73 65 the two-byte se
0a20: 71 75 65 6e 63 65 20 5c 66 49 5c 65 33 30 30 5c quence \fI\e300\
0a30: 65 32 30 30 5c 66 52 2c 20 75 73 65 0a 5c 66 42 e200\fR, use.\fB
0a40: 54 63 6c 5f 45 78 74 65 72 6e 61 6c 54 6f 55 74 Tcl_ExternalToUt
0a50: 66 5c 66 52 20 74 6f 20 63 6f 6e 76 65 72 74 2c f\fR to convert,
0a60: 20 6f 72 20 5c 66 42 54 63 6c 5f 4e 65 77 42 79 or \fBTcl_NewBy
0a70: 74 65 41 72 72 61 79 4f 62 6a 5c 66 52 20 69 66 teArrayObj\fR if
0a80: 0a 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 61 .the string is a
0a90: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 75 collection of u
0aa0: 6e 69 6e 74 65 72 70 72 65 74 65 64 20 62 79 74 ninterpreted byt
0ab0: 65 73 2e 29 0a 2e 41 50 20 73 69 7a 65 5f 74 20 es.)..AP size_t
0ac0: 6c 65 6e 67 74 68 20 69 6e 0a 54 68 65 20 6e 75 length in.The nu
0ad0: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 6f mber of bytes to
0ae0: 20 63 6f 70 79 20 66 72 6f 6d 20 5c 66 49 62 79 copy from \fIby
0af0: 74 65 73 5c 66 52 20 77 68 65 6e 0a 69 6e 69 74 tes\fR when.init
0b00: 69 61 6c 69 7a 69 6e 67 2c 20 73 65 74 74 69 6e ializing, settin
0b10: 67 2c 20 6f 72 20 61 70 70 65 6e 64 69 6e 67 20 g, or appending
0b20: 74 6f 20 61 20 73 74 72 69 6e 67 20 76 61 6c 75 to a string valu
0b30: 65 2e 0a 49 66 20 5c 66 42 54 43 4c 5f 49 4e 44 e..If \fBTCL_IND
0b40: 45 58 5f 4e 4f 4e 45 5c 66 52 2c 20 61 6c 6c 20 EX_NONE\fR, all
0b50: 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 bytes up to the
0b60: 66 69 72 73 74 20 6e 75 6c 6c 20 61 72 65 20 75 first null are u
0b70: 73 65 64 2e 0a 2e 41 50 20 22 63 6f 6e 73 74 20 sed...AP "const
0b80: 54 63 6c 5f 55 6e 69 43 68 61 72 22 20 2a 75 6e Tcl_UniChar" *un
0b90: 69 63 6f 64 65 20 69 6e 0a 50 6f 69 6e 74 73 20 icode in.Points
0ba0: 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 to the first byt
0bb0: 65 20 6f 66 20 61 6e 20 61 72 72 61 79 20 6f 66 e of an array of
0bc0: 20 55 6e 69 63 6f 64 65 20 63 68 61 72 61 63 74 Unicode charact
0bd0: 65 72 73 0a 75 73 65 64 20 74 6f 20 73 65 74 20 ers.used to set
0be0: 6f 72 20 61 70 70 65 6e 64 20 74 6f 20 61 20 73 or append to a s
0bf0: 74 72 69 6e 67 20 76 61 6c 75 65 2e 0a 54 68 69 tring value..Thi
0c00: 73 20 62 79 74 65 20 61 72 72 61 79 20 6d 61 79 s byte array may
0c10: 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
0c20: 64 20 6e 75 6c 6c 20 63 68 61 72 61 63 74 65 72 d null character
0c30: 73 0a 75 6e 6c 65 73 73 20 5c 66 49 6e 75 6d 43 s.unless \fInumC
0c40: 68 61 72 73 5c 66 52 20 69 73 20 5c 66 42 54 43 hars\fR is \fBTC
0c50: 4c 5f 49 4e 44 45 58 5f 4e 4f 4e 45 5c 66 52 2e L_INDEX_NONE\fR.
0c60: 0a 2e 41 50 20 73 69 7a 65 5f 74 20 6e 75 6d 43 ..AP size_t numC
0c70: 68 61 72 73 20 69 6e 0a 54 68 65 20 6e 75 6d 62 hars in.The numb
0c80: 65 72 20 6f 66 20 55 6e 69 63 6f 64 65 20 63 68 er of Unicode ch
0c90: 61 72 61 63 74 65 72 73 20 74 6f 20 63 6f 70 79 aracters to copy
0ca0: 20 66 72 6f 6d 20 5c 66 49 75 6e 69 63 6f 64 65 from \fIunicode
0cb0: 5c 66 52 20 77 68 65 6e 0a 69 6e 69 74 69 61 6c \fR when.initial
0cc0: 69 7a 69 6e 67 2c 20 73 65 74 74 69 6e 67 2c 20 izing, setting,
0cd0: 6f 72 20 61 70 70 65 6e 64 69 6e 67 20 74 6f 20 or appending to
0ce0: 61 20 73 74 72 69 6e 67 20 76 61 6c 75 65 2e 0a a string value..
0cf0: 49 66 20 5c 66 42 54 43 4c 5f 49 4e 44 45 58 5f If \fBTCL_INDEX_
0d00: 4e 4f 4e 45 5c 66 52 2c 20 61 6c 6c 20 63 68 61 NONE\fR, all cha
0d10: 72 61 63 74 65 72 73 20 75 70 20 74 6f 20 74 68 racters up to th
0d20: 65 20 66 69 72 73 74 20 6e 75 6c 6c 20 63 68 61 e first null cha
0d30: 72 61 63 74 65 72 20 61 72 65 20 75 73 65 64 2e racter are used.
0d40: 0a 2e 41 50 20 73 69 7a 65 5f 74 20 69 6e 64 65 ..AP size_t inde
0d50: 78 20 69 6e 0a 54 68 65 20 69 6e 64 65 78 20 6f x in.The index o
0d60: 66 20 74 68 65 20 55 6e 69 63 6f 64 65 20 63 68 f the Unicode ch
0d70: 61 72 61 63 74 65 72 20 74 6f 20 72 65 74 75 72 aracter to retur
0d80: 6e 2e 0a 2e 41 50 20 73 69 7a 65 5f 74 20 66 69 n...AP size_t fi
0d90: 72 73 74 20 69 6e 0a 54 68 65 20 69 6e 64 65 78 rst in.The index
0da0: 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 55 6e of the first Un
0db0: 69 63 6f 64 65 20 63 68 61 72 61 63 74 65 72 20 icode character
0dc0: 69 6e 20 74 68 65 20 55 6e 69 63 6f 64 65 20 72 in the Unicode r
0dd0: 61 6e 67 65 20 74 6f 20 62 65 0a 72 65 74 75 72 ange to be.retur
0de0: 6e 65 64 20 61 73 20 61 20 6e 65 77 20 76 61 6c ned as a new val
0df0: 75 65 2e 20 49 66 20 5c 66 42 54 43 4c 5f 49 4e ue. If \fBTCL_IN
0e00: 44 45 58 5f 4e 4f 4e 45 5c 66 52 2c 20 62 65 68 DEX_NONE\fR, beh
0e10: 61 76 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 ave the same as
0e20: 69 66 20 74 68 65 0a 76 61 6c 75 65 20 77 61 73 if the.value was
0e30: 20 30 2e 0a 2e 41 50 20 73 69 7a 65 5f 74 20 6c 0...AP size_t l
0e40: 61 73 74 20 69 6e 0a 54 68 65 20 69 6e 64 65 78 ast in.The index
0e50: 20 6f 66 20 74 68 65 20 6c 61 73 74 20 55 6e 69 of the last Uni
0e60: 63 6f 64 65 20 63 68 61 72 61 63 74 65 72 20 69 code character i
0e70: 6e 20 74 68 65 20 55 6e 69 63 6f 64 65 20 72 61 n the Unicode ra
0e80: 6e 67 65 20 74 6f 20 62 65 0a 72 65 74 75 72 6e nge to be.return
0e90: 65 64 20 61 73 20 61 20 6e 65 77 20 76 61 6c 75 ed as a new valu
0ea0: 65 2e 20 49 66 20 5c 66 42 54 43 4c 5f 49 4e 44 e. If \fBTCL_IND
0eb0: 45 58 5f 4e 4f 4e 45 5c 66 52 2c 20 74 61 6b 65 EX_NONE\fR, take
0ec0: 20 61 6c 6c 20 63 68 61 72 61 63 74 65 72 73 20 all characters
0ed0: 75 70 20 74 6f 0a 74 68 65 20 6c 61 73 74 20 6f up to.the last o
0ee0: 6e 65 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2e 41 ne available...A
0ef0: 50 20 54 63 6c 5f 4f 62 6a 20 2a 6f 62 6a 50 74 P Tcl_Obj *objPt
0f00: 72 20 69 6e 2f 6f 75 74 0a 50 6f 69 6e 74 73 20 r in/out.Points
0f10: 74 6f 20 61 20 76 61 6c 75 65 20 74 6f 20 6d 61 to a value to ma
0f20: 6e 69 70 75 6c 61 74 65 2e 0a 2e 41 50 20 54 63 nipulate...AP Tc
0f30: 6c 5f 4f 62 6a 20 2a 61 70 70 65 6e 64 4f 62 6a l_Obj *appendObj
0f40: 50 74 72 20 69 6e 0a 54 68 65 20 76 61 6c 75 65 Ptr in.The value
0f50: 20 74 6f 20 61 70 70 65 6e 64 20 74 6f 20 5c 66 to append to \f
0f60: 49 6f 62 6a 50 74 72 5c 66 52 20 69 6e 20 5c 66 IobjPtr\fR in \f
0f70: 42 54 63 6c 5f 41 70 70 65 6e 64 4f 62 6a 54 6f BTcl_AppendObjTo
0f80: 4f 62 6a 5c 66 52 2e 0a 2e 41 50 20 22 73 69 7a Obj\fR...AP "siz
0f90: 65 5f 74 20 5c 26 7c 20 69 6e 74 22 20 2a 6c 65 e_t \&| int" *le
0fa0: 6e 67 74 68 50 74 72 20 6f 75 74 0a 54 68 65 20 ngthPtr out.The
0fb0: 6c 6f 63 61 74 69 6f 6e 20 77 68 65 72 65 20 5c location where \
0fc0: 66 42 54 63 6c 5f 47 65 74 53 74 72 69 6e 67 46 fBTcl_GetStringF
0fd0: 72 6f 6d 4f 62 6a 5c 66 52 20 77 69 6c 6c 20 73 romObj\fR will s
0fe0: 74 6f 72 65 20 74 68 65 20 6c 65 6e 67 74 68 0a tore the length.
0ff0: 6f 66 20 61 20 76 61 6c 75 65 27 73 20 73 74 72 of a value's str
1000: 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
1010: 6f 6e 2e 20 4d 61 79 20 62 65 20 28 69 6e 74 20 on. May be (int
1020: 2a 29 4e 55 4c 4c 20 77 68 65 6e 20 6e 6f 74 20 *)NULL when not
1030: 75 73 65 64 2e 0a 2e 41 50 20 22 63 6f 6e 73 74 used...AP "const
1040: 20 63 68 61 72 22 20 2a 73 74 72 69 6e 67 20 69 char" *string i
1050: 6e 0a 4e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 n.Null-terminate
1060: 64 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 74 d string value t
1070: 6f 20 61 70 70 65 6e 64 20 74 6f 20 5c 66 49 6f o append to \fIo
1080: 62 6a 50 74 72 5c 66 52 2e 0a 2e 41 50 20 76 61 bjPtr\fR...AP va
1090: 5f 6c 69 73 74 20 61 72 67 4c 69 73 74 20 69 6e _list argList in
10a0: 0a 41 6e 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 .An argument lis
10b0: 74 20 77 68 69 63 68 20 6d 75 73 74 20 68 61 76 t which must hav
10c0: 65 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a e been initializ
10d0: 65 64 20 75 73 69 6e 67 0a 5c 66 42 76 61 5f 73 ed using.\fBva_s
10e0: 74 61 72 74 5c 66 52 2c 20 61 6e 64 20 63 6c 65 tart\fR, and cle
10f0: 61 72 65 64 20 75 73 69 6e 67 20 5c 66 42 76 61 ared using \fBva
1100: 5f 65 6e 64 5c 66 52 2e 0a 2e 41 50 20 73 69 7a _end\fR...AP siz
1110: 65 5f 74 20 6c 69 6d 69 74 20 69 6e 0a 4d 61 78 e_t limit in.Max
1120: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 imum number of b
1130: 79 74 65 73 20 74 6f 20 62 65 20 61 70 70 65 6e ytes to be appen
1140: 64 65 64 2e 0a 2e 41 50 20 22 63 6f 6e 73 74 20 ded...AP "const
1150: 63 68 61 72 22 20 2a 65 6c 6c 69 70 73 69 73 20 char" *ellipsis
1160: 69 6e 0a 53 75 66 66 69 78 20 74 6f 20 61 70 70 in.Suffix to app
1170: 65 6e 64 20 77 68 65 6e 20 74 68 65 20 6c 69 6d end when the lim
1180: 69 74 20 6c 65 61 64 73 20 74 6f 20 73 74 72 69 it leads to stri
1190: 6e 67 20 74 72 75 6e 63 61 74 69 6f 6e 2e 0a 49 ng truncation..I
11a0: 66 20 4e 55 4c 4c 20 69 73 20 70 61 73 73 65 64 f NULL is passed
11b0: 20 74 68 65 6e 20 74 68 65 20 73 75 66 66 69 78 then the suffix
11c0: 0a 2e 51 57 20 22 2e 2e 2e 22 0a 69 73 20 75 73 ..QW "...".is us
11d0: 65 64 2e 0a 2e 41 50 20 22 63 6f 6e 73 74 20 63 ed...AP "const c
11e0: 68 61 72 22 20 2a 66 6f 72 6d 61 74 20 69 6e 0a har" *format in.
11f0: 46 6f 72 6d 61 74 20 63 6f 6e 74 72 6f 6c 20 73 Format control s
1200: 74 72 69 6e 67 20 69 6e 63 6c 75 64 69 6e 67 20 tring including
1210: 25 20 63 6f 6e 76 65 72 73 69 6f 6e 20 73 70 65 % conversion spe
1220: 63 69 66 69 65 72 73 2e 0a 2e 41 50 20 73 69 7a cifiers...AP siz
1230: 65 5f 74 20 6f 62 6a 63 20 69 6e 0a 54 68 65 20 e_t objc in.The
1240: 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e number of elemen
1250: 74 73 20 74 6f 20 66 6f 72 6d 61 74 20 6f 72 20 ts to format or
1260: 63 6f 6e 63 61 74 65 6e 61 74 65 2e 0a 2e 41 50 concatenate...AP
1270: 20 54 63 6c 5f 4f 62 6a 20 2a 6f 62 6a 76 5b 5d Tcl_Obj *objv[]
1280: 20 69 6e 0a 54 68 65 20 61 72 72 61 79 20 6f 66 in.The array of
1290: 20 76 61 6c 75 65 73 20 74 6f 20 66 6f 72 6d 61 values to forma
12a0: 74 20 6f 72 20 63 6f 6e 63 61 74 65 6e 61 74 65 t or concatenate
12b0: 2e 0a 2e 41 50 20 73 69 7a 65 5f 74 20 6e 65 77 ...AP size_t new
12c0: 4c 65 6e 67 74 68 20 69 6e 0a 4e 65 77 20 6c 65 Length in.New le
12d0: 6e 67 74 68 20 66 6f 72 20 74 68 65 20 73 74 72 ngth for the str
12e0: 69 6e 67 20 76 61 6c 75 65 20 6f 66 20 5c 66 49 ing value of \fI
12f0: 6f 62 6a 50 74 72 5c 66 52 2c 20 6e 6f 74 20 69 objPtr\fR, not i
1300: 6e 63 6c 75 64 69 6e 67 20 74 68 65 0a 66 69 6e ncluding the.fin
1310: 61 6c 20 6e 75 6c 6c 20 63 68 61 72 61 63 74 65 al null characte
1320: 72 2e 0a 2e 42 45 0a 2e 53 48 20 44 45 53 43 52 r...BE..SH DESCR
1330: 49 50 54 49 4f 4e 0a 2e 50 50 0a 54 68 65 20 70 IPTION..PP.The p
1340: 72 6f 63 65 64 75 72 65 73 20 64 65 73 63 72 69 rocedures descri
1350: 62 65 64 20 69 6e 20 74 68 69 73 20 6d 61 6e 75 bed in this manu
1360: 61 6c 20 65 6e 74 72 79 20 61 6c 6c 6f 77 20 54 al entry allow T
1370: 63 6c 20 76 61 6c 75 65 73 20 74 6f 0a 62 65 20 cl values to.be
1380: 6d 61 6e 69 70 75 6c 61 74 65 64 20 61 73 20 73 manipulated as s
1390: 74 72 69 6e 67 20 76 61 6c 75 65 73 2e 20 20 54 tring values. T
13a0: 68 65 79 20 75 73 65 20 74 68 65 20 69 6e 74 65 hey use the inte
13b0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
13c0: 69 6f 6e 0a 6f 66 20 74 68 65 20 76 61 6c 75 65 ion.of the value
13d0: 20 74 6f 20 73 74 6f 72 65 20 61 64 64 69 74 69 to store additi
13e0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
13f0: 20 74 6f 20 6d 61 6b 65 20 74 68 65 20 73 74 72 to make the str
1400: 69 6e 67 0a 6d 61 6e 69 70 75 6c 61 74 69 6f 6e ing.manipulation
1410: 73 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 s more efficient
1420: 2e 20 20 49 6e 20 70 61 72 74 69 63 75 6c 61 72 . In particular
1430: 2c 20 74 68 65 79 20 6d 61 6b 65 20 61 20 73 65 , they make a se
1440: 72 69 65 73 20 6f 66 0a 61 70 70 65 6e 64 20 6f ries of.append o
1450: 70 65 72 61 74 69 6f 6e 73 20 65 66 66 69 63 69 perations effici
1460: 65 6e 74 20 62 79 20 61 6c 6c 6f 63 61 74 69 6e ent by allocatin
1470: 67 20 65 78 74 72 61 20 73 74 6f 72 61 67 65 20 g extra storage
1480: 73 70 61 63 65 20 66 6f 72 20 74 68 65 0a 73 74 space for the.st
1490: 72 69 6e 67 20 73 6f 20 74 68 61 74 20 69 74 20 ring so that it
14a0: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f does not have to
14b0: 20 62 65 20 63 6f 70 69 65 64 20 66 6f 72 20 65 be copied for e
14c0: 61 63 68 20 61 70 70 65 6e 64 2e 0a 41 6c 73 6f ach append..Also
14d0: 2c 20 69 6e 64 65 78 69 6e 67 20 61 6e 64 20 6c , indexing and l
14e0: 65 6e 67 74 68 20 63 6f 6d 70 75 74 61 74 69 6f ength computatio
14f0: 6e 73 20 61 72 65 20 6f 70 74 69 6d 69 7a 65 64 ns are optimized
1500: 20 62 65 63 61 75 73 65 20 74 68 65 0a 55 6e 69 because the.Uni
1510: 63 6f 64 65 20 73 74 72 69 6e 67 20 72 65 70 72 code string repr
1520: 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 63 61 esentation is ca
1530: 6c 63 75 6c 61 74 65 64 20 61 6e 64 20 63 61 63 lculated and cac
1540: 68 65 64 20 61 73 20 6e 65 65 64 65 64 2e 0a 57 hed as needed..W
1550: 68 65 6e 20 75 73 69 6e 67 20 74 68 65 20 5c 66 hen using the \f
1560: 42 54 63 6c 5f 41 70 70 65 6e 64 2a 5c 66 52 20 BTcl_Append*\fR
1570: 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 family of functi
1580: 6f 6e 73 20 77 68 65 72 65 20 74 68 65 0a 69 6e ons where the.in
1590: 74 65 72 70 72 65 74 65 72 27 73 20 72 65 73 75 terpreter's resu
15a0: 6c 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 lt is the value
15b0: 62 65 69 6e 67 20 61 70 70 65 6e 64 65 64 20 74 being appended t
15c0: 6f 2c 20 69 74 20 69 73 20 69 6d 70 6f 72 74 61 o, it is importa
15d0: 6e 74 0a 74 6f 20 63 61 6c 6c 20 54 63 6c 5f 52 nt.to call Tcl_R
15e0: 65 73 65 74 52 65 73 75 6c 74 20 66 69 72 73 74 esetResult first
15f0: 20 74 6f 20 65 6e 73 75 72 65 20 79 6f 75 20 61 to ensure you a
1600: 72 65 20 6e 6f 74 20 75 6e 69 6e 74 65 6e 74 69 re not unintenti
1610: 6f 6e 61 6c 6c 79 0a 61 70 70 65 6e 64 69 6e 67 onally.appending
1620: 20 74 6f 20 65 78 69 73 74 69 6e 67 20 64 61 74 to existing dat
1630: 61 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 a in the result
1640: 76 61 6c 75 65 2e 0a 2e 50 50 0a 5c 66 42 54 63 value...PP.\fBTc
1650: 6c 5f 4e 65 77 53 74 72 69 6e 67 4f 62 6a 5c 66 l_NewStringObj\f
1660: 52 20 61 6e 64 20 5c 66 42 54 63 6c 5f 53 65 74 R and \fBTcl_Set
1670: 53 74 72 69 6e 67 4f 62 6a 5c 66 52 20 63 72 65 StringObj\fR cre
1680: 61 74 65 20 61 20 6e 65 77 20 76 61 6c 75 65 0a ate a new value.
1690: 6f 72 20 6d 6f 64 69 66 79 20 61 6e 20 65 78 69 or modify an exi
16a0: 73 74 69 6e 67 20 76 61 6c 75 65 20 74 6f 20 68 sting value to h
16b0: 6f 6c 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 old a copy of th
16c0: 65 20 73 74 72 69 6e 67 20 67 69 76 65 6e 20 62 e string given b
16d0: 79 0a 5c 66 49 62 79 74 65 73 5c 66 52 20 61 6e y.\fIbytes\fR an
16e0: 64 20 5c 66 49 6c 65 6e 67 74 68 5c 66 52 2e 20 d \fIlength\fR.
16f0: 20 5c 66 42 54 63 6c 5f 4e 65 77 55 6e 69 63 6f \fBTcl_NewUnico
1700: 64 65 4f 62 6a 5c 66 52 20 61 6e 64 0a 5c 66 42 deObj\fR and.\fB
1710: 54 63 6c 5f 53 65 74 55 6e 69 63 6f 64 65 4f 62 Tcl_SetUnicodeOb
1720: 6a 5c 66 52 20 63 72 65 61 74 65 20 61 20 6e 65 j\fR create a ne
1730: 77 20 76 61 6c 75 65 20 6f 72 20 6d 6f 64 69 66 w value or modif
1740: 79 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 76 61 y an existing.va
1750: 6c 75 65 20 74 6f 20 68 6f 6c 64 20 61 20 63 6f lue to hold a co
1760: 70 79 20 6f 66 20 74 68 65 20 55 6e 69 63 6f 64 py of the Unicod
1770: 65 20 73 74 72 69 6e 67 20 67 69 76 65 6e 20 62 e string given b
1780: 79 20 5c 66 49 75 6e 69 63 6f 64 65 5c 66 52 20 y \fIunicode\fR
1790: 61 6e 64 0a 5c 66 49 6e 75 6d 43 68 61 72 73 5c and.\fInumChars\
17a0: 66 52 2e 20 20 5c 66 42 54 63 6c 5f 4e 65 77 53 fR. \fBTcl_NewS
17b0: 74 72 69 6e 67 4f 62 6a 5c 66 52 20 61 6e 64 20 tringObj\fR and
17c0: 5c 66 42 54 63 6c 5f 4e 65 77 55 6e 69 63 6f 64 \fBTcl_NewUnicod
17d0: 65 4f 62 6a 5c 66 52 0a 72 65 74 75 72 6e 20 61 eObj\fR.return a
17e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 pointer to a ne
17f0: 77 6c 79 20 63 72 65 61 74 65 64 20 76 61 6c 75 wly created valu
1800: 65 20 77 69 74 68 20 72 65 66 65 72 65 6e 63 65 e with reference
1810: 20 63 6f 75 6e 74 20 7a 65 72 6f 2e 0a 41 6c 6c count zero..All
1820: 20 66 6f 75 72 20 70 72 6f 63 65 64 75 72 65 73 four procedures
1830: 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 74 set the value t
1840: 6f 20 68 6f 6c 64 20 61 20 63 6f 70 79 20 6f 66 o hold a copy of
1850: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 73 the specified.s
1860: 74 72 69 6e 67 2e 20 20 5c 66 42 54 63 6c 5f 53 tring. \fBTcl_S
1870: 65 74 53 74 72 69 6e 67 4f 62 6a 5c 66 52 20 61 etStringObj\fR a
1880: 6e 64 20 5c 66 42 54 63 6c 5f 53 65 74 55 6e 69 nd \fBTcl_SetUni
1890: 63 6f 64 65 4f 62 6a 5c 66 52 20 66 72 65 65 20 codeObj\fR free
18a0: 61 6e 79 0a 6f 6c 64 20 73 74 72 69 6e 67 20 72 any.old string r
18b0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 epresentation as
18c0: 20 77 65 6c 6c 20 61 73 20 61 6e 79 20 6f 6c 64 well as any old
18d0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
18e0: 65 6e 74 61 74 69 6f 6e 0a 6f 66 20 74 68 65 20 entation.of the
18f0: 76 61 6c 75 65 2e 0a 2e 50 50 0a 5c 66 42 54 63 value...PP.\fBTc
1900: 6c 5f 47 65 74 53 74 72 69 6e 67 46 72 6f 6d 4f l_GetStringFromO
1910: 62 6a 5c 66 52 20 61 6e 64 20 5c 66 42 54 63 6c bj\fR and \fBTcl
1920: 5f 47 65 74 53 74 72 69 6e 67 5c 66 52 20 72 65 _GetString\fR re
1930: 74 75 72 6e 20 61 20 76 61 6c 75 65 27 73 0a 73 turn a value's.s
1940: 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 tring representa
1950: 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20 67 tion. This is g
1960: 69 76 65 6e 20 62 79 20 74 68 65 20 72 65 74 75 iven by the retu
1970: 72 6e 65 64 20 62 79 74 65 20 70 6f 69 6e 74 65 rned byte pointe
1980: 72 20 61 6e 64 0a 28 66 6f 72 20 5c 66 42 54 63 r and.(for \fBTc
1990: 6c 5f 47 65 74 53 74 72 69 6e 67 46 72 6f 6d 4f l_GetStringFromO
19a0: 62 6a 5c 66 52 29 20 6c 65 6e 67 74 68 2c 20 77 bj\fR) length, w
19b0: 68 69 63 68 20 69 73 20 73 74 6f 72 65 64 20 69 hich is stored i
19c0: 6e 0a 5c 66 49 6c 65 6e 67 74 68 50 74 72 5c 66 n.\fIlengthPtr\f
19d0: 52 20 69 66 20 69 74 20 69 73 20 6e 6f 6e 2d 4e R if it is non-N
19e0: 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 76 61 6c ULL. If the val
19f0: 75 65 27 73 20 55 54 46 20 73 74 72 69 6e 67 0a ue's UTF string.
1a00: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 representation i
1a10: 73 20 69 6e 76 61 6c 69 64 20 28 69 74 73 20 62 s invalid (its b
1a20: 79 74 65 20 70 6f 69 6e 74 65 72 20 69 73 20 4e yte pointer is N
1a30: 55 4c 4c 29 2c 20 74 68 65 20 73 74 72 69 6e 67 ULL), the string
1a40: 0a 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 .representation
1a50: 69 73 20 72 65 67 65 6e 65 72 61 74 65 64 20 66 is regenerated f
1a60: 72 6f 6d 20 74 68 65 20 76 61 6c 75 65 27 73 20 rom the value's
1a70: 69 6e 74 65 72 6e 61 6c 0a 72 65 70 72 65 73 65 internal.represe
1a80: 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 20 73 74 ntation. The st
1a90: 6f 72 61 67 65 20 72 65 66 65 72 65 6e 63 65 64 orage referenced
1aa0: 20 62 79 20 74 68 65 20 72 65 74 75 72 6e 65 64 by the returned
1ab0: 20 62 79 74 65 20 70 6f 69 6e 74 65 72 0a 69 73 byte pointer.is
1ac0: 20 6f 77 6e 65 64 20 62 79 20 74 68 65 20 76 61 owned by the va
1ad0: 6c 75 65 20 6d 61 6e 61 67 65 72 2e 20 20 49 74 lue manager. It
1ae0: 20 69 73 20 70 61 73 73 65 64 20 62 61 63 6b 20 is passed back
1af0: 61 73 20 61 20 77 72 69 74 61 62 6c 65 0a 70 6f as a writable.po
1b00: 69 6e 74 65 72 20 73 6f 20 74 68 61 74 20 65 78 inter so that ex
1b10: 74 65 6e 73 69 6f 6e 20 61 75 74 68 6f 72 20 63 tension author c
1b20: 72 65 61 74 69 6e 67 20 74 68 65 69 72 20 6f 77 reating their ow
1b30: 6e 20 5c 66 42 54 63 6c 5f 4f 62 6a 54 79 70 65 n \fBTcl_ObjType
1b40: 5c 66 52 0a 77 69 6c 6c 20 62 65 20 61 62 6c 65 \fR.will be able
1b50: 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 73 to modify the s
1b60: 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 tring representa
1b70: 74 69 6f 6e 20 77 69 74 68 69 6e 20 74 68 65 0a tion within the.
1b80: 5c 66 42 54 63 6c 5f 55 70 64 61 74 65 53 74 72 \fBTcl_UpdateStr
1b90: 69 6e 67 50 72 6f 63 5c 66 52 20 6f 66 20 74 68 ingProc\fR of th
1ba0: 65 69 72 20 5c 66 42 54 63 6c 5f 4f 62 6a 54 79 eir \fBTcl_ObjTy
1bb0: 70 65 5c 66 52 2e 20 20 45 78 63 65 70 74 20 66 pe\fR. Except f
1bc0: 6f 72 20 74 68 61 74 0a 6c 69 6d 69 74 65 64 20 or that.limited
1bd0: 70 75 72 70 6f 73 65 2c 20 74 68 65 20 70 6f 69 purpose, the poi
1be0: 6e 74 65 72 20 72 65 74 75 72 6e 65 64 20 62 79 nter returned by
1bf0: 20 5c 66 42 54 63 6c 5f 47 65 74 53 74 72 69 6e \fBTcl_GetStrin
1c00: 67 46 72 6f 6d 4f 62 6a 5c 66 52 0a 6f 72 20 5c gFromObj\fR.or \
1c10: 66 42 54 63 6c 5f 47 65 74 53 74 72 69 6e 67 5c fBTcl_GetString\
1c20: 66 52 20 73 68 6f 75 6c 64 20 62 65 20 74 72 65 fR should be tre
1c30: 61 74 65 64 20 61 73 20 72 65 61 64 2d 6f 6e 6c ated as read-onl
1c40: 79 2e 20 20 49 74 20 69 73 0a 72 65 63 6f 6d 6d y. It is.recomm
1c50: 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 ended that this
1c60: 70 6f 69 6e 74 65 72 20 62 65 20 61 73 73 69 67 pointer be assig
1c70: 6e 65 64 20 74 6f 20 61 20 28 63 6f 6e 73 74 20 ned to a (const
1c80: 63 68 61 72 20 2a 29 20 76 61 72 69 61 62 6c 65 char *) variable
1c90: 2e 0a 45 76 65 6e 20 69 6e 20 74 68 65 20 6c 69 ..Even in the li
1ca0: 6d 69 74 65 64 20 73 69 74 75 61 74 69 6f 6e 73 mited situations
1cb0: 20 77 68 65 72 65 20 77 72 69 74 69 6e 67 20 74 where writing t
1cc0: 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 69 o this pointer i
1cd0: 73 0a 61 63 63 65 70 74 61 62 6c 65 2c 20 6f 6e s.acceptable, on
1ce0: 65 20 73 68 6f 75 6c 64 20 74 61 6b 65 20 63 61 e should take ca
1cf0: 72 65 20 74 6f 20 72 65 73 70 65 63 74 20 74 68 re to respect th
1d00: 65 20 63 6f 70 79 2d 6f 6e 2d 77 72 69 74 65 0a e copy-on-write.
1d10: 73 65 6d 61 6e 74 69 63 73 20 72 65 71 75 69 72 semantics requir
1d20: 65 64 20 62 79 20 5c 66 42 54 63 6c 5f 4f 62 6a ed by \fBTcl_Obj
1d30: 5c 66 52 27 73 2c 20 77 69 74 68 20 61 70 70 72 \fR's, with appr
1d40: 6f 70 72 69 61 74 65 20 63 61 6c 6c 73 0a 74 6f opriate calls.to
1d50: 20 5c 66 42 54 63 6c 5f 49 73 53 68 61 72 65 64 \fBTcl_IsShared
1d60: 5c 66 52 20 61 6e 64 20 5c 66 42 54 63 6c 5f 44 \fR and \fBTcl_D
1d70: 75 70 6c 69 63 61 74 65 4f 62 6a 5c 66 52 20 70 uplicateObj\fR p
1d80: 72 69 6f 72 20 74 6f 20 61 6e 79 0a 69 6e 2d 70 rior to any.in-p
1d90: 6c 61 63 65 20 6d 6f 64 69 66 69 63 61 74 69 6f lace modificatio
1da0: 6e 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 n of the string
1db0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2e 20 representation.
1dc0: 49 66 20 5c 66 49 6c 65 6e 67 74 68 50 74 72 5c If \fIlengthPtr\
1dd0: 66 52 0a 70 6f 69 6e 74 73 20 74 6f 20 61 6e 20 fR.points to an
1de0: 5c 66 42 69 6e 74 5c 66 52 20 76 61 72 69 61 62 \fBint\fR variab
1df0: 6c 65 2c 20 61 6e 64 20 74 68 65 20 73 74 72 69 le, and the stri
1e00: 6e 67 20 68 61 73 20 6d 6f 72 65 20 74 68 61 6e ng has more than
1e10: 20 32 5e 33 31 20 62 79 74 65 73 2c 0a 61 20 70 2^31 bytes,.a p
1e20: 61 6e 69 63 20 77 69 6c 6c 20 72 65 73 75 6c 74 anic will result
1e30: 2e 0a 54 68 65 20 70 72 6f 63 65 64 75 72 65 20 ..The procedure
1e40: 5c 66 42 54 63 6c 5f 47 65 74 53 74 72 69 6e 67 \fBTcl_GetString
1e50: 5c 66 52 20 69 73 20 75 73 65 64 20 69 6e 20 74 \fR is used in t
1e60: 68 65 20 63 6f 6d 6d 6f 6e 20 63 61 73 65 0a 77 he common case.w
1e70: 68 65 72 65 20 74 68 65 20 63 61 6c 6c 65 72 20 here the caller
1e80: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 68 does not need th
1e90: 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 e length of the
1ea0: 73 74 72 69 6e 67 0a 72 65 70 72 65 73 65 6e 74 string.represent
1eb0: 61 74 69 6f 6e 2e 0a 2e 50 50 0a 5c 66 42 54 63 ation...PP.\fBTc
1ec0: 6c 5f 47 65 74 55 6e 69 63 6f 64 65 46 72 6f 6d l_GetUnicodeFrom
1ed0: 4f 62 6a 5c 66 52 20 61 6e 64 20 5c 66 42 54 63 Obj\fR and \fBTc
1ee0: 6c 5f 47 65 74 55 6e 69 63 6f 64 65 5c 66 52 20 l_GetUnicode\fR
1ef0: 72 65 74 75 72 6e 20 61 20 76 61 6c 75 65 27 73 return a value's
1f00: 0a 76 61 6c 75 65 20 61 73 20 61 20 55 6e 69 63 .value as a Unic
1f10: 6f 64 65 20 73 74 72 69 6e 67 2e 20 20 54 68 69 ode string. Thi
1f20: 73 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 s is given by th
1f30: 65 20 72 65 74 75 72 6e 65 64 20 70 6f 69 6e 74 e returned point
1f40: 65 72 20 61 6e 64 0a 28 66 6f 72 20 5c 66 42 54 er and.(for \fBT
1f50: 63 6c 5f 47 65 74 55 6e 69 63 6f 64 65 46 72 6f cl_GetUnicodeFro
1f60: 6d 4f 62 6a 5c 66 52 29 20 6c 65 6e 67 74 68 2c mObj\fR) length,
1f70: 20 77 68 69 63 68 20 69 73 20 73 74 6f 72 65 64 which is stored
1f80: 20 69 6e 0a 5c 66 49 6c 65 6e 67 74 68 50 74 72 in.\fIlengthPtr
1f90: 5c 66 52 20 69 66 20 69 74 20 69 73 20 6e 6f 6e \fR if it is non
1fa0: 2d 4e 55 4c 4c 2e 20 20 54 68 65 20 73 74 6f 72 -NULL. The stor
1fb0: 61 67 65 20 72 65 66 65 72 65 6e 63 65 64 20 62 age referenced b
1fc0: 79 20 74 68 65 20 72 65 74 75 72 6e 65 64 0a 62 y the returned.b
1fd0: 79 74 65 20 70 6f 69 6e 74 65 72 20 69 73 20 6f yte pointer is o
1fe0: 77 6e 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 wned by the valu
1ff0: 65 20 6d 61 6e 61 67 65 72 20 61 6e 64 20 73 68 e manager and sh
2000: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 6d 6f 64 69 ould not be modi
2010: 66 69 65 64 20 62 79 0a 74 68 65 20 63 61 6c 6c fied by.the call
2020: 65 72 2e 20 20 54 68 65 20 70 72 6f 63 65 64 75 er. The procedu
2030: 72 65 20 5c 66 42 54 63 6c 5f 47 65 74 55 6e 69 re \fBTcl_GetUni
2040: 63 6f 64 65 5c 66 52 20 69 73 20 75 73 65 64 20 code\fR is used
2050: 69 6e 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 63 61 in the common ca
2060: 73 65 0a 77 68 65 72 65 20 74 68 65 20 63 61 6c se.where the cal
2070: 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ler does not nee
2080: 64 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 d the length of
2090: 74 68 65 20 75 6e 69 63 6f 64 65 20 73 74 72 69 the unicode stri
20a0: 6e 67 0a 72 65 70 72 65 73 65 6e 74 61 74 69 6f ng.representatio
20b0: 6e 2e 20 49 66 20 5c 66 49 6c 65 6e 67 74 68 50 n. If \fIlengthP
20c0: 74 72 5c 66 52 20 70 6f 69 6e 74 73 20 74 6f 20 tr\fR points to
20d0: 61 6e 20 5c 66 42 69 6e 74 5c 66 52 20 76 61 72 an \fBint\fR var
20e0: 69 61 62 6c 65 2c 0a 61 6e 64 20 74 68 65 20 73 iable,.and the s
20f0: 74 72 69 6e 67 20 68 61 73 20 6d 6f 72 65 20 74 tring has more t
2100: 68 61 6e 20 32 5e 33 31 20 75 6e 69 63 6f 64 65 han 2^31 unicode
2110: 20 63 68 61 72 61 63 74 65 72 73 2c 20 61 20 70 characters, a p
2120: 61 6e 69 63 20 77 69 6c 6c 20 72 65 73 75 6c 74 anic will result
2130: 2e 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 47 65 74 ...PP.\fBTcl_Get
2140: 55 6e 69 43 68 61 72 5c 66 52 20 72 65 74 75 72 UniChar\fR retur
2150: 6e 73 20 74 68 65 20 5c 66 49 69 6e 64 65 78 5c ns the \fIindex\
2160: 66 52 27 74 68 20 63 68 61 72 61 63 74 65 72 20 fR'th character
2170: 69 6e 20 74 68 65 0a 76 61 6c 75 65 27 73 20 55 in the.value's U
2180: 6e 69 63 6f 64 65 20 72 65 70 72 65 73 65 6e 74 nicode represent
2190: 61 74 69 6f 6e 2e 20 49 66 20 74 68 65 20 69 6e ation. If the in
21a0: 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 dex is out of ra
21b0: 6e 67 65 20 6f 72 0a 69 74 20 72 65 66 65 72 65 nge or.it refere
21c0: 6e 63 65 73 20 61 20 6c 6f 77 20 73 75 72 72 6f nces a low surro
21d0: 67 61 74 65 20 70 72 65 63 65 64 65 64 20 62 79 gate preceded by
21e0: 20 61 20 68 69 67 68 20 73 75 72 72 6f 67 61 74 a high surrogat
21f0: 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 2d 31 e, it returns -1
2200: 3b 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 47 65 74 ;..PP.\fBTcl_Get
2210: 52 61 6e 67 65 5c 66 52 20 72 65 74 75 72 6e 73 Range\fR returns
2220: 20 61 20 6e 65 77 6c 79 20 63 72 65 61 74 65 64 a newly created
2230: 20 76 61 6c 75 65 20 63 6f 6d 70 72 69 73 65 64 value comprised
2240: 20 6f 66 20 74 68 65 0a 63 68 61 72 61 63 74 65 of the.characte
2250: 72 73 20 62 65 74 77 65 65 6e 20 5c 66 49 66 69 rs between \fIfi
2260: 72 73 74 5c 66 52 20 61 6e 64 20 5c 66 49 6c 61 rst\fR and \fIla
2270: 73 74 5c 66 52 20 28 69 6e 63 6c 75 73 69 76 65 st\fR (inclusive
2280: 29 20 69 6e 20 74 68 65 20 76 61 6c 75 65 27 73 ) in the value's
2290: 0a 55 6e 69 63 6f 64 65 20 72 65 70 72 65 73 65 .Unicode represe
22a0: 6e 74 61 74 69 6f 6e 2e 20 20 49 66 20 74 68 65 ntation. If the
22b0: 20 76 61 6c 75 65 27 73 20 55 6e 69 63 6f 64 65 value's Unicode
22c0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 0a representation.
22d0: 69 73 20 69 6e 76 61 6c 69 64 2c 20 74 68 65 20 is invalid, the
22e0: 55 6e 69 63 6f 64 65 20 72 65 70 72 65 73 65 6e Unicode represen
22f0: 74 61 74 69 6f 6e 20 69 73 20 72 65 67 65 6e 65 tation is regene
2300: 72 61 74 65 64 20 66 72 6f 6d 20 74 68 65 20 76 rated from the v
2310: 61 6c 75 65 27 73 0a 73 74 72 69 6e 67 20 72 65 alue's.string re
2320: 70 72 65 73 65 6e 74 61 74 69 6f 6e 2e 20 20 49 presentation. I
2330: 66 20 5c 66 49 66 69 72 73 74 5c 66 52 20 3d 3d f \fIfirst\fR ==
2340: 20 54 43 4c 5f 49 4e 44 45 58 5f 4e 4f 4e 45 2c TCL_INDEX_NONE,
2350: 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
2360: 65 64 0a 73 74 72 69 6e 67 20 73 74 61 72 74 73 ed.string starts
2370: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e at the beginnin
2380: 67 20 6f 66 20 74 68 65 20 76 61 6c 75 65 2e 20 g of the value.
2390: 49 66 20 5c 66 49 6c 61 73 74 5c 66 52 20 3d 3d If \fIlast\fR ==
23a0: 20 54 43 4c 5f 49 4e 44 45 58 5f 4e 4f 4e 45 2c TCL_INDEX_NONE,
23b0: 0a 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e .then the return
23c0: 65 64 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 ed string ends a
23d0: 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 t the end of the
23e0: 20 76 61 6c 75 65 2e 0a 2e 50 50 0a 5c 66 42 54 value...PP.\fBT
23f0: 63 6c 5f 47 65 74 43 68 61 72 4c 65 6e 67 74 68 cl_GetCharLength
2400: 5c 66 52 20 72 65 74 75 72 6e 73 20 74 68 65 20 \fR returns the
2410: 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
2420: 74 65 72 73 20 28 61 73 20 6f 70 70 6f 73 65 64 ters (as opposed
2430: 0a 74 6f 20 62 79 74 65 73 29 20 69 6e 20 74 68 .to bytes) in th
2440: 65 20 73 74 72 69 6e 67 20 76 61 6c 75 65 2e 0a e string value..
2450: 2e 50 50 0a 5c 66 42 54 63 6c 5f 41 70 70 65 6e .PP.\fBTcl_Appen
2460: 64 54 6f 4f 62 6a 5c 66 52 20 61 70 70 65 6e 64 dToObj\fR append
2470: 73 20 74 68 65 20 64 61 74 61 20 67 69 76 65 6e s the data given
2480: 20 62 79 20 5c 66 49 62 79 74 65 73 5c 66 52 20 by \fIbytes\fR
2490: 61 6e 64 0a 5c 66 49 6c 65 6e 67 74 68 5c 66 52 and.\fIlength\fR
24a0: 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 72 to the string r
24b0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 epresentation of
24c0: 20 74 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 the value speci
24d0: 66 69 65 64 20 62 79 0a 5c 66 49 6f 62 6a 50 74 fied by.\fIobjPt
24e0: 72 5c 66 52 2e 20 20 49 66 20 74 68 65 20 76 61 r\fR. If the va
24f0: 6c 75 65 20 68 61 73 20 61 6e 20 69 6e 76 61 6c lue has an inval
2500: 69 64 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 id string repres
2510: 65 6e 74 61 74 69 6f 6e 2c 0a 74 68 65 6e 20 61 entation,.then a
2520: 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
2530: 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 5c 66 49 e to convert \fI
2540: 62 79 74 65 73 5c 66 52 20 69 73 20 74 6f 20 74 bytes\fR is to t
2550: 68 65 20 55 6e 69 63 6f 64 65 0a 66 6f 72 6d 61 he Unicode.forma
2560: 74 2e 20 20 49 66 20 74 68 65 20 63 6f 6e 76 65 t. If the conve
2570: 72 73 69 6f 6e 20 69 73 20 73 75 63 63 65 73 73 rsion is success
2580: 66 75 6c 2c 20 74 68 65 6e 20 74 68 65 20 63 6f ful, then the co
2590: 6e 76 65 72 74 65 64 20 66 6f 72 6d 20 6f 66 0a nverted form of.
25a0: 5c 66 49 62 79 74 65 73 5c 66 52 20 69 73 20 61 \fIbytes\fR is a
25b0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65 20 76 ppended to the v
25c0: 61 6c 75 65 27 73 20 55 6e 69 63 6f 64 65 20 72 alue's Unicode r
25d0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2e 0a 4f epresentation..O
25e0: 74 68 65 72 77 69 73 65 2c 20 74 68 65 20 76 61 therwise, the va
25f0: 6c 75 65 27 73 20 55 6e 69 63 6f 64 65 20 72 65 lue's Unicode re
2600: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 presentation is
2610: 69 6e 76 61 6c 69 64 61 74 65 64 20 61 6e 64 0a invalidated and.
2620: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 74 68 65 converted to the
2630: 20 55 54 46 20 66 6f 72 6d 61 74 2c 20 61 6e 64 UTF format, and
2640: 20 5c 66 49 62 79 74 65 73 5c 66 52 20 69 73 20 \fIbytes\fR is
2650: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 65 0a appended to the.
2660: 76 61 6c 75 65 27 73 20 6e 65 77 20 73 74 72 69 value's new stri
2670: 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f ng representatio
2680: 6e 2e 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 41 70 n...PP.\fBTcl_Ap
2690: 70 65 6e 64 55 6e 69 63 6f 64 65 54 6f 4f 62 6a pendUnicodeToObj
26a0: 5c 66 52 20 61 70 70 65 6e 64 73 20 74 68 65 20 \fR appends the
26b0: 55 6e 69 63 6f 64 65 20 73 74 72 69 6e 67 20 67 Unicode string g
26c0: 69 76 65 6e 20 62 79 0a 5c 66 49 75 6e 69 63 6f iven by.\fIunico
26d0: 64 65 5c 66 52 20 61 6e 64 20 5c 66 49 6e 75 6d de\fR and \fInum
26e0: 43 68 61 72 73 5c 66 52 20 74 6f 20 74 68 65 20 Chars\fR to the
26f0: 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 value specified
2700: 62 79 0a 5c 66 49 6f 62 6a 50 74 72 5c 66 52 2e by.\fIobjPtr\fR.
2710: 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 68 If the value h
2720: 61 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 6e as an invalid Un
2730: 69 63 6f 64 65 20 72 65 70 72 65 73 65 6e 74 61 icode representa
2740: 74 69 6f 6e 2c 0a 74 68 65 6e 20 5c 66 49 75 6e tion,.then \fIun
2750: 69 63 6f 64 65 5c 66 52 20 69 73 20 63 6f 6e 76 icode\fR is conv
2760: 65 72 74 65 64 20 74 6f 20 74 68 65 20 55 54 46 erted to the UTF
2770: 20 66 6f 72 6d 61 74 20 61 6e 64 20 61 70 70 65 format and appe
2780: 6e 64 65 64 20 74 6f 20 74 68 65 0a 76 61 6c 75 nded to the.valu
2790: 65 27 73 20 73 74 72 69 6e 67 20 72 65 70 72 65 e's string repre
27a0: 73 65 6e 74 61 74 69 6f 6e 2e 20 20 41 70 70 65 sentation. Appe
27b0: 6e 64 73 20 61 72 65 20 6f 70 74 69 6d 69 7a 65 nds are optimize
27c0: 64 20 74 6f 20 68 61 6e 64 6c 65 0a 72 65 70 65 d to handle.repe
27d0: 61 74 65 64 20 61 70 70 65 6e 64 73 20 72 65 6c ated appends rel
27e0: 61 74 69 76 65 6c 79 20 65 66 66 69 63 69 65 6e atively efficien
27f0: 74 6c 79 20 28 69 74 20 6f 76 65 72 2d 61 6c 6c tly (it over-all
2800: 6f 63 61 74 65 73 20 74 68 65 20 73 74 72 69 6e ocates the strin
2810: 67 0a 6f 72 20 55 6e 69 63 6f 64 65 20 73 70 61 g.or Unicode spa
2820: 63 65 20 74 6f 20 61 76 6f 69 64 20 72 65 70 65 ce to avoid repe
2830: 61 74 65 64 20 72 65 61 6c 6c 6f 63 61 74 69 6f ated reallocatio
2840: 6e 73 20 61 6e 64 20 63 6f 70 69 65 73 20 6f 66 ns and copies of
2850: 0a 76 61 6c 75 65 27 73 20 73 74 72 69 6e 67 20 .value's string
2860: 76 61 6c 75 65 29 2e 0a 2e 50 50 0a 5c 66 42 54 value)...PP.\fBT
2870: 63 6c 5f 41 70 70 65 6e 64 4f 62 6a 54 6f 4f 62 cl_AppendObjToOb
2880: 6a 5c 66 52 20 69 73 20 73 69 6d 69 6c 61 72 20 j\fR is similar
2890: 74 6f 20 5c 66 42 54 63 6c 5f 41 70 70 65 6e 64 to \fBTcl_Append
28a0: 54 6f 4f 62 6a 5c 66 52 2c 20 62 75 74 20 69 74 ToObj\fR, but it
28b0: 0a 61 70 70 65 6e 64 73 20 74 68 65 20 73 74 72 .appends the str
28c0: 69 6e 67 20 6f 72 20 55 6e 69 63 6f 64 65 20 76 ing or Unicode v
28d0: 61 6c 75 65 20 28 77 68 69 63 68 65 76 65 72 20 alue (whichever
28e0: 65 78 69 73 74 73 20 61 6e 64 20 69 73 20 62 65 exists and is be
28f0: 73 74 0a 73 75 69 74 65 64 20 74 6f 20 62 65 20 st.suited to be
2900: 61 70 70 65 6e 64 65 64 20 74 6f 20 5c 66 49 6f appended to \fIo
2910: 62 6a 50 74 72 5c 66 52 29 20 6f 66 20 5c 66 49 bjPtr\fR) of \fI
2920: 61 70 70 65 6e 64 4f 62 6a 50 74 72 5c 66 52 20 appendObjPtr\fR
2930: 74 6f 0a 5c 66 49 6f 62 6a 50 74 72 5c 66 52 2e to.\fIobjPtr\fR.
2940: 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 41 70 70 65 ..PP.\fBTcl_Appe
2950: 6e 64 53 74 72 69 6e 67 73 54 6f 4f 62 6a 5c 66 ndStringsToObj\f
2960: 52 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 R is similar to
2970: 5c 66 42 54 63 6c 5f 41 70 70 65 6e 64 54 6f 4f \fBTcl_AppendToO
2980: 62 6a 5c 66 52 0a 65 78 63 65 70 74 20 74 68 61 bj\fR.except tha
2990: 74 20 69 74 20 63 61 6e 20 62 65 20 70 61 73 73 t it can be pass
29a0: 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 ed more than one
29b0: 20 76 61 6c 75 65 20 74 6f 20 61 70 70 65 6e 64 value to append
29c0: 20 61 6e 64 0a 65 61 63 68 20 76 61 6c 75 65 20 and.each value
29d0: 6d 75 73 74 20 62 65 20 61 20 6e 75 6c 6c 2d 74 must be a null-t
29e0: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
29f0: 20 28 69 2e 65 2e 20 6e 6f 6e 65 20 6f 66 20 74 (i.e. none of t
2a00: 68 65 0a 76 61 6c 75 65 73 20 6d 61 79 20 63 6f he.values may co
2a10: 6e 74 61 69 6e 20 69 6e 74 65 72 6e 61 6c 20 6e ntain internal n
2a20: 75 6c 6c 20 63 68 61 72 61 63 74 65 72 73 29 2e ull characters).
2a30: 20 20 41 6e 79 20 6e 75 6d 62 65 72 20 6f 66 0a Any number of.
2a40: 5c 66 49 73 74 72 69 6e 67 5c 66 52 20 61 72 67 \fIstring\fR arg
2a50: 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 20 70 72 uments may be pr
2a60: 6f 76 69 64 65 64 2c 20 62 75 74 20 74 68 65 20 ovided, but the
2a70: 6c 61 73 74 20 61 72 67 75 6d 65 6e 74 0a 6d 75 last argument.mu
2a80: 73 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 st be a NULL poi
2a90: 6e 74 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 nter to indicate
2aa0: 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
2ab0: 6c 69 73 74 2e 0a 2e 50 50 0a 5c 66 42 54 63 6c list...PP.\fBTcl
2ac0: 5f 41 70 70 65 6e 64 4c 69 6d 69 74 65 64 54 6f _AppendLimitedTo
2ad0: 4f 62 6a 5c 66 52 20 69 73 20 73 69 6d 69 6c 61 Obj\fR is simila
2ae0: 72 20 74 6f 20 5c 66 42 54 63 6c 5f 41 70 70 65 r to \fBTcl_Appe
2af0: 6e 64 54 6f 4f 62 6a 5c 66 52 0a 65 78 63 65 70 ndToObj\fR.excep
2b00: 74 20 74 68 61 74 20 69 74 20 69 6d 70 6f 73 65 t that it impose
2b10: 73 20 61 20 6c 69 6d 69 74 20 6f 6e 20 68 6f 77 s a limit on how
2b20: 20 6d 61 6e 79 20 62 79 74 65 73 20 61 72 65 20 many bytes are
2b30: 61 70 70 65 6e 64 65 64 2e 0a 54 68 69 73 20 63 appended..This c
2b40: 61 6e 20 62 65 20 68 61 6e 64 79 20 77 68 65 6e an be handy when
2b50: 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 62 the string to b
2b60: 65 20 61 70 70 65 6e 64 65 64 20 6d 69 67 68 74 e appended might
2b70: 20 62 65 0a 76 65 72 79 20 6c 61 72 67 65 2c 20 be.very large,
2b80: 62 75 74 20 74 68 65 20 76 61 6c 75 65 20 62 65 but the value be
2b90: 69 6e 67 20 63 6f 6e 73 74 72 75 63 74 65 64 20 ing constructed
2ba0: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c should not be al
2bb0: 6c 6f 77 65 64 20 74 6f 20 67 72 6f 77 0a 77 69 lowed to grow.wi
2bc0: 74 68 6f 75 74 20 62 6f 75 6e 64 2e 20 41 20 63 thout bound. A c
2bd0: 6f 6d 6d 6f 6e 20 75 73 61 67 65 20 69 73 20 77 ommon usage is w
2be0: 68 65 6e 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 hen constructing
2bf0: 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
2c00: 65 2c 20 77 68 65 72 65 20 74 68 65 0a 65 6e 64 e, where the.end
2c10: 20 72 65 73 75 6c 74 20 73 68 6f 75 6c 64 20 62 result should b
2c20: 65 20 6b 65 70 74 20 73 68 6f 72 74 20 65 6e 6f e kept short eno
2c30: 75 67 68 20 74 6f 20 62 65 20 72 65 61 64 2e 0a ugh to be read..
2c40: 42 79 74 65 73 20 66 72 6f 6d 20 5c 66 49 62 79 Bytes from \fIby
2c50: 74 65 73 5c 66 52 20 61 72 65 20 61 70 70 65 6e tes\fR are appen
2c60: 64 65 64 20 74 6f 20 5c 66 49 6f 62 6a 50 74 72 ded to \fIobjPtr
2c70: 5c 66 52 2c 20 62 75 74 20 6e 6f 20 6d 6f 72 65 \fR, but no more
2c80: 0a 74 68 61 6e 20 5c 66 49 6c 69 6d 69 74 5c 66 .than \fIlimit\f
2c90: 52 20 62 79 74 65 73 20 74 6f 74 61 6c 20 61 72 R bytes total ar
2ca0: 65 20 74 6f 20 62 65 20 61 70 70 65 6e 64 65 64 e to be appended
2cb0: 2e 20 49 66 20 74 68 65 20 6c 69 6d 69 74 20 70 . If the limit p
2cc0: 72 65 76 65 6e 74 73 0a 61 6c 6c 20 5c 66 49 6c revents.all \fIl
2cd0: 65 6e 67 74 68 5c 66 52 20 62 79 74 65 73 20 74 ength\fR bytes t
2ce0: 68 61 74 20 61 72 65 20 61 76 61 69 6c 61 62 6c hat are availabl
2cf0: 65 20 66 72 6f 6d 20 62 65 69 6e 67 20 61 70 70 e from being app
2d00: 65 6e 64 65 64 2c 20 74 68 65 6e 20 74 68 65 0a ended, then the.
2d10: 61 70 70 65 6e 64 69 6e 67 20 69 73 20 64 6f 6e appending is don
2d20: 65 20 73 6f 20 74 68 61 74 20 74 68 65 20 6c 61 e so that the la
2d30: 73 74 20 62 79 74 65 73 20 61 70 70 65 6e 64 65 st bytes appende
2d40: 64 20 61 72 65 20 66 72 6f 6d 20 74 68 65 0a 73 d are from the.s
2d50: 74 72 69 6e 67 20 5c 66 49 65 6c 6c 69 70 73 69 tring \fIellipsi
2d60: 73 5c 66 52 2e 20 54 68 69 73 20 61 6c 6c 6f 77 s\fR. This allow
2d70: 73 20 66 6f 72 20 61 6e 20 69 6e 64 69 63 61 74 s for an indicat
2d80: 69 6f 6e 20 6f 66 20 74 68 65 20 74 72 75 6e 63 ion of the trunc
2d90: 61 74 69 6f 6e 0a 74 6f 20 62 65 20 6c 65 66 74 ation.to be left
2da0: 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2e 0a in the string..
2db0: 57 68 65 6e 20 5c 66 49 6c 65 6e 67 74 68 5c 66 When \fIlength\f
2dc0: 52 20 69 73 20 5c 66 42 54 43 4c 5f 49 4e 44 45 R is \fBTCL_INDE
2dd0: 58 5f 4e 4f 4e 45 5c 66 52 2c 20 61 6c 6c 20 62 X_NONE\fR, all b
2de0: 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 ytes up to the f
2df0: 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20 61 irst zero byte a
2e00: 72 65 20 61 70 70 65 6e 64 65 64 2c 0a 73 75 62 re appended,.sub
2e10: 6a 65 63 74 20 74 6f 20 74 68 65 20 6c 69 6d 69 ject to the limi
2e20: 74 2e 20 57 68 65 6e 20 5c 66 49 65 6c 6c 69 70 t. When \fIellip
2e30: 73 69 73 5c 66 52 20 69 73 20 4e 55 4c 4c 2c 20 sis\fR is NULL,
2e40: 74 68 65 20 64 65 66 61 75 6c 74 0a 73 74 72 69 the default.stri
2e50: 6e 67 20 5c 66 42 2e 2e 2e 5c 66 52 20 69 73 20 ng \fB...\fR is
2e60: 75 73 65 64 2e 20 57 68 65 6e 20 5c 66 49 65 6c used. When \fIel
2e70: 6c 69 70 73 69 73 5c 66 52 20 69 73 20 6e 6f 6e lipsis\fR is non
2e80: 2d 4e 55 4c 4c 2c 20 69 74 20 6d 75 73 74 20 70 -NULL, it must p
2e90: 6f 69 6e 74 0a 74 6f 20 61 20 7a 65 72 6f 2d 62 oint.to a zero-b
2ea0: 79 74 65 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 yte-terminated s
2eb0: 74 72 69 6e 67 20 69 6e 20 54 63 6c 27 73 20 69 tring in Tcl's i
2ec0: 6e 74 65 72 6e 61 6c 20 55 54 46 20 65 6e 63 6f nternal UTF enco
2ed0: 64 69 6e 67 2e 0a 54 68 65 20 6e 75 6d 62 65 72 ding..The number
2ee0: 20 6f 66 20 62 79 74 65 73 20 61 70 70 65 6e 64 of bytes append
2ef0: 65 64 20 63 61 6e 20 62 65 20 6c 65 73 73 20 74 ed can be less t
2f00: 68 61 6e 20 74 68 65 20 6c 65 73 73 65 72 0a 6f han the lesser.o
2f10: 66 20 5c 66 49 6c 65 6e 67 74 68 5c 66 52 20 61 f \fIlength\fR a
2f20: 6e 64 20 5c 66 49 6c 69 6d 69 74 5c 66 52 20 77 nd \fIlimit\fR w
2f30: 68 65 6e 20 61 70 70 65 6e 64 69 6e 67 20 66 65 hen appending fe
2f40: 77 65 72 0a 62 79 74 65 73 20 69 73 20 6e 65 63 wer.bytes is nec
2f50: 65 73 73 61 72 79 20 74 6f 20 61 70 70 65 6e 64 essary to append
2f60: 20 6f 6e 6c 79 20 77 68 6f 6c 65 20 6d 75 6c 74 only whole mult
2f70: 69 2d 62 79 74 65 20 63 68 61 72 61 63 74 65 72 i-byte character
2f80: 73 2e 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 46 6f s...PP.\fBTcl_Fo
2f90: 72 6d 61 74 5c 66 52 20 69 73 20 74 68 65 20 43 rmat\fR is the C
2fa0: 2d 6c 65 76 65 6c 20 69 6e 74 65 72 66 61 63 65 -level interface
2fb0: 20 74 6f 20 74 68 65 20 65 6e 67 69 6e 65 20 6f to the engine o
2fc0: 66 20 74 68 65 20 5c 66 42 66 6f 72 6d 61 74 5c f the \fBformat\
2fd0: 66 52 0a 63 6f 6d 6d 61 6e 64 2e 20 20 54 68 65 fR.command. The
2fe0: 20 61 63 74 75 61 6c 20 63 6f 6d 6d 61 6e 64 20 actual command
2ff0: 70 72 6f 63 65 64 75 72 65 20 66 6f 72 20 5c 66 procedure for \f
3000: 42 66 6f 72 6d 61 74 5c 66 52 20 69 73 20 6c 69 Bformat\fR is li
3010: 74 74 6c 65 20 6d 6f 72 65 0a 74 68 61 6e 0a 2e ttle more.than..
3020: 50 50 0a 2e 43 53 0a 5c 66 42 54 63 6c 5f 46 6f PP..CS.\fBTcl_Fo
3030: 72 6d 61 74 5c 66 52 28 69 6e 74 65 72 70 2c 20 rmat\fR(interp,
3040: 5c 66 42 54 63 6c 5f 47 65 74 53 74 72 69 6e 67 \fBTcl_GetString
3050: 5c 66 52 28 6f 62 6a 76 5b 31 5d 29 2c 20 6f 62 \fR(objv[1]), ob
3060: 6a 63 2d 32 2c 20 6f 62 6a 76 2b 32 29 3b 0a 2e jc-2, objv+2);..
3070: 43 45 0a 2e 50 50 0a 54 68 65 20 5c 66 49 6f 62 CE..PP.The \fIob
3080: 6a 63 5c 66 52 20 54 63 6c 5f 4f 62 6a 20 76 61 jc\fR Tcl_Obj va
3090: 6c 75 65 73 20 69 6e 20 5c 66 49 6f 62 6a 76 5c lues in \fIobjv\
30a0: 66 52 20 61 72 65 20 66 6f 72 6d 61 74 74 65 64 fR are formatted
30b0: 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 0a 61 into a string.a
30c0: 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 ccording to the
30d0: 63 6f 6e 76 65 72 73 69 6f 6e 20 73 70 65 63 69 conversion speci
30e0: 66 69 63 61 74 69 6f 6e 20 69 6e 20 5c 66 49 66 fication in \fIf
30f0: 6f 72 6d 61 74 5c 66 52 20 61 72 67 75 6d 65 6e ormat\fR argumen
3100: 74 2c 20 66 6f 6c 6c 6f 77 69 6e 67 0a 74 68 65 t, following.the
3110: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 documentation f
3120: 6f 72 20 74 68 65 20 5c 66 42 66 6f 72 6d 61 74 or the \fBformat
3130: 5c 66 52 20 63 6f 6d 6d 61 6e 64 2e 20 20 54 68 \fR command. Th
3140: 65 20 72 65 73 75 6c 74 69 6e 67 20 66 6f 72 6d e resulting form
3150: 61 74 74 65 64 0a 73 74 72 69 6e 67 20 69 73 20 atted.string is
3160: 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 61 20 6e converted to a n
3170: 65 77 20 54 63 6c 5f 4f 62 6a 20 77 69 74 68 20 ew Tcl_Obj with
3180: 72 65 66 63 6f 75 6e 74 20 6f 66 20 7a 65 72 6f refcount of zero
3190: 20 61 6e 64 20 72 65 74 75 72 6e 65 64 2e 0a 49 and returned..I
31a0: 66 20 73 6f 6d 65 20 65 72 72 6f 72 20 68 61 70 f some error hap
31b0: 70 65 6e 73 20 64 75 72 69 6e 67 20 70 72 6f 64 pens during prod
31c0: 75 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 66 6f uction of the fo
31d0: 72 6d 61 74 74 65 64 20 73 74 72 69 6e 67 2c 20 rmatted string,
31e0: 4e 55 4c 4c 20 69 73 0a 72 65 74 75 72 6e 65 64 NULL is.returned
31f0: 2c 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d , and an error m
3200: 65 73 73 61 67 65 20 69 73 20 72 65 63 6f 72 64 essage is record
3210: 65 64 20 69 6e 20 5c 66 49 69 6e 74 65 72 70 5c ed in \fIinterp\
3220: 66 52 2c 20 69 66 20 5c 66 49 69 6e 74 65 72 70 fR, if \fIinterp
3230: 5c 66 52 0a 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e \fR.is non-NULL.
3240: 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 41 70 70 65 ..PP.\fBTcl_Appe
3250: 6e 64 46 6f 72 6d 61 74 54 6f 4f 62 6a 5c 66 52 ndFormatToObj\fR
3260: 20 69 73 20 61 6e 20 61 70 70 65 6e 64 69 6e 67 is an appending
3270: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 66 6f 72 alternative for
3280: 6d 0a 6f 66 20 5c 66 42 54 63 6c 5f 46 6f 72 6d m.of \fBTcl_Form
3290: 61 74 5c 66 52 20 77 69 74 68 20 66 75 6e 63 74 at\fR with funct
32a0: 69 6f 6e 61 6c 69 74 79 20 65 71 75 69 76 61 6c ionality equival
32b0: 65 6e 74 20 74 6f 3a 0a 2e 50 50 0a 2e 43 53 0a ent to:..PP..CS.
32c0: 54 63 6c 5f 4f 62 6a 20 2a 6e 65 77 50 74 72 20 Tcl_Obj *newPtr
32d0: 3d 20 5c 66 42 54 63 6c 5f 46 6f 72 6d 61 74 5c = \fBTcl_Format\
32e0: 66 52 28 69 6e 74 65 72 70 2c 20 66 6f 72 6d 61 fR(interp, forma
32f0: 74 2c 20 6f 62 6a 63 2c 20 6f 62 6a 76 29 3b 0a t, objc, objv);.
3300: 69 66 20 28 6e 65 77 50 74 72 20 3d 3d 20 4e 55 if (newPtr == NU
3310: 4c 4c 29 20 72 65 74 75 72 6e 20 54 43 4c 5f 45 LL) return TCL_E
3320: 52 52 4f 52 3b 0a 5c 66 42 54 63 6c 5f 41 70 70 RROR;.\fBTcl_App
3330: 65 6e 64 4f 62 6a 54 6f 4f 62 6a 5c 66 52 28 6f endObjToObj\fR(o
3340: 62 6a 50 74 72 2c 20 6e 65 77 50 74 72 29 3b 0a bjPtr, newPtr);.
3350: 5c 66 42 54 63 6c 5f 44 65 63 72 52 65 66 43 6f \fBTcl_DecrRefCo
3360: 75 6e 74 5c 66 52 28 6e 65 77 50 74 72 29 3b 0a unt\fR(newPtr);.
3370: 72 65 74 75 72 6e 20 54 43 4c 5f 4f 4b 3b 0a 2e return TCL_OK;..
3380: 43 45 0a 2e 50 50 0a 62 75 74 20 77 69 74 68 20 CE..PP.but with
3390: 67 72 65 61 74 65 72 20 63 6f 6e 76 65 6e 69 65 greater convenie
33a0: 6e 63 65 20 61 6e 64 20 65 66 66 69 63 69 65 6e nce and efficien
33b0: 63 79 20 77 68 65 6e 20 74 68 65 20 61 70 70 65 cy when the appe
33c0: 6e 64 69 6e 67 0a 66 75 6e 63 74 69 6f 6e 61 6c nding.functional
33d0: 69 74 79 20 69 73 20 6e 65 65 64 65 64 2e 0a 2e ity is needed...
33e0: 50 50 0a 5c 66 42 54 63 6c 5f 4f 62 6a 50 72 69 PP.\fBTcl_ObjPri
33f0: 6e 74 66 5c 66 52 20 73 65 72 76 65 73 20 61 73 ntf\fR serves as
3400: 20 61 20 72 65 70 6c 61 63 65 6d 65 6e 74 20 66 a replacement f
3410: 6f 72 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 73 65 or the common se
3420: 71 75 65 6e 63 65 0a 2e 50 50 0a 2e 43 53 0a 63 quence..PP..CS.c
3430: 68 61 72 20 62 75 66 5b 53 4f 4d 45 5f 53 55 49 har buf[SOME_SUI
3440: 54 41 42 4c 45 5f 4c 45 4e 47 54 48 5d 3b 0a 73 TABLE_LENGTH];.s
3450: 70 72 69 6e 74 66 28 62 75 66 2c 20 66 6f 72 6d printf(buf, form
3460: 61 74 2c 20 2e 2e 2e 29 3b 0a 5c 66 42 54 63 6c at, ...);.\fBTcl
3470: 5f 4e 65 77 53 74 72 69 6e 67 4f 62 6a 5c 66 52 _NewStringObj\fR
3480: 28 62 75 66 2c 20 5c 66 42 54 43 4c 5f 49 4e 44 (buf, \fBTCL_IND
3490: 45 58 5f 4e 4f 4e 45 5c 66 52 29 3b 0a 2e 43 45 EX_NONE\fR);..CE
34a0: 0a 2e 50 50 0a 62 75 74 20 77 69 74 68 20 67 72 ..PP.but with gr
34b0: 65 61 74 65 72 20 63 6f 6e 76 65 6e 69 65 6e 63 eater convenienc
34c0: 65 20 61 6e 64 20 6e 6f 20 6e 65 65 64 20 74 6f e and no need to
34d0: 0a 64 65 74 65 72 6d 69 6e 65 20 5c 66 42 53 4f .determine \fBSO
34e0: 4d 45 5f 53 55 49 54 41 42 4c 45 5f 4c 45 4e 47 ME_SUITABLE_LENG
34f0: 54 48 5c 66 52 2e 20 54 68 65 20 66 6f 72 6d 61 TH\fR. The forma
3500: 74 74 69 6e 67 20 69 73 20 64 6f 6e 65 20 77 69 tting is done wi
3510: 74 68 20 74 68 65 20 73 61 6d 65 0a 63 6f 72 65 th the same.core
3520: 20 66 6f 72 6d 61 74 74 69 6e 67 20 65 6e 67 69 formatting engi
3530: 6e 65 20 75 73 65 64 20 62 79 20 5c 66 42 54 63 ne used by \fBTc
3540: 6c 5f 46 6f 72 6d 61 74 5c 66 52 2e 20 20 54 68 l_Format\fR. Th
3550: 69 73 20 6d 65 61 6e 73 20 74 68 65 20 73 65 74 is means the set
3560: 20 6f 66 0a 73 75 70 70 6f 72 74 65 64 20 63 6f of.supported co
3570: 6e 76 65 72 73 69 6f 6e 20 73 70 65 63 69 66 69 nversion specifi
3580: 65 72 73 20 69 73 20 74 68 61 74 20 6f 66 20 74 ers is that of t
3590: 68 65 20 5c 66 42 66 6f 72 6d 61 74 5c 66 52 20 he \fBformat\fR
35a0: 63 6f 6d 6d 61 6e 64 20 61 6e 64 0a 6e 6f 74 20 command and.not
35b0: 74 68 61 74 20 6f 66 20 74 68 65 20 5c 66 42 73 that of the \fBs
35c0: 70 72 69 6e 74 66 5c 66 52 20 72 6f 75 74 69 6e printf\fR routin
35d0: 65 20 77 68 65 72 65 20 74 68 65 20 74 77 6f 20 e where the two
35e0: 73 65 74 73 20 64 69 66 66 65 72 2e 20 57 68 65 sets differ. Whe
35f0: 6e 20 61 0a 63 6f 6e 76 65 72 73 69 6f 6e 20 73 n a.conversion s
3600: 70 65 63 69 66 69 65 72 20 70 61 73 73 65 64 20 pecifier passed
3610: 74 6f 20 5c 66 42 54 63 6c 5f 4f 62 6a 50 72 69 to \fBTcl_ObjPri
3620: 6e 74 66 5c 66 52 20 69 6e 63 6c 75 64 65 73 20 ntf\fR includes
3630: 61 20 70 72 65 63 69 73 69 6f 6e 2c 0a 74 68 65 a precision,.the
3640: 20 76 61 6c 75 65 20 69 73 20 74 61 6b 65 6e 20 value is taken
3650: 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 62 as a number of b
3660: 79 74 65 73 2c 20 61 73 20 5c 66 42 73 70 72 69 ytes, as \fBspri
3670: 6e 74 66 5c 66 52 20 64 6f 65 73 2c 20 61 6e 64 ntf\fR does, and
3680: 20 6e 6f 74 0a 61 73 20 61 20 6e 75 6d 62 65 72 not.as a number
3690: 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2c 20 of characters,
36a0: 61 73 20 5c 66 42 66 6f 72 6d 61 74 5c 66 52 20 as \fBformat\fR
36b0: 64 6f 65 73 2e 20 20 54 68 69 73 20 69 73 20 64 does. This is d
36c0: 6f 6e 65 20 6f 6e 20 74 68 65 0a 61 73 73 75 6d one on the.assum
36d0: 70 74 69 6f 6e 20 74 68 61 74 20 43 20 63 6f 64 ption that C cod
36e0: 65 20 69 73 20 6d 6f 72 65 20 6c 69 6b 65 6c 79 e is more likely
36f0: 20 74 6f 20 6b 6e 6f 77 20 68 6f 77 20 6d 61 6e to know how man
3700: 79 20 62 79 74 65 73 20 69 74 20 69 73 0a 70 61 y bytes it is.pa
3710: 73 73 69 6e 67 20 61 72 6f 75 6e 64 20 74 68 61 ssing around tha
3720: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
3730: 65 6e 63 6f 64 65 64 20 63 68 61 72 61 63 74 65 encoded characte
3740: 72 73 20 74 68 6f 73 65 20 62 79 74 65 73 20 68 rs those bytes h
3750: 61 70 70 65 6e 0a 74 6f 20 72 65 70 72 65 73 65 appen.to represe
3760: 6e 74 2e 20 20 54 68 65 20 76 61 72 69 61 62 6c nt. The variabl
3770: 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 e number of argu
3780: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 20 ments passed in
3790: 73 68 6f 75 6c 64 20 62 65 20 6f 66 0a 74 68 65 should be of.the
37a0: 20 74 79 70 65 73 20 74 68 61 74 20 77 6f 75 6c types that woul
37b0: 64 20 62 65 20 73 75 69 74 61 62 6c 65 20 66 6f d be suitable fo
37c0: 72 20 70 61 73 73 69 6e 67 20 74 6f 20 5c 66 42 r passing to \fB
37d0: 73 70 72 69 6e 74 66 5c 66 52 2e 20 20 4e 6f 74 sprintf\fR. Not
37e0: 65 20 69 6e 0a 74 68 69 73 20 65 78 61 6d 70 6c e in.this exampl
37f0: 65 20 75 73 61 67 65 2c 20 5c 66 49 78 5c 66 52 e usage, \fIx\fR
3800: 20 69 73 20 6f 66 20 74 79 70 65 20 5c 66 42 69 is of type \fBi
3810: 6e 74 5c 66 52 2e 0a 2e 50 50 0a 2e 43 53 0a 69 nt\fR...PP..CS.i
3820: 6e 74 20 78 20 3d 20 35 3b 0a 54 63 6c 5f 4f 62 nt x = 5;.Tcl_Ob
3830: 6a 20 2a 6f 62 6a 50 74 72 20 3d 20 5c 66 42 54 j *objPtr = \fBT
3840: 63 6c 5f 4f 62 6a 50 72 69 6e 74 66 5c 66 52 28 cl_ObjPrintf\fR(
3850: 22 56 61 6c 75 65 20 69 73 20 25 64 22 2c 20 78 "Value is %d", x
3860: 29 3b 0a 2e 43 45 0a 2e 50 50 0a 49 66 20 74 68 );..CE..PP.If th
3870: 65 20 76 61 6c 75 65 20 6f 66 20 5c 66 49 66 6f e value of \fIfo
3880: 72 6d 61 74 5c 66 52 20 63 6f 6e 74 61 69 6e 73 rmat\fR contains
3890: 20 69 6e 74 65 72 6e 61 6c 20 69 6e 63 6f 6e 73 internal incons
38a0: 69 73 74 65 6e 63 69 65 73 20 6f 72 20 69 6e 76 istencies or inv
38b0: 61 6c 69 64 0a 73 70 65 63 69 66 69 65 72 20 66 alid.specifier f
38c0: 6f 72 6d 61 74 73 2c 20 74 68 65 20 66 6f 72 6d ormats, the form
38d0: 61 74 74 65 64 20 73 74 72 69 6e 67 20 72 65 73 atted string res
38e0: 75 6c 74 20 70 72 6f 64 75 63 65 64 20 62 79 0a ult produced by.
38f0: 5c 66 42 54 63 6c 5f 4f 62 6a 50 72 69 6e 74 66 \fBTcl_ObjPrintf
3900: 5c 66 52 20 77 69 6c 6c 20 62 65 20 61 6e 20 65 \fR will be an e
3910: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 64 65 73 rror message des
3920: 63 72 69 62 69 6e 67 20 74 68 65 20 65 72 72 6f cribing the erro
3930: 72 2e 0a 49 74 20 69 73 20 69 6d 70 6f 73 73 69 r..It is impossi
3940: 62 6c 65 20 68 6f 77 65 76 65 72 20 74 6f 20 70 ble however to p
3950: 72 6f 76 69 64 65 20 72 75 6e 74 69 6d 65 20 70 rovide runtime p
3960: 72 6f 74 65 63 74 69 6f 6e 20 61 67 61 69 6e 73 rotection agains
3970: 74 0a 6d 69 73 6d 61 74 63 68 65 73 20 62 65 74 t.mismatches bet
3980: 77 65 65 6e 20 74 68 65 20 66 6f 72 6d 61 74 20 ween the format
3990: 61 6e 64 20 61 6e 79 20 73 75 62 73 65 71 75 65 and any subseque
39a0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 2e 0a 43 6f nt arguments..Co
39b0: 6d 70 69 6c 65 2d 74 69 6d 65 20 70 72 6f 74 65 mpile-time prote
39c0: 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 70 72 6f ction may be pro
39d0: 76 69 64 65 64 20 62 79 20 73 6f 6d 65 20 63 6f vided by some co
39e0: 6d 70 69 6c 65 72 73 2e 0a 2e 50 50 0a 5c 66 42 mpilers...PP.\fB
39f0: 54 63 6c 5f 41 70 70 65 6e 64 50 72 69 6e 74 66 Tcl_AppendPrintf
3a00: 54 6f 4f 62 6a 5c 66 52 20 69 73 20 61 6e 20 61 ToObj\fR is an a
3a10: 70 70 65 6e 64 69 6e 67 20 61 6c 74 65 72 6e 61 ppending alterna
3a20: 74 69 76 65 20 66 6f 72 6d 0a 6f 66 20 5c 66 42 tive form.of \fB
3a30: 54 63 6c 5f 4f 62 6a 50 72 69 6e 74 66 5c 66 52 Tcl_ObjPrintf\fR
3a40: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 61 6c with functional
3a50: 69 74 79 20 65 71 75 69 76 61 6c 65 6e 74 20 74 ity equivalent t
3a60: 6f 0a 2e 50 50 0a 2e 43 53 0a 54 63 6c 5f 4f 62 o..PP..CS.Tcl_Ob
3a70: 6a 20 2a 6e 65 77 50 74 72 20 3d 20 5c 66 42 54 j *newPtr = \fBT
3a80: 63 6c 5f 4f 62 6a 50 72 69 6e 74 66 5c 66 52 28 cl_ObjPrintf\fR(
3a90: 66 6f 72 6d 61 74 2c 20 2e 2e 2e 29 3b 0a 5c 66 format, ...);.\f
3aa0: 42 54 63 6c 5f 41 70 70 65 6e 64 4f 62 6a 54 6f BTcl_AppendObjTo
3ab0: 4f 62 6a 5c 66 52 28 6f 62 6a 50 74 72 2c 20 6e Obj\fR(objPtr, n
3ac0: 65 77 50 74 72 29 3b 0a 5c 66 42 54 63 6c 5f 44 ewPtr);.\fBTcl_D
3ad0: 65 63 72 52 65 66 43 6f 75 6e 74 5c 66 52 28 6e ecrRefCount\fR(n
3ae0: 65 77 50 74 72 29 3b 0a 2e 43 45 0a 2e 50 50 0a ewPtr);..CE..PP.
3af0: 62 75 74 20 77 69 74 68 20 67 72 65 61 74 65 72 but with greater
3b00: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 61 6e 64 convenience and
3b10: 20 65 66 66 69 63 69 65 6e 63 79 20 77 68 65 6e efficiency when
3b20: 20 74 68 65 20 61 70 70 65 6e 64 69 6e 67 0a 66 the appending.f
3b30: 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 69 73 20 unctionality is
3b40: 6e 65 65 64 65 64 2e 0a 2e 50 50 0a 54 68 65 20 needed...PP.The
3b50: 5c 66 42 54 63 6c 5f 53 65 74 4f 62 6a 4c 65 6e \fBTcl_SetObjLen
3b60: 67 74 68 5c 66 52 20 70 72 6f 63 65 64 75 72 65 gth\fR procedure
3b70: 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 65 6e changes the len
3b80: 67 74 68 20 6f 66 20 74 68 65 0a 73 74 72 69 6e gth of the.strin
3b90: 67 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20 5c g value of its \
3ba0: 66 49 6f 62 6a 50 74 72 5c 66 52 20 61 72 67 75 fIobjPtr\fR argu
3bb0: 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 5c 66 ment. If the \f
3bc0: 49 6e 65 77 4c 65 6e 67 74 68 5c 66 52 0a 61 72 InewLength\fR.ar
3bd0: 67 75 6d 65 6e 74 20 69 73 20 67 72 65 61 74 65 gument is greate
3be0: 72 20 74 68 61 6e 20 74 68 65 20 73 70 61 63 65 r than the space
3bf0: 20 61 6c 6c 6f 63 61 74 65 64 20 66 6f 72 20 74 allocated for t
3c00: 68 65 20 76 61 6c 75 65 27 73 0a 73 74 72 69 6e he value's.strin
3c10: 67 2c 20 74 68 65 6e 20 74 68 65 20 73 74 72 69 g, then the stri
3c20: 6e 67 20 73 70 61 63 65 20 69 73 20 72 65 61 6c ng space is real
3c30: 6c 6f 63 61 74 65 64 20 61 6e 64 20 74 68 65 20 located and the
3c40: 6f 6c 64 20 76 61 6c 75 65 0a 69 73 20 63 6f 70 old value.is cop
3c50: 69 65 64 20 74 6f 20 74 68 65 20 6e 65 77 20 73 ied to the new s
3c60: 70 61 63 65 3b 20 74 68 65 20 62 79 74 65 73 20 pace; the bytes
3c70: 62 65 74 77 65 65 6e 20 74 68 65 20 6f 6c 64 20 between the old
3c80: 6c 65 6e 67 74 68 20 6f 66 0a 74 68 65 20 73 74 length of.the st
3c90: 72 69 6e 67 20 61 6e 64 20 74 68 65 20 6e 65 77 ring and the new
3ca0: 20 6c 65 6e 67 74 68 20 6d 61 79 20 68 61 76 65 length may have
3cb0: 20 61 72 62 69 74 72 61 72 79 20 76 61 6c 75 65 arbitrary value
3cc0: 73 2e 0a 49 66 20 74 68 65 20 5c 66 49 6e 65 77 s..If the \fInew
3cd0: 4c 65 6e 67 74 68 5c 66 52 20 61 72 67 75 6d 65 Length\fR argume
3ce0: 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 nt is less than
3cf0: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 65 6e 67 the current leng
3d00: 74 68 0a 6f 66 20 74 68 65 20 76 61 6c 75 65 27 th.of the value'
3d10: 73 20 73 74 72 69 6e 67 2c 20 77 69 74 68 20 5c s string, with \
3d20: 66 49 6f 62 6a 50 74 72 2d 3e 6c 65 6e 67 74 68 fIobjPtr->length
3d30: 5c 66 52 20 69 73 20 72 65 64 75 63 65 64 20 77 \fR is reduced w
3d40: 69 74 68 6f 75 74 0a 72 65 61 6c 6c 6f 63 61 74 ithout.reallocat
3d50: 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 73 ing the string s
3d60: 70 61 63 65 3b 20 74 68 65 20 6f 72 69 67 69 6e pace; the origin
3d70: 61 6c 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a al allocated siz
3d80: 65 20 66 6f 72 20 74 68 65 0a 73 74 72 69 6e 67 e for the.string
3d90: 20 69 73 20 72 65 63 6f 72 64 65 64 20 69 6e 20 is recorded in
3da0: 74 68 65 20 76 61 6c 75 65 2c 20 73 6f 20 74 68 the value, so th
3db0: 61 74 20 74 68 65 20 73 74 72 69 6e 67 20 6c 65 at the string le
3dc0: 6e 67 74 68 20 63 61 6e 20 62 65 0a 65 6e 6c 61 ngth can be.enla
3dd0: 72 67 65 64 20 69 6e 20 61 20 73 75 62 73 65 71 rged in a subseq
3de0: 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5c 66 42 uent call to \fB
3df0: 54 63 6c 5f 53 65 74 4f 62 6a 4c 65 6e 67 74 68 Tcl_SetObjLength
3e00: 5c 66 52 20 77 69 74 68 6f 75 74 0a 72 65 61 6c \fR without.real
3e10: 6c 6f 63 61 74 69 6e 67 20 73 74 6f 72 61 67 65 locating storage
3e20: 2e 20 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 20 . In all cases
3e30: 5c 66 42 54 63 6c 5f 53 65 74 4f 62 6a 4c 65 6e \fBTcl_SetObjLen
3e40: 67 74 68 5c 66 52 20 6c 65 61 76 65 73 0a 61 20 gth\fR leaves.a
3e50: 6e 75 6c 6c 20 63 68 61 72 61 63 74 65 72 20 61 null character a
3e60: 74 20 5c 66 49 6f 62 6a 50 74 72 2d 3e 62 79 74 t \fIobjPtr->byt
3e70: 65 73 5b 6e 65 77 4c 65 6e 67 74 68 5d 5c 66 52 es[newLength]\fR
3e80: 2e 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 41 74 74 ...PP.\fBTcl_Att
3e90: 65 6d 70 74 53 65 74 4f 62 6a 4c 65 6e 67 74 68 emptSetObjLength
3ea0: 5c 66 52 20 69 73 20 69 64 65 6e 74 69 63 61 6c \fR is identical
3eb0: 20 69 6e 20 66 75 6e 63 74 69 6f 6e 20 74 6f 0a in function to.
3ec0: 5c 66 42 54 63 6c 5f 53 65 74 4f 62 6a 4c 65 6e \fBTcl_SetObjLen
3ed0: 67 74 68 5c 66 52 20 65 78 63 65 70 74 20 74 68 gth\fR except th
3ee0: 61 74 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 at if sufficient
3ef0: 20 6d 65 6d 6f 72 79 20 74 6f 20 73 61 74 69 73 memory to satis
3f00: 66 79 20 74 68 65 0a 72 65 71 75 65 73 74 20 63 fy the.request c
3f10: 61 6e 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 annot be allocat
3f20: 65 64 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 ed, it does not
3f30: 63 61 75 73 65 20 74 68 65 20 54 63 6c 20 69 6e cause the Tcl in
3f40: 74 65 72 70 72 65 74 65 72 20 74 6f 0a 5c 66 42 terpreter to.\fB
3f50: 70 61 6e 69 63 5c 66 52 2e 20 20 54 68 75 73 2c panic\fR. Thus,
3f60: 20 69 66 20 5c 66 49 6e 65 77 4c 65 6e 67 74 68 if \fInewLength
3f70: 5c 66 52 20 69 73 20 67 72 65 61 74 65 72 20 74 \fR is greater t
3f80: 68 61 6e 20 74 68 65 20 73 70 61 63 65 0a 61 6c han the space.al
3f90: 6c 6f 63 61 74 65 64 20 66 6f 72 20 74 68 65 20 located for the
3fa0: 76 61 6c 75 65 27 73 20 73 74 72 69 6e 67 2c 20 value's string,
3fb0: 61 6e 64 20 74 68 65 72 65 20 69 73 20 6e 6f 74 and there is not
3fc0: 20 65 6e 6f 75 67 68 20 6d 65 6d 6f 72 79 0a 61 enough memory.a
3fd0: 76 61 69 6c 61 62 6c 65 20 74 6f 20 73 61 74 69 vailable to sati
3fe0: 73 66 79 20 74 68 65 20 72 65 71 75 65 73 74 2c sfy the request,
3ff0: 20 5c 66 42 54 63 6c 5f 41 74 74 65 6d 70 74 53 \fBTcl_AttemptS
4000: 65 74 4f 62 6a 4c 65 6e 67 74 68 5c 66 52 20 77 etObjLength\fR w
4010: 69 6c 6c 20 74 61 6b 65 0a 6e 6f 20 61 63 74 69 ill take.no acti
4020: 6f 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 30 20 on and return 0
4030: 74 6f 20 69 6e 64 69 63 61 74 65 20 66 61 69 6c to indicate fail
4040: 75 72 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 ure. If there i
4050: 73 20 65 6e 6f 75 67 68 20 6d 65 6d 6f 72 79 0a s enough memory.
4060: 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 72 to satisfy the r
4070: 65 71 75 65 73 74 2c 20 5c 66 42 54 63 6c 5f 41 equest, \fBTcl_A
4080: 74 74 65 6d 70 74 53 65 74 4f 62 6a 4c 65 6e 67 ttemptSetObjLeng
4090: 74 68 5c 66 52 20 62 65 68 61 76 65 73 20 6a 75 th\fR behaves ju
40a0: 73 74 20 6c 69 6b 65 0a 5c 66 42 54 63 6c 5f 53 st like.\fBTcl_S
40b0: 65 74 4f 62 6a 4c 65 6e 67 74 68 5c 66 52 20 61 etObjLength\fR a
40c0: 6e 64 20 72 65 74 75 72 6e 73 20 31 20 74 6f 20 nd returns 1 to
40d0: 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73 indicate success
40e0: 2e 0a 2e 50 50 0a 54 68 65 20 5c 66 42 54 63 6c ...PP.The \fBTcl
40f0: 5f 43 6f 6e 63 61 74 4f 62 6a 5c 66 52 20 66 75 _ConcatObj\fR fu
4100: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 nction returns a
4110: 20 6e 65 77 20 73 74 72 69 6e 67 20 76 61 6c 75 new string valu
4120: 65 20 77 68 6f 73 65 0a 76 61 6c 75 65 20 69 73 e whose.value is
4130: 20 74 68 65 20 73 70 61 63 65 2d 73 65 70 61 72 the space-separ
4140: 61 74 65 64 20 63 6f 6e 63 61 74 65 6e 61 74 69 ated concatenati
4150: 6f 6e 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 on of the string
4160: 0a 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 73 .representations
4170: 20 6f 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 76 of all of the v
4180: 61 6c 75 65 73 20 69 6e 20 74 68 65 20 5c 66 49 alues in the \fI
4190: 6f 62 6a 76 5c 66 52 0a 61 72 72 61 79 2e 20 5c objv\fR.array. \
41a0: 66 42 54 63 6c 5f 43 6f 6e 63 61 74 4f 62 6a 5c fBTcl_ConcatObj\
41b0: 66 52 20 65 6c 69 6d 69 6e 61 74 65 73 20 6c 65 fR eliminates le
41c0: 61 64 69 6e 67 20 61 6e 64 20 74 72 61 69 6c 69 ading and traili
41d0: 6e 67 20 77 68 69 74 65 20 73 70 61 63 65 0a 61 ng white space.a
41e0: 73 20 69 74 20 63 6f 70 69 65 73 20 74 68 65 20 s it copies the
41f0: 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 string represent
4200: 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 5c 66 ations of the \f
4210: 49 6f 62 6a 76 5c 66 52 20 61 72 72 61 79 20 74 Iobjv\fR array t
4220: 6f 20 74 68 65 0a 72 65 73 75 6c 74 2e 20 49 66 o the.result. If
4230: 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 an element of t
4240: 68 65 20 5c 66 49 6f 62 6a 76 5c 66 52 20 61 72 he \fIobjv\fR ar
4250: 72 61 79 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 ray consists of
4260: 6e 6f 74 68 69 6e 67 20 62 75 74 0a 77 68 69 74 nothing but.whit
4270: 65 20 73 70 61 63 65 2c 20 74 68 65 6e 20 74 68 e space, then th
4280: 61 74 20 76 61 6c 75 65 20 69 73 20 69 67 6e 6f at value is igno
4290: 72 65 64 20 65 6e 74 69 72 65 6c 79 2e 20 54 68 red entirely. Th
42a0: 69 73 20 77 68 69 74 65 2d 73 70 61 63 65 0a 72 is white-space.r
42b0: 65 6d 6f 76 61 6c 20 77 61 73 20 61 64 64 65 64 emoval was added
42c0: 20 74 6f 20 6d 61 6b 65 20 74 68 65 20 6f 75 74 to make the out
42d0: 70 75 74 20 6f 66 20 74 68 65 20 5c 66 42 63 6f put of the \fBco
42e0: 6e 63 61 74 5c 66 52 20 63 6f 6d 6d 61 6e 64 0a ncat\fR command.
42f0: 63 6c 65 61 6e 65 72 2d 6c 6f 6f 6b 69 6e 67 2e cleaner-looking.
4300: 20 5c 66 42 54 63 6c 5f 43 6f 6e 63 61 74 4f 62 \fBTcl_ConcatOb
4310: 6a 5c 66 52 20 72 65 74 75 72 6e 73 20 61 20 70 j\fR returns a p
4320: 6f 69 6e 74 65 72 20 74 6f 20 61 0a 6e 65 77 6c ointer to a.newl
4330: 79 2d 63 72 65 61 74 65 64 20 76 61 6c 75 65 20 y-created value
4340: 77 68 6f 73 65 20 72 65 66 20 63 6f 75 6e 74 20 whose ref count
4350: 69 73 20 7a 65 72 6f 2e 0a 2e 53 48 20 22 52 45 is zero...SH "RE
4360: 46 45 52 45 4e 43 45 20 43 4f 55 4e 54 20 4d 41 FERENCE COUNT MA
4370: 4e 41 47 45 4d 45 4e 54 22 0a 2e 50 50 0a 5c 66 NAGEMENT"..PP.\f
4380: 42 54 63 6c 5f 4e 65 77 53 74 72 69 6e 67 4f 62 BTcl_NewStringOb
4390: 6a 5c 66 52 2c 20 5c 66 42 54 63 6c 5f 4e 65 77 j\fR, \fBTcl_New
43a0: 55 6e 69 63 6f 64 65 4f 62 6a 5c 66 52 2c 20 5c UnicodeObj\fR, \
43b0: 66 42 54 63 6c 5f 46 6f 72 6d 61 74 5c 66 52 2c fBTcl_Format\fR,
43c0: 0a 5c 66 42 54 63 6c 5f 4f 62 6a 50 72 69 6e 74 .\fBTcl_ObjPrint
43d0: 66 5c 66 52 2c 20 61 6e 64 20 5c 66 42 54 63 6c f\fR, and \fBTcl
43e0: 5f 43 6f 6e 63 61 74 4f 62 6a 5c 66 52 20 61 6c _ConcatObj\fR al
43f0: 77 61 79 73 20 72 65 74 75 72 6e 20 61 20 7a 65 ways return a ze
4400: 72 6f 2d 72 65 66 65 72 65 6e 63 65 0a 6f 62 6a ro-reference.obj
4410: 65 63 74 2c 20 6d 75 63 68 20 6c 69 6b 65 20 5c ect, much like \
4420: 66 42 54 63 6c 5f 4e 65 77 4f 62 6a 5c 66 52 2e fBTcl_NewObj\fR.
4430: 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 47 65 74 53 ..PP.\fBTcl_GetS
4440: 74 72 69 6e 67 46 72 6f 6d 4f 62 6a 5c 66 52 2c tringFromObj\fR,
4450: 20 5c 66 42 54 63 6c 5f 47 65 74 53 74 72 69 6e \fBTcl_GetStrin
4460: 67 5c 66 52 2c 20 5c 66 42 54 63 6c 5f 47 65 74 g\fR, \fBTcl_Get
4470: 55 6e 69 63 6f 64 65 46 72 6f 6d 4f 62 6a 5c 66 UnicodeFromObj\f
4480: 52 2c 0a 5c 66 42 54 63 6c 5f 47 65 74 55 6e 69 R,.\fBTcl_GetUni
4490: 63 6f 64 65 5c 66 52 2c 20 5c 66 42 54 63 6c 5f code\fR, \fBTcl_
44a0: 47 65 74 55 6e 69 43 68 61 72 5c 66 52 2c 20 5c GetUniChar\fR, \
44b0: 66 42 54 63 6c 5f 47 65 74 43 68 61 72 4c 65 6e fBTcl_GetCharLen
44c0: 67 74 68 5c 66 52 2c 20 61 6e 64 0a 5c 66 42 54 gth\fR, and.\fBT
44d0: 63 6c 5f 47 65 74 52 61 6e 67 65 5c 66 52 20 61 cl_GetRange\fR a
44e0: 6c 6c 20 6f 6e 6c 79 20 77 6f 72 6b 20 77 69 74 ll only work wit
44f0: 68 20 61 6e 20 65 78 69 73 74 69 6e 67 20 76 61 h an existing va
4500: 6c 75 65 3b 20 74 68 65 79 20 64 6f 20 6e 6f 74 lue; they do not
4510: 0a 6d 61 6e 69 70 75 6c 61 74 65 20 69 74 73 20 .manipulate its
4520: 72 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 20 reference count
4530: 69 6e 20 61 6e 79 20 77 61 79 2e 0a 2e 50 50 0a in any way...PP.
4540: 5c 66 42 54 63 6c 5f 53 65 74 53 74 72 69 6e 67 \fBTcl_SetString
4550: 4f 62 6a 5c 66 52 2c 20 5c 66 42 54 63 6c 5f 53 Obj\fR, \fBTcl_S
4560: 65 74 55 6e 69 63 6f 64 65 4f 62 6a 5c 66 52 2c etUnicodeObj\fR,
4570: 20 5c 66 42 54 63 6c 5f 41 70 70 65 6e 64 54 6f \fBTcl_AppendTo
4580: 4f 62 6a 5c 66 52 2c 0a 5c 66 42 54 63 6c 5f 41 Obj\fR,.\fBTcl_A
4590: 70 70 65 6e 64 55 6e 69 63 6f 64 65 54 6f 4f 62 ppendUnicodeToOb
45a0: 6a 5c 66 52 2c 20 5c 66 42 54 63 6c 5f 41 70 70 j\fR, \fBTcl_App
45b0: 65 6e 64 4f 62 6a 54 6f 4f 62 6a 5c 66 52 2c 0a endObjToObj\fR,.
45c0: 5c 66 42 54 63 6c 5f 41 70 70 65 6e 64 53 74 72 \fBTcl_AppendStr
45d0: 69 6e 67 73 54 6f 4f 62 6a 5c 66 52 2c 20 5c 66 ingsToObj\fR, \f
45e0: 42 54 63 6c 5f 41 70 70 65 6e 64 53 74 72 69 6e BTcl_AppendStrin
45f0: 67 73 54 6f 4f 62 6a 56 41 5c 66 52 2c 0a 5c 66 gsToObjVA\fR,.\f
4600: 42 54 63 6c 5f 41 70 70 65 6e 64 4c 69 6d 69 74 BTcl_AppendLimit
4610: 65 64 54 6f 4f 62 6a 5c 66 52 2c 20 5c 66 42 54 edToObj\fR, \fBT
4620: 63 6c 5f 41 70 70 65 6e 64 46 6f 72 6d 61 74 54 cl_AppendFormatT
4630: 6f 4f 62 6a 5c 66 52 2c 0a 5c 66 42 54 63 6c 5f oObj\fR,.\fBTcl_
4640: 41 70 70 65 6e 64 50 72 69 6e 74 66 54 6f 4f 62 AppendPrintfToOb
4650: 6a 5c 66 52 2c 20 5c 66 42 54 63 6c 5f 53 65 74 j\fR, \fBTcl_Set
4660: 4f 62 6a 4c 65 6e 67 74 68 5c 66 52 2c 20 61 6e ObjLength\fR, an
4670: 64 0a 5c 66 42 54 63 6c 5f 41 74 74 65 6d 70 74 d.\fBTcl_Attempt
4680: 53 65 74 4f 62 6a 4c 65 6e 67 74 68 5c 66 52 20 SetObjLength\fR
4690: 61 6e 64 20 72 65 71 75 69 72 65 20 74 68 65 69 and require thei
46a0: 72 20 5c 66 49 6f 62 6a 50 74 72 5c 66 52 20 74 r \fIobjPtr\fR t
46b0: 6f 20 62 65 20 61 6e 20 75 6e 73 68 61 72 65 64 o be an unshared
46c0: 0a 76 61 6c 75 65 20 28 69 2e 65 2c 20 61 20 72 .value (i.e, a r
46d0: 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 20 6e eference count n
46e0: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 31 29 20 61 o more than 1) a
46f0: 73 20 74 68 65 79 20 77 69 6c 6c 20 6d 6f 64 69 s they will modi
4700: 66 79 20 69 74 2e 0a 2e 50 50 0a 41 64 64 69 74 fy it...PP.Addit
4710: 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 ional arguments
4720: 74 6f 20 74 68 65 20 61 62 6f 76 65 20 66 75 6e to the above fun
4730: 63 74 69 6f 6e 73 20 28 74 68 65 20 5c 66 49 61 ctions (the \fIa
4740: 70 70 65 6e 64 4f 62 6a 50 74 72 5c 66 52 20 61 ppendObjPtr\fR a
4750: 72 67 75 6d 65 6e 74 0a 74 6f 20 5c 66 42 54 63 rgument.to \fBTc
4760: 6c 5f 41 70 70 65 6e 64 4f 62 6a 54 6f 4f 62 6a l_AppendObjToObj
4770: 5c 66 52 2c 20 76 61 6c 75 65 73 20 69 6e 20 74 \fR, values in t
4780: 68 65 20 5c 66 49 6f 62 6a 76 5c 66 52 20 61 72 he \fIobjv\fR ar
4790: 67 75 6d 65 6e 74 20 74 6f 0a 5c 66 42 54 63 6c gument to.\fBTcl
47a0: 5f 46 6f 72 6d 61 74 5c 66 52 2c 20 5c 66 42 54 _Format\fR, \fBT
47b0: 63 6c 5f 41 70 70 65 6e 64 46 6f 72 6d 61 74 54 cl_AppendFormatT
47c0: 6f 4f 62 6a 5c 66 52 2c 20 61 6e 64 20 5c 66 42 oObj\fR, and \fB
47d0: 54 63 6c 5f 43 6f 6e 63 61 74 4f 62 6a 5c 66 52 Tcl_ConcatObj\fR
47e0: 29 20 63 61 6e 0a 68 61 76 65 20 61 6e 79 20 72 ) can.have any r
47f0: 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 2c 20 eference count,
4800: 62 75 74 20 72 65 66 65 72 65 6e 63 65 20 63 6f but reference co
4810: 75 6e 74 73 20 6f 66 20 7a 65 72 6f 20 61 72 65 unts of zero are
4820: 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 not recommended
4830: 2e 0a 2e 50 50 0a 5c 66 42 54 63 6c 5f 46 6f 72 ...PP.\fBTcl_For
4840: 6d 61 74 5c 66 52 20 61 6e 64 20 5c 66 42 54 63 mat\fR and \fBTc
4850: 6c 5f 41 70 70 65 6e 64 46 6f 72 6d 61 74 54 6f l_AppendFormatTo
4860: 4f 62 6a 5c 66 52 20 6d 61 79 20 6d 6f 64 69 66 Obj\fR may modif
4870: 79 20 74 68 65 20 69 6e 74 65 72 70 72 65 74 65 y the interprete
4880: 72 0a 72 65 73 75 6c 74 2c 20 77 68 69 63 68 20 r.result, which
4890: 69 6e 76 6f 6c 76 65 73 20 63 68 61 6e 67 69 6e involves changin
48a0: 67 20 74 68 65 20 72 65 66 65 72 65 6e 63 65 20 g the reference
48b0: 63 6f 75 6e 74 20 6f 66 20 61 20 76 61 6c 75 65 count of a value
48c0: 2e 0a 0a 2e 53 48 20 22 53 45 45 20 41 4c 53 4f ....SH "SEE ALSO
48d0: 22 0a 54 63 6c 5f 4e 65 77 4f 62 6a 28 33 29 2c ".Tcl_NewObj(3),
48e0: 20 54 63 6c 5f 49 6e 63 72 52 65 66 43 6f 75 6e Tcl_IncrRefCoun
48f0: 74 28 33 29 2c 20 54 63 6c 5f 44 65 63 72 52 65 t(3), Tcl_DecrRe
4900: 66 43 6f 75 6e 74 28 33 29 2c 20 66 6f 72 6d 61 fCount(3), forma
4910: 74 28 6e 29 2c 20 73 70 72 69 6e 74 66 28 33 29 t(n), sprintf(3)
4920: 0a 2e 53 48 20 4b 45 59 57 4f 52 44 53 0a 61 70 ..SH KEYWORDS.ap
4930: 70 65 6e 64 2c 20 69 6e 74 65 72 6e 61 6c 20 72 pend, internal r
4940: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 76 epresentation, v
4950: 61 6c 75 65 2c 20 76 61 6c 75 65 20 74 79 70 65 alue, value type
4960: 2c 20 73 74 72 69 6e 67 20 76 61 6c 75 65 2c 0a , string value,.
4970: 73 74 72 69 6e 67 20 74 79 70 65 2c 20 73 74 72 string type, str
4980: 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
4990: 6f 6e 2c 20 63 6f 6e 63 61 74 2c 20 63 6f 6e 63 on, concat, conc
49a0: 61 74 65 6e 61 74 65 2c 20 75 6e 69 63 6f 64 65 atenate, unicode
49b0: 0a .