1Tcl_StringObj(3) Tcl Library Procedures Tcl_StringObj(3)
2______________________________________________________________________________
6
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
18 #include <tcl.h>
19 Tcl_Obj *
21 Tcl_NewStringObj(bytes, length)
22 Tcl_Obj *
24 Tcl_NewUnicodeObj(unicode, numChars)
25 void
27 Tcl_SetStringObj(objPtr, bytes, length)
28 void
30 Tcl_SetUnicodeObj(objPtr, unicode, numChars)
31 char *
33 Tcl_GetStringFromObj(objPtr, lengthPtr)
34 char *
36 Tcl_GetString(objPtr)
37 Tcl_UniChar *
39 Tcl_GetUnicodeFromObj(objPtr, lengthPtr)
40 Tcl_UniChar *
42 Tcl_GetUnicode(objPtr)
43 Tcl_UniChar
45 Tcl_GetUniChar(objPtr, index)
46 int
48 Tcl_GetCharLength(objPtr)
49 Tcl_Obj *
51 Tcl_GetRange(objPtr, first, last)
52 void
54 Tcl_AppendToObj(objPtr, bytes, length)
55 void
57 Tcl_AppendUnicodeToObj(objPtr, unicode, numChars)
58 void
60 Tcl_AppendObjToObj(objPtr, appendObjPtr)
61 void
63 Tcl_AppendStringsToObj(objPtr, string, string, ... (char *) NULL)
64 void
66 Tcl_AppendStringsToObjVA(objPtr, argList)
67 void
69 Tcl_AppendLimitedToObj(objPtr, bytes, length, limit, ellipsis)
70 Tcl_Obj *
72 Tcl_Format(interp, format, objc, objv)
73 int
75 Tcl_AppendFormatToObj(interp, objPtr, format, objc, objv)
76 Tcl_Obj *
78 Tcl_ObjPrintf(format, ...)
79 void
81 Tcl_AppendPrintfToObj(objPtr, format, ...)
82 void
84 Tcl_SetObjLength(objPtr, newLength)
85 int
87 Tcl_AttemptSetObjLength(objPtr, newLength)
88 Tcl_Obj *
90 Tcl_ConcatObj(objc, objv)
91
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 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 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 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 int index (in) The index of the Unicode
139 character to return.
140 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 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 Tcl_Obj *objPtr (in/out) Points to a value to
152 manipulate.
153 Tcl_Obj *appendObjPtr (in) The value to append to
155 objPtr in Tcl_AppendObj‐
156 ToObj.
157 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 const char *string (in) Null-terminated string
165 value to append to
166 objPtr.
167 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 int limit (in) Maximum number of bytes
174 to be appended.
175 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 const char *format (in) Format control string
183 including % conversion
184 specifiers.
185 int objc (in) The number of elements to
187 format or concatenate.
188 Tcl_Obj *objv[] (in) The array of values to
190 format or concatenate.
191 int newLength (in) New length for the string
193 value of objPtr, not
194 including the final null
195 character.
196______________________________________________________________________________
197
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 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 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 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 Tcl_GetUniChar returns the index'th character in the value's Unicode
251 representation.
252 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 Tcl_GetCharLength returns the number of characters (as opposed to
259 bytes) in the string value.
260 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 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 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 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 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 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 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 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
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 Tcl_AppendFormatToObj is an appending alternative form of Tcl_Format
324 with functionality equivalent to:
325 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 but with greater convenience and efficiency when the appending func‐
333 tionality is needed.
334 Tcl_ObjPrintf serves as a replacement for the common sequence
336 char buf[SOME_SUITABLE_LENGTH];
338 sprintf(buf, format, ...);
339 Tcl_NewStringObj(buf, -1);
340 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 int x = 5;
355 Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x);
356 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 Tcl_AppendPrintfToObj is an appending alternative form of Tcl_ObjPrintf
365 with functionality equivalent to
366 Tcl_Obj *newPtr = Tcl_ObjPrintf(format, ...);
368 Tcl_AppendObjToObj(objPtr, newPtr);
369 Tcl_DecrRefCount(newPtr);
370 but with greater convenience and efficiency when the appending func‐
372 tionality is needed.
373 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 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 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
407 Tcl_NewObj(3), Tcl_IncrRefCount(3), Tcl_DecrRefCount(3), format(n),
408 sprintf(3)
409
411 append, internal representation, value, value type, string value,
412 string type, string representation, concat, concatenate, unicode
413Tcl 8.1 Tcl_StringObj(3)