1Tcl_ListObj(3) Tcl Library Procedures Tcl_ListObj(3)
2______________________________________________________________________________
6
8 Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj,
9 Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListOb‐
10 jIndex, Tcl_ListObjReplace - manipulate Tcl objects as lists
11
13 #include <tcl.h>
14 int
16 Tcl_ListObjAppendList(interp, listPtr, elemListPtr)
17 int
19 Tcl_ListObjAppendElement(interp, listPtr, objPtr)
20 Tcl_Obj *
22 Tcl_NewListObj(objc, objv)
23 Tcl_SetListObj(objPtr, objc, objv)
25 int
27 Tcl_ListObjGetElements(interp, listPtr, objcPtr, objvPtr)
28 int
30 Tcl_ListObjLength(interp, listPtr, intPtr)
31 int
33 Tcl_ListObjIndex(interp, listPtr, index, objPtrPtr)
34 int
36 Tcl_ListObjReplace(interp, listPtr, first, count, objc, objv)
37
39 Tcl_Interp *interp (in) If an error occurs while con‐
40 verting an object to be a
41 list object, an error message
42 is left in the interpreter's
43 result object unless interp
44 is NULL.
45 Tcl_Obj *listPtr (in/out) Points to the list object to
47 be manipulated. If listPtr
48 does not already point to a
49 list object, an attempt will
50 be made to convert it to one.
51 Tcl_Obj *elemListPtr (in/out) For Tcl_ListObjAppendList,
53 this points to a list object
54 containing elements to be
55 appended onto listPtr. Each
56 element of *elemListPtr will
57 become a new element of
58 listPtr. If *elemListPtr is
59 not NULL and does not already
60 point to a list object, an
61 attempt will be made to con‐
62 vert it to one.
63 Tcl_Obj *objPtr (in) For Tcl_ListObjAppendElement,
65 points to the Tcl object that
66 will be appended to listPtr.
67 For Tcl_SetListObj, this
68 points to the Tcl object that
69 will be converted to a list
70 object containing the objc
71 elements of the array refer‐
72 enced by objv.
73 int *objcPtr (in) Points to location where
75 Tcl_ListObjGetElements stores
76 the number of element objects
77 in listPtr.
78 Tcl_Obj ***objvPtr (out) A location where Tcl_ListOb‐
80 jGetElements stores a pointer
81 to an array of pointers to
82 the element objects of
83 listPtr.
84 int objc (in) The number of Tcl objects
86 that Tcl_NewListObj will
87 insert into a new list
88 object, and Tcl_ListObjRe‐
89 place will insert into
90 listPtr. For Tcl_SetListObj,
91 the number of Tcl objects to
92 insert into objPtr.
93 Tcl_Obj *const objv[] (in) An array of pointers to
95 objects. Tcl_NewListObj will
96 insert these objects into a
97 new list object and Tcl_Lis‐
98 tObjReplace will insert them
99 into an existing listPtr.
100 Each object will become a
101 separate list element.
102 int *intPtr (out) Points to location where
104 Tcl_ListObjLength stores the
105 length of the list.
106 int index (in) Index of the list element
108 that Tcl_ListObjIndex is to
109 return. The first element
110 has index 0.
111 Tcl_Obj **objPtrPtr (out) Points to place where
113 Tcl_ListObjIndex is to store
114 a pointer to the resulting
115 list element object.
116 int first (in) Index of the starting list
118 element that Tcl_ListObjRe‐
119 place is to replace. The
120 list's first element has
121 index 0.
122 int count (in) The number of elements that
124 Tcl_ListObjReplace is to
125 replace.
126_________________________________________________________________
127
130 Tcl list objects have an internal representation that supports the
131 efficient indexing and appending. The procedures described in this man
132 page are used to create, modify, index, and append to Tcl list objects
133 from C code.
134 Tcl_ListObjAppendList and Tcl_ListObjAppendElement both add one or more
136 objects to the end of the list object referenced by listPtr. Tcl_Lis‐
137 tObjAppendList appends each element of the list object referenced by
138 elemListPtr while Tcl_ListObjAppendElement appends the single object
139 referenced by objPtr. Both procedures will convert the object refer‐
140 enced by listPtr to a list object if necessary. If an error occurs
141 during conversion, both procedures return TCL_ERROR and leave an error
142 message in the interpreter's result object if interp is not NULL. Sim‐
143 ilarly, if elemListPtr does not already refer to a list object,
144 Tcl_ListObjAppendList will attempt to convert it to one and if an error
145 occurs during conversion, will return TCL_ERROR and leave an error mes‐
146 sage in the interpreter's result object if interp is not NULL. Both
147 procedures invalidate any old string representation of listPtr and, if
148 it was converted to a list object, free any old internal representa‐
149 tion. Similarly, Tcl_ListObjAppendList frees any old internal repre‐
150 sentation of elemListPtr if it converts it to a list object. After
151 appending each element in elemListPtr, Tcl_ListObjAppendList increments
152 the element's reference count since listPtr now also refers to it. For
153 the same reason, Tcl_ListObjAppendElement increments objPtr's reference
154 count. If no error occurs, the two procedures return TCL_OK after
155 appending the objects.
156 Tcl_NewListObj and Tcl_SetListObj create a new object or modify an
158 existing object to hold the objc elements of the array referenced by
159 objv where each element is a pointer to a Tcl object. If objc is less
160 than or equal to zero, they return an empty object. The new object's
161 string representation is left invalid. The two procedures increment
162 the reference counts of the elements in objc since the list object now
163 refers to them. The new list object returned by Tcl_NewListObj has
164 reference count zero.
165 Tcl_ListObjGetElements returns a count and a pointer to an array of the
167 elements in a list object. It returns the count by storing it in the
168 address objcPtr. Similarly, it returns the array pointer by storing it
169 in the address objvPtr. The memory pointed to is managed by Tcl and
170 should not be freed or written to by the caller. If the list is empty,
171 0 is stored at objcPtr and NULL at objvPtr. If listPtr is not already
172 a list object, Tcl_ListObjGetElements will attempt to convert it to
173 one; if the conversion fails, it returns TCL_ERROR and leaves an error
174 message in the interpreter's result object if interp is not NULL. Oth‐
175 erwise it returns TCL_OK after storing the count and array pointer.
176 Tcl_ListObjLength returns the number of elements in the list object
178 referenced by listPtr. It returns this count by storing an integer in
179 the address intPtr. If the object is not already a list object,
180 Tcl_ListObjLength will attempt to convert it to one; if the conversion
181 fails, it returns TCL_ERROR and leaves an error message in the inter‐
182 preter's result object if interp is not NULL. Otherwise it returns
183 TCL_OK after storing the list's length.
184 The procedure Tcl_ListObjIndex returns a pointer to the object at ele‐
186 ment index in the list referenced by listPtr. It returns this object
187 by storing a pointer to it in the address objPtrPtr. If listPtr does
188 not already refer to a list object, Tcl_ListObjIndex will attempt to
189 convert it to one; if the conversion fails, it returns TCL_ERROR and
190 leaves an error message in the interpreter's result object if interp is
191 not NULL. If the index is out of range, that is, index is negative or
192 greater than or equal to the number of elements in the list, Tcl_ListO‐
193 bjIndex stores a NULL in objPtrPtr and returns TCL_OK. Otherwise it
194 returns TCL_OK after storing the element's object pointer. The refer‐
195 ence count for the list element is not incremented; the caller must do
196 that if it needs to retain a pointer to the element.
197 Tcl_ListObjReplace replaces zero or more elements of the list refer‐
199 enced by listPtr with the objc objects in the array referenced by objv.
200 If listPtr does not point to a list object, Tcl_ListObjReplace will
201 attempt to convert it to one; if the conversion fails, it returns
202 TCL_ERROR and leaves an error message in the interpreter's result
203 object if interp is not NULL. Otherwise, it returns TCL_OK after
204 replacing the objects. If objv is NULL, no new elements are added. If
205 the argument first is zero or negative, it refers to the first element.
206 If first is greater than or equal to the number of elements in the
207 list, then no elements are deleted; the new elements are appended to
208 the list. count gives the number of elements to replace. If count is
209 zero or negative then no elements are deleted; the new elements are
210 simply inserted before the one designated by first. Tcl_ListObjReplace
211 invalidates listPtr's old string representation. The reference counts
212 of any elements inserted from objv are incremented since the resulting
213 list now refers to them. Similarly, the reference counts for any
214 replaced objects are decremented.
215 Because Tcl_ListObjReplace combines both element insertion and dele‐
217 tion, it can be used to implement a number of list operations. For
218 example, the following code inserts the objc objects referenced by the
219 array of object pointers objv just before the element index of the list
220 referenced by listPtr:
221 result = Tcl_ListObjReplace(interp, listPtr, index, 0,
223 objc, objv);
224 Similarly, the following code appends the objc objects referenced by
226 the array objv to the end of the list listPtr:
227 result = Tcl_ListObjLength(interp, listPtr, &length);
229 if (result == TCL_OK) {
230 result = Tcl_ListObjReplace(interp, listPtr, length, 0,
231 objc, objv);
232 }
233 The count list elements starting at first can be deleted by simply
235 calling Tcl_ListObjReplace with a NULL objvPtr:
236 result = Tcl_ListObjReplace(interp, listPtr, first, count,
238 0, NULL);
239
241 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
242
244 append, index, insert, internal representation, length, list, list
245 object, list type, object, object type, replace, string representation
246Tcl 8.0 Tcl_ListObj(3)