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,  Tcl_Ap‐
12       pendStringsToObj,   Tcl_AppendStringsToObjVA,   Tcl_AppendLimitedToObj,
13       Tcl_Format,  Tcl_AppendFormatToObj,   Tcl_ObjPrintf,   Tcl_AppendPrint‐
14       fToObj,  Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj - ma‐
15       nipulate Tcl values 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       void
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 UTF-8-en‐
95                                                     coded bytes used  to  set
96                                                     or  append  to  a  string
97                                                     value.  This  byte  array
98                                                     may contain embedded null
99                                                     characters  unless   num‐
100                                                     Chars  is negative.  (Ap‐
101                                                     plications  needing  null
102                                                     bytes   should  represent
103                                                     them as the two-byte  se‐
104                                                     quence    \300\200,   use
105                                                     Tcl_ExternalToUtf to con‐
106                                                     vert,  or  Tcl_NewByteAr‐
107                                                     rayObj if the string is a
108                                                     collection   of  uninter‐
109                                                     preted bytes.)
110
111       int length (in)                               The number  of  bytes  to
112                                                     copy from bytes when ini‐
113                                                     tializing,  setting,   or
114                                                     appending   to  a  string
115                                                     value.  If negative,  all
116                                                     bytes  up  to  the  first
117                                                     null are used.
118
119       const Tcl_UniChar *unicode (in)               Points to the first  byte
120                                                     of  an  array  of Unicode
121                                                     characters used to set or
122                                                     append to a string value.
123                                                     This byte array may  con‐
124                                                     tain  embedded null char‐
125                                                     acters unless numChars is
126                                                     negative.
127
128       int numChars (in)                             The   number  of  Unicode
129                                                     characters to  copy  from
130                                                     unicode  when  initializ‐
131                                                     ing, setting, or  append‐
132                                                     ing  to  a  string value.
133                                                     If negative, all  charac‐
134                                                     ters up to the first null
135                                                     character are used.
136
137       int index (in)                                The index of the  Unicode
138                                                     character to return.
139
140       int first (in)                                The  index  of  the first
141                                                     Unicode character in  the
142                                                     Unicode  range  to be re‐
143                                                     turned as a new value.
144
145       int last (in)                                 The  index  of  the  last
146                                                     Unicode  character in the
147                                                     Unicode range to  be  re‐
148                                                     turned as a new value.
149
150       Tcl_Obj *objPtr (in/out)                      Points  to a value to ma‐
151                                                     nipulate.
152
153       Tcl_Obj *appendObjPtr (in)                    The value  to  append  to
154                                                     objPtr  in Tcl_AppendObj‐
155                                                     ToObj.
156
157       int *lengthPtr (out)                          If non-NULL, the location
158                                                     where   Tcl_GetStringFro‐
159                                                     mObj   will   store   the
160                                                     length   of   a   value's
161                                                     string representation.
162
163       const char *string (in)                       Null-terminated    string
164                                                     value  to  append  to ob‐
165                                                     jPtr.
166
167       va_list argList (in)                          An  argument  list  which
168                                                     must  have  been initial‐
169                                                     ized using va_start,  and
170                                                     cleared using va_end.
171
172       int limit (in)                                Maximum  number  of bytes
173                                                     to be appended.
174
175       const char *ellipsis (in)                     Suffix to append when the
176                                                     limit   leads  to  string
177                                                     truncation.  If  NULL  is
178                                                     passed  then  the  suffix
179                                                     “...”  is used.
180
181       const char *format (in)                       Format control string in‐
182                                                     cluding    %   conversion
183                                                     specifiers.
184
185       int objc (in)                                 The number of elements to
186                                                     format or concatenate.
187
188       Tcl_Obj *objv[] (in)                          The  array  of  values to
189                                                     format or concatenate.
190
191       int newLength (in)                            New length for the string
192                                                     value  of objPtr, not in‐
193                                                     cluding  the  final  null
194                                                     character.
195______________________________________________________________________________
196

DESCRIPTION

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

SEE ALSO

407       Tcl_NewObj(3),  Tcl_IncrRefCount(3),  Tcl_DecrRefCount(3),   format(n),
408       sprintf(3)
409

KEYWORDS

411       append,  internal  representation,  value,  value  type,  string value,
412       string type, string representation, concat, concatenate, unicode
413
414
415
416Tcl                                   8.1                     Tcl_StringObj(3)
Impressum