1Tcl_StringObj(3)            Tcl Library Procedures            Tcl_StringObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_NewStringObj,   Tcl_NewUnicodeObj,   Tcl_SetStringObj,  Tcl_SetUni‐
9       codeObj,  Tcl_GetStringFromObj,  Tcl_GetString,  Tcl_GetUnicodeFromObj,
10       Tcl_GetUnicode,    Tcl_GetUniChar,   Tcl_GetCharLength,   Tcl_GetRange,
11       Tcl_AppendToObj,      Tcl_AppendUnicodeToObj,       Tcl_AppendObjToObj,
12       Tcl_AppendStringsToObj,   Tcl_AppendStringsToObjVA,  Tcl_AppendLimited‐
13       ToObj, Tcl_Format,  Tcl_AppendFormatToObj,  Tcl_ObjPrintf,  Tcl_Append‐
14       PrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj -
15       manipulate Tcl objects as strings
16

SYNOPSIS

18       #include <tcl.h>
19
20       Tcl_Obj *
21       Tcl_NewStringObj(bytes, length)
22
23       Tcl_Obj *
24       Tcl_NewUnicodeObj(unicode, numChars)
25
26       void
27       Tcl_SetStringObj(objPtr, bytes, length)
28
29       void
30       Tcl_SetUnicodeObj(objPtr, unicode, numChars)
31
32       char *
33       Tcl_GetStringFromObj(objPtr, lengthPtr)
34
35       char *
36       Tcl_GetString(objPtr)
37
38       Tcl_UniChar *
39       Tcl_GetUnicodeFromObj(objPtr, lengthPtr)
40
41       Tcl_UniChar *
42       Tcl_GetUnicode(objPtr)
43
44       Tcl_UniChar
45       Tcl_GetUniChar(objPtr, index)
46
47       int
48       Tcl_GetCharLength(objPtr)
49
50       Tcl_Obj *
51       Tcl_GetRange(objPtr, first, last)
52
53       void
54       Tcl_AppendToObj(objPtr, bytes, length)
55
56       void
57       Tcl_AppendUnicodeToObj(objPtr, unicode, numChars)
58
59       void
60       Tcl_AppendObjToObj(objPtr, appendObjPtr)
61
62       void
63       Tcl_AppendStringsToObj(objPtr, string, string, ... (char *) NULL)
64
65       void
66       Tcl_AppendStringsToObjVA(objPtr, argList)
67
68       void                                                                    │
69       Tcl_AppendLimitedToObj(objPtr, bytes, length, limit, ellipsis)          │
70
71       Tcl_Obj *                                                               │
72       Tcl_Format(interp, format, objc, objv)                                  │
73
74       int                                                                     │
75       Tcl_AppendFormatToObj(interp, objPtr, format, objc, objv)               │
76
77       Tcl_Obj *                                                               │
78       Tcl_ObjPrintf(format, ...)                                              │
79
80       int                                                                     │
81       Tcl_AppendPrintfToObj(objPtr, format, ...)                              │
82
83       void
84       Tcl_SetObjLength(objPtr, newLength)
85
86       int
87       Tcl_AttemptSetObjLength(objPtr, newLength)
88
89       Tcl_Obj *
90       Tcl_ConcatObj(objc, objv)
91

ARGUMENTS

