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 objects 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 int │
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 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 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 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 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 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 object.
145 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 Tcl_Obj *objPtr (in/out) Points to an object to
152 manipulate.
153 Tcl_Obj *appendObjPtr (in) The object 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 an object'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 ini‐
170 tialised using va_start,
171 and 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 objects 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
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 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 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 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 Tcl_GetUniChar returns the index'th character in the object's Unicode
252 representation.
253 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 Tcl_GetCharLength returns the number of characters (as opposed to
260 bytes) in the string object.
261 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 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 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 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 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 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 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 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 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 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 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 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 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
394 Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount, format, sprintf
395
398 append, internal representation, object, object type, string object,
399 string type, string representation, concat, concatenate, unicode
400Tcl 8.1 Tcl_StringObj(3)