Tcl Source Code

Hex Artifact Content
Login

Artifact e7f6125d9499d6e12f52fb6f47c92d3753dc90f87a9bf10c6e4fbd1fa3828441:


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                                               .