93       const char *bytes (in)                        Points to the first  byte
94                                                     of     an     array    of
95                                                     UTF-8-encoded bytes  used
96                                                     to  set  or  append  to a
97                                                     string object.  This byte
98                                                     array  may contain embed‐
99                                                     ded    null    characters
100                                                     unless  numChars is nega‐
101                                                     tive.       (Applications
102                                                     needing null bytes should
103                                                     represent  them  as   the
104                                                     two-byte         sequence
105                                                     \700\600,             use
106                                                     Tcl_ExternalToUtf to con‐
107                                                     vert,  or  Tcl_NewByteAr‐
108                                                     rayObj if the string is a
109                                                     collection  of   uninter‐
110                                                     preted bytes.)
111
112       int length (in)                               The  number  of  bytes to
113                                                     copy from bytes when ini‐
114                                                     tializing,   setting,  or
115                                                     appending  to  a   string
116                                                     object.  If negative, all
117                                                     bytes  up  to  the  first
118                                                     null are used.
119
120       const Tcl_UniChar *unicode (in)               Points  to the first byte
121                                                     of an  array  of  Unicode
122                                                     characters used to set or
123                                                     append   to   a    string
124                                                     object.   This byte array
125                                                     may contain embedded null
126                                                     characters   unless  num‐
127                                                     Chars is negative.
128
129       int numChars (in)                             The  number  of   Unicode
130                                                     characters  to  copy from
131                                                     unicode  when  initializ‐
132                                                     ing,  setting, or append‐
133                                                     ing to a  string  object.
134                                                     If  negative, all charac‐
135                                                     ters up to the first null
136                                                     character are used.
137
138       int index (in)                                The  index of the Unicode
139                                                     character to return.
140
141       int first (in)                                The index  of  the  first
142                                                     Unicode  character in the
143                                                     Unicode   range   to   be
144                                                     returned as a new object.
145
146       int last (in)                                 The  index  of  the  last
147                                                     Unicode character in  the
148                                                     Unicode   range   to   be
149                                                     returned as a new object.
150
151       Tcl_Obj *objPtr (in/out)                      Points to  an  object  to
152                                                     manipulate.
153
154       Tcl_Obj *appendObjPtr (in)                    The  object  to append to
155                                                     objPtr in  Tcl_AppendObj‐
156                                                     ToObj.
157
158       int *lengthPtr (out)                          If non-NULL, the location
159                                                     where   Tcl_GetStringFro‐
160                                                     mObj   will   store   the
161                                                     length  of  an   object's
162                                                     string representation.
163
164       const char *string (in)                       Null-terminated    string
165                                                     value   to   append    to
166                                                     objPtr.
167
168       va_list argList (in)                          An  argument  list  which
169                                                     must   have   been   ini‐
170                                                     tialised  using va_start,
171                                                     and cleared using va_end.
172
173       int limit (in)                                Maximum number  of  bytes
174                                                     to be appended.
175
176       const char *ellipsis (in)                     Suffix to append when the
177                                                     limit  leads  to   string
178                                                     truncation.   If  NULL is
179                                                     passed  then  the  suffix
180                                                     "..." is used.
181
182       const char *format (in)                       Format   control   string
183                                                     including  %   conversion
184                                                     specifiers.
185
186       int objc (in)                                 The number of elements to
187                                                     format or concatenate.
188
189       Tcl_Obj *objv[] (in)                          The array of  objects  to
190                                                     format or concatenate.
191
192       int newLength (in)                            New length for the string
193                                                     value  of   objPtr,   not
194                                                     including  the final null
195                                                     character.
196_________________________________________________________________
197
198

DESCRIPTION

200       The procedures described in this manual entry allow Tcl objects  to  be
201       manipulated  as string values.  They use the internal representation of
202       the object to store additional information to make the string manipula‐
203       tions  more  efficient.   In  particular,  they make a series of append
204       operations efficient by allocating extra storage space for  the  string
205       so  that it does not have to be copied for each append.  Also, indexing
206       and length computations are optimized because the Unicode string repre‐
207       sentation   is  calculated  and  cached  as  needed.   When  using  the
208       Tcl_Append* family of functions where the interpreter's result  is  the
209       object being appended to, it is important to call Tcl_ResetResult first
210       to ensure you are not unintentionally appending to existing data in the
211       result object.
212
213       Tcl_NewStringObj  and Tcl_SetStringObj create a new object or modify an
214       existing object to hold a copy of the string given by bytes and length.
215       Tcl_NewUnicodeObj  and  Tcl_SetUnicodeObj create a new object or modify
216       an existing object to hold a copy of the Unicode string given  by  uni‐
217       code  and  numChars.   Tcl_NewStringObj  and Tcl_NewUnicodeObj return a
218       pointer to a newly created object with reference count zero.  All  four
219       procedures  set  the  object  to  hold  a copy of the specified string.
220       Tcl_SetStringObj and Tcl_SetUnicodeObj free any old string  representa‐
221       tion as well as any old internal representation of the object.
222
223       Tcl_GetStringFromObj and Tcl_GetString return an object's string repre‐
224       sentation.  This is  given  by  the  returned  byte  pointer  and  (for
225       Tcl_GetStringFromObj)  length,  which  is  stored in lengthPtr if it is
226       non-NULL.  If the object's UTF string representation  is  invalid  (its
227       byte  pointer  is  NULL), the string representation is regenerated from
228       the object's internal representation.  The storage  referenced  by  the
229       returned  byte  pointer  is  owned by the object manager.  It is passed
230       back as a writable pointer so that extension author creating their  own
231       Tcl_ObjType will be able to modify the string representation within the
232       Tcl_UpdateStringProc of their Tcl_ObjType.   Except  for  that  limited
233       purpose,  the pointer returned by Tcl_GetStringFromObj or Tcl_GetString
234       should be treated as read-only.  It is recommended that this pointer be
235       assigned  to a (const char *) variable.  Even in the limited situations
236       where writing to this pointer is acceptable, one should  take  care  to
237       respect  the copy-on-write semantics required by Tcl_Obj's, with appro‐
238       priate calls to Tcl_IsShared and Tcl_DuplicateObj prior to any in-place
239       modification of the string representation.  The procedure Tcl_GetString
240       is used in the common case where the caller does not need the length of
241       the string representation.
242
243       Tcl_GetUnicodeFromObj  and Tcl_GetUnicode return an object's value as a
244       Unicode string.  This  is  given  by  the  returned  pointer  and  (for
245       Tcl_GetUnicodeFromObj)  length,  which  is stored in lengthPtr if it is
246       non-NULL.  The storage referenced by the returned byte pointer is owned
247       by  the  object  manager and should not be modified by the caller.  The
248       procedure Tcl_GetUnicode is used in the common case  where  the  caller
249       does not need the length of the unicode string representation.
250
251       Tcl_GetUniChar  returns  the index'th character in the object's Unicode
252       representation.
253
254       Tcl_GetRange returns a newly created object comprised of the characters
255       between  first and last (inclusive) in the object's Unicode representa‐
256       tion.  If the object's Unicode representation is invalid,  the  Unicode
257       representation is regenerated from the object's string representation.
258
259       Tcl_GetCharLength  returns  the  number  of  characters  (as opposed to
260       bytes) in the string object.
261
262       Tcl_AppendToObj appends the data given  by  bytes  and  length  to  the
263       string representation of the object specified by objPtr.  If the object
264       has an invalid string representation, then an attempt is made  to  con‐
265       vert  bytes is to the Unicode format.  If the conversion is successful,
266       then the converted form of bytes is appended to  the  object's  Unicode
267       representation.   Otherwise,  the  object's  Unicode  representation is
268       invalidated and converted to the UTF format, and bytes is  appended  to
269       the object's new string representation.
270
271       Tcl_AppendUnicodeToObj  appends the Unicode string given by unicode and
272       numChars to the object specified by  objPtr.   If  the  object  has  an
273       invalid  Unicode  representation,  then unicode is converted to the UTF
274       format and appended to the object's string representation.  Appends are
275       optimized to handle repeated appends relatively efficiently (it overal‐
276       locates the string or Unicode space to avoid repeated reallocations and
277       copies of object's string value).
278
279       Tcl_AppendObjToObj  is  similar  to Tcl_AppendToObj, but it appends the
280       string or Unicode value (whichever exists and  is  best  suited  to  be
281       appended to objPtr) of appendObjPtr to objPtr.
282
283       Tcl_AppendStringsToObj is similar to Tcl_AppendToObj except that it can
284       be passed more than one value to append and each value must be a  null-
285       terminated  string  (i.e.  none of the values may contain internal null
286       characters).  Any number of string arguments may be provided,  but  the
287       last argument must be a NULL pointer to indicate the end of the list.
288
289       Tcl_AppendStringsToObjVA  is  the same as Tcl_AppendStringsToObj except
290       that instead of taking a variable number of arguments it takes an argu‐
291       ment list.
292
293       Tcl_AppendLimitedToObj  is  similar  to  Tcl_AppendToObj except that it │
294       imposes a limit on how many bytes are appended.  This can be handy when │
295       the string to be appended might be very large, but the value being con‐ │
296       structed should not be allowed to grow without bound. A common usage is │
297       when constructing an error message, where the end result should be kept │
298       short enough to be read.  Bytes from bytes are appended to objPtr,  but │
299       no  more  than  limit bytes total are to be appended. If the limit pre‐ │
300       vents all length bytes that are available from being appended, then the │
301       appending  is  done so that the last bytes appended are from the string │
302       ellipsis. This allows for an indication of the truncation to be left in │
303       the string.  When length is -1, all bytes up to the first zero byte are │
304       appended, subject to the limit. When  ellipsis  is  NULL,  the  default │
305       string ... is used. When ellipsis is non-NULL, it must point to a zero- │
306       byte-terminated string in Tcl's internal UTF encoding.  The  number  of │
307       bytes  appended  can  be  less than the lesser of length and limit when │
308       appending fewer bytes is necessary  to  append  only  whole  multi-byte │
309       characters.                                                             │
310
311       Tcl_Format  is  the  C-level interface to the engine of the format com‐ │
312       mand.  The actual command procedure for format is little more than      │
313              Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2);      │
314       The objc Tcl_Obj values in objv are formatted into a  string  according │
315       to the conversion specification in format argument, following the docu‐ │
316       mentation for the format command.  The resulting  formatted  string  is │
317       converted to a new Tcl_Obj with refcount of zero and returned.  If some │
318       error happens during  production  of  the  formatted  string,  NULL  is │
319       returned, and an error message is recorded in interp, if interp is non- │
320       NULL.                                                                   │
321
322       Tcl_AppendFormatToObj is an appending alternative  form  of  Tcl_Format 
323       with functionality equivalent to                                        │
324              Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv);        │
325              if (newPtr == NULL) return TCL_ERROR;                            │
326              Tcl_AppendObjToObj(objPtr, newPtr);                              │
327              return TCL_OK;                                                   │
328       but  with  greater  convenience and efficiency when the appending func‐ │
329       tionality is needed.                                                    │
330
331       Tcl_ObjPrintf serves as a replacement for the common sequence           │
332              char buf[SOME_SUITABLE_LENGTH];                                  │
333              sprintf(buf, format, ...);                                       │
334              Tcl_NewStringObj(buf, -1);                                       │
335       but with greater  convenience  and  no  need  to  determine  SOME_SUIT‐ 
336       ABLE_LENGTH.  The  formatting  is  done  with  the same core formatting │
337       engine used by Tcl_Format.  This means the set of supported  conversion │
338       specifiers  is  that  of the format command and not that of the sprintf 
339       routine where the two sets differ. When a conversion  specifier  passed │
340       to  Tcl_ObjPrintf  includes a precision, the value is taken as a number │
341       of bytes, as sprintf does, and not as a number of characters, as format 
342       does.   This  is  done  on the assumption that C code is more likely to │
343       know how many bytes it is passing around than  the  number  of  encoded │
344       characters  those  bytes  happen  to represent.  The variable number of │
345       arguments passed in should be of the types that would be  suitable  for │
346       passing to sprintf.  Note in this example usage, x is of type long.     │
347              long x = 5;                                                      │
348              Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x);               │
349       If  the  value  of  format contains internal inconsistencies or invalid │
350       specifier  formats,   the   formatted   string   result   produced   by │
351       Tcl_ObjPrintf will be an error message describing the error.            │
352
353       Tcl_AppendPrintfToObj is an appending alternative form of Tcl_ObjPrintf 
354       with functionality equivalent to                                        │
355              Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...));          │
356       but with greater convenience and efficiency when  the  appending  func‐ │
357       tionality is needed.
358
359       The  Tcl_SetObjLength  procedure changes the length of the string value
360       of its objPtr argument.  If the newLength argument is greater than  the
361       space allocated for the object's string, then the string space is real‐
362       located and the old value is copied to the new space; the bytes between
363       the old length of the string and the new length may have arbitrary val‐
364       ues.  If the newLength argument is less than the current length of  the
365       object's  string,  with  objPtr->length is reduced without reallocating
366       the string space;  the  original  allocated  size  for  the  string  is
367       recorded  in the object, so that the string length can be enlarged in a
368       subsequent call to Tcl_SetObjLength without reallocating  storage.   In
369       all    cases    Tcl_SetObjLength    leaves    a   null   character   at
370       objPtr->bytes[newLength].
371
372       Tcl_AttemptSetObjLength is identical in  function  to  Tcl_SetObjLength
373       except that if sufficient memory to satisfy the request cannot be allo‐
374       cated, it does not cause  the  Tcl  interpreter  to  panic.   Thus,  if
375       newLength  is greater than the space allocated for the object's string,
376       and there is not  enough  memory  available  to  satisfy  the  request,
377       Tcl_AttemptSetObjLength  will  take  no action and return 0 to indicate
378       failure.   If  there  is  enough  memory  to   satisfy   the   request,
379       Tcl_AttemptSetObjLength  behaves just like Tcl_SetObjLength and returns
380       1 to indicate success.
381
382       The Tcl_ConcatObj function returns a new string object whose  value  is
383       the  space-separated concatenation of the string representations of all
384       of the objects in the objv array. Tcl_ConcatObj eliminates leading  and
385       trailing  white  space  as  it copies the string representations of the
386       objv array to the result. If an element of the objv array  consists  of
387       nothing  but  white  space,  then that object is ignored entirely. This
388       white-space removal was added to make the output of the concat  command
389       cleaner-looking.  Tcl_ConcatObj  returns  a  pointer to a newly-created
390       object whose ref count is zero.
391
392

SEE ALSO

394       Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount, format, sprintf
395
396

KEYWORDS

398       append, internal representation, object, object  type,  string  object,
399       string type, string representation, concat, concatenate, unicode
400
401
402
403Tcl                                   8.1                     Tcl_StringObj(3)
Impressum