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_AppendStringsToObj,
12 Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength,
13 Tcl_ConcatObj, Tcl_AttemptSetObjLength - manipulate Tcl objects as
14 strings
15
17 #include <tcl.h>
18 Tcl_Obj *
20 Tcl_NewStringObj(bytes, length)
21 Tcl_Obj *
23 Tcl_NewUnicodeObj(unicode, numChars)
24 void
26 Tcl_SetStringObj(objPtr, bytes, length)
27 void
29 Tcl_SetUnicodeObj(objPtr, unicode, numChars)
30 char *
32 Tcl_GetStringFromObj(objPtr, lengthPtr)
33 char *
35 Tcl_GetString(objPtr)
36 Tcl_UniChar *
38 Tcl_GetUnicodeFromObj(objPtr, lengthPtr)
39 Tcl_UniChar *
41 Tcl_GetUnicode(objPtr)
42 Tcl_UniChar
44 Tcl_GetUniChar(objPtr, index)
45 int
47 Tcl_GetCharLength(objPtr)
48 Tcl_Obj *
50 Tcl_GetRange(objPtr, first, last)
51 void
53 Tcl_AppendToObj(objPtr, bytes, length)
54 void
56 Tcl_AppendUnicodeToObj(objPtr, unicode, numChars)
57 void
59 Tcl_AppendObjToObj(objPtr, appendObjPtr)
60 void
62 Tcl_AppendStringsToObj(objPtr, string, string, ... (char *) NULL)
63 void
65 Tcl_AppendStringsToObjVA(objPtr, argList)
66 void
68 Tcl_SetObjLength(objPtr, newLength)
69 int
71 Tcl_AttemptSetObjLength(objPtr, newLength)
72 Tcl_Obj *
74 Tcl_ConcatObj(objc, objv)
75
77 CONST char *bytes (in) Points to the first byte │
78 of an array of │
79 UTF-8-encoded bytes used │
80 to set or append to a │
81 string object. This byte │
82 array should not contain │
83 embedded null bytes │
84 unless length is nega‐ │
85 tive. (Applications │
86 needing null bytes should │
87 represent them as the │
88 two-byte sequence │
89 \700\600, use │
90 Tcl_ExternalToUtf to con‐ │
91 vert, or Tcl_NewByteAr‐ │
92 rayObj if the string is a │
93 collection of uninter‐ │
94 preted bytes.)
95 int length (in) The number of bytes to
97 copy from bytes when ini‐
98 tializing, setting, or
99 appending to a string
100 object. If negative, all
101 bytes up to the first
102 null are used.
103 CONST Tcl_UniChar *unicode (in) Points to the first byte
105 of an array of Unicode
106 characters used to set or
107 append to a string
108 object. This byte array
109 may contain embedded null
110 characters unless num‐
111 Chars is negative.
112 int numChars (in) The number of Unicode
114 characters to copy from
115 unicode when initializ‐
116 ing, setting, or append‐
117 ing to a string object.
118 If negative, all charac‐
119 ters up to the first null
120 character are used.
121 int index (in) The index of the Unicode
123 character to return.
124 int first (in) The index of the first
126 Unicode character in the
127 Unicode range to be
128 returned as a new object.
129 int last (in) The index of the last
131 Unicode character in the
132 Unicode range to be
133 returned as a new object.
134 Tcl_Obj *objPtr (in/out) Points to an object to
136 manipulate.
137 Tcl_Obj *appendObjPtr (in) The object to append to
139 objPtr in Tcl_AppendObj‐
140 ToObj.
141 int *lengthPtr (out) If non-NULL, the location
143 where Tcl_GetStringFro‐
144 mObj will store the the
145 length of an object's
146 string representation.
147 CONST char *string (in) Null-terminated string
149 value to append to
150 objPtr.
151 va_list argList (in) An argument list which
153 must have been ini‐
154 tialised using
155 TCL_VARARGS_START, and
156 cleared using va_end.
157 int newLength (in) New length for the string
159 value of objPtr, not
160 including the final null
161 character.
162 int objc (in) The number of elements to
164 concatenate.
165 Tcl_Obj *objv[] (in) The array of objects to
167 concatenate.
168_________________________________________________________________
169
172 The procedures described in this manual entry allow Tcl objects to be
173 manipulated as string values. They use the internal representation of
174 the object to store additional information to make the string manipula‐
175 tions more efficient. In particular, they make a series of append
176 operations efficient by allocating extra storage space for the string
177 so that it doesn't have to be copied for each append. Also, indexing
178 and length computations are optimized because the Unicode string repre‐
179 sentation is calculated and cached as needed. When using the
180 Tcl_Append* family of functions where the interpreter's result is the
181 object being appended to, it is important to call Tcl_ResetResult first
182 to ensure you are not unintentionally appending to existing data in the
183 result object.
184 Tcl_NewStringObj and Tcl_SetStringObj create a new object or modify an
186 existing object to hold a copy of the string given by bytes and length.
187 Tcl_NewUnicodeObj and Tcl_SetUnicodeObj create a new object or modify
188 an existing object to hold a copy of the Unicode string given by uni‐
189 code and numChars. Tcl_NewStringObj and Tcl_NewUnicodeObj return a
190 pointer to a newly created object with reference count zero. All four
191 procedures set the object to hold a copy of the specified string.
192 Tcl_SetStringObj and Tcl_SetUnicodeObj free any old string representa‐
193 tion as well as any old internal representation of the object.
194 Tcl_GetStringFromObj and Tcl_GetString return an object's string repre‐
196 sentation. This is given by the returned byte pointer and (for
197 Tcl_GetStringFromObj) length, which is stored in lengthPtr if it is
198 non-NULL. If the object's UTF string representation is invalid (its
199 byte pointer is NULL), the string representation is regenerated from
200 the object's internal representation. The storage referenced by the
201 returned byte pointer is owned by the object manager. It is passed
202 back as a writable pointer so that extension author creating their own
203 Tcl_ObjType will be able to modify the string representation within the
204 Tcl_UpdateStringProc of their Tcl_ObjType. Except for that limited
205 purpose, the pointer returned by Tcl_GetStringFromObj or Tcl_GetString
206 should be treated as read-only. It is recommended that this pointer be
207 assigned to a (CONST char *) variable. Even in the limited situations
208 where writing to this pointer is acceptable, one should take care to
209 respect the copy-on-write semantics required by Tcl_Obj's, with appro‐
210 priate calls to Tcl_IsShared and Tcl_DuplicateObj prior to any in-place
211 modification of the string representation. The procedure Tcl_GetString
212 is used in the common case where the caller does not need the length of
213 the string representation.
214 Tcl_GetUnicodeFromObj and Tcl_GetUnicode return an object's value as a
216 Unicode string. This is given by the returned pointer and (for
217 Tcl_GetUnicodeFromObj) length, which is stored in lengthPtr if it is
218 non-NULL. The storage referenced by the returned byte pointer is owned
219 by the object manager and should not be modified by the caller. The
220 procedure Tcl_GetUnicode is used in the common case where the caller
221 does not need the length of the unicode string representation.
222 Tcl_GetUniChar returns the index'th character in the object's Unicode
224 representation.
225 Tcl_GetRange returns a newly created object comprised of the characters
227 between first and last (inclusive) in the object's Unicode representa‐
228 tion. If the object's Unicode representation is invalid, the Unicode
229 representation is regenerated from the object's string representation.
230 Tcl_GetCharLength returns the number of characters (as opposed to
232 bytes) in the string object.
233 Tcl_AppendToObj appends the data given by bytes and length to the
235 string representation of the object specified by objPtr. If the object
236 has an invalid string representation, then an attempt is made to con‐
237 vert bytes is to the Unicode format. If the conversion is successful,
238 then the converted form of bytes is appended to the object's Unicode
239 representation. Otherwise, the object's Unicode representation is
240 invalidated and converted to the UTF format, and bytes is appended to
241 the object's new string representation.
242 Tcl_AppendUnicodeToObj appends the Unicode string given by unicode and
244 numChars to the object specified by objPtr. If the object has an
245 invalid Unicode representation, then unicode is converted to the UTF
246 format and appended to the object's string representation. Appends are
247 optimized to handle repeated appends relatively efficiently (it overal‐
248 locates the string or Unicode space to avoid repeated reallocations and
249 copies of object's string value).
250 Tcl_AppendObjToObj is similar to Tcl_AppendToObj, but it appends the
252 string or Unicode value (whichever exists and is best suited to be
253 appended to objPtr) of appendObjPtr to objPtr.
254 Tcl_AppendStringsToObj is similar to Tcl_AppendToObj except that it can
256 be passed more than one value to append and each value must be a null-
257 terminated string (i.e. none of the values may contain internal null
258 characters). Any number of string arguments may be provided, but the
259 last argument must be a NULL pointer to indicate the end of the list.
260 Tcl_AppendStringsToObjVA is the same as Tcl_AppendStringsToObj except
262 that instead of taking a variable number of arguments it takes an argu‐
263 ment list.
264 The Tcl_SetObjLength procedure changes the length of the string value
266 of its objPtr argument. If the newLength argument is greater than the
267 space allocated for the object's string, then the string space is real‐
268 located and the old value is copied to the new space; the bytes between
269 the old length of the string and the new length may have arbitrary val‐
270 ues. If the newLength argument is less than the current length of the
271 object's string, with objPtr->length is reduced without reallocating
272 the string space; the original allocated size for the string is
273 recorded in the object, so that the string length can be enlarged in a
274 subsequent call to Tcl_SetObjLength without reallocating storage. In
275 all cases Tcl_SetObjLength leaves a null character at
276 objPtr->bytes[newLength].
277 Tcl_AttemptSetObjLength is identical in function to Tcl_SetObjLength
279 except that if sufficient memory to satisfy the request cannot be allo‐
280 cated, it does not cause the Tcl interpreter to panic. Thus, if
281 newLength is greater than the space allocated for the object's string,
282 and there is not enough memory available to satisfy the request,
283 Tcl_AttemptSetObjLength will take no action and return 0 to indicate
284 failure. If there is enough memory to satisfy the request,
285 Tcl_AttemptSetObjLength behaves just like Tcl_SetObjLength and returns
286 1 to indicate success.
287 The Tcl_ConcatObj function returns a new string object whose value is
289 the space-separated concatenation of the string representations of all
290 of the objects in the objv array. Tcl_ConcatObj eliminates leading and
291 trailing white space as it copies the string representations of the
292 objv array to the result. If an element of the objv array consists of
293 nothing but white space, then that object is ignored entirely. This
294 white-space removal was added to make the output of the concat command
295 cleaner-looking. Tcl_ConcatObj returns a pointer to a newly-created
296 object whose ref count is zero.
297
300 Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
301
304 append, internal representation, object, object type, string object,
305 string type, string representation, concat, concatenate, unicode
306Tcl 8.1 Tcl_StringObj(3)