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 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
95                                                     UTF-8-encoded bytes  used
96                                                     to  set  or  append  to a
97                                                     string value.  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                                                     \300\200,             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                                                     value.   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 value.
124                                                     This  byte array may con‐
125                                                     tain embedded null  char‐
126                                                     acters unless numChars is
127                                                     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  value.
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 value.
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 value.
150
151       Tcl_Obj *objPtr (in/out)                      Points  to  a  value   to
152                                                     manipulate.
153
154       Tcl_Obj *appendObjPtr (in)                    The  value  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   a   value'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  initial‐
170                                                     ized  using va_start, and
171                                                     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  values  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

DESCRIPTION

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