1Tcl_ListObj(3)              Tcl Library Procedures              Tcl_ListObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

13       #include <tcl.h>
14
15       int
16       Tcl_ListObjAppendList(interp, listPtr, elemListPtr)
17
18       int
19       Tcl_ListObjAppendElement(interp, listPtr, objPtr)
20
21       Tcl_Obj *
22       Tcl_NewListObj(objc, objv)
23
24       Tcl_SetListObj(objPtr, objc, objv)
25
26       int
27       Tcl_ListObjGetElements(interp, listPtr, objcPtr, objvPtr)
28
29       int
30       Tcl_ListObjLength(interp, listPtr, intPtr)
31
32       int
33       Tcl_ListObjIndex(interp, listPtr, index, objPtrPtr)
34
35       int
36       Tcl_ListObjReplace(interp, listPtr, first, count, objc, objv)
37

ARGUMENTS

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
46       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
52       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
64       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
74       int *objcPtr (in)                         Points  to   location   where
75                                                 Tcl_ListObjGetElements stores
76                                                 the number of element objects
77                                                 in listPtr.
78
79       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
85       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
94       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
103       int *intPtr (out)                         Points   to   location  where
104                                                 Tcl_ListObjLength stores  the
105                                                 length of the list.
106
107       int index (in)                            Index  of  the  list  element
108                                                 that Tcl_ListObjIndex  is  to
109                                                 return.   The  first  element
110                                                 has index 0.
111
112       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
117       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
123       int count (in)                            The  number  of elements that
124                                                 Tcl_ListObjReplace   is    to
125                                                 replace.
126_________________________________________________________________
127
128

DESCRIPTION

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
135       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
157       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
166       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
177       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
185       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
198       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
216       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
222              result = Tcl_ListObjReplace(interp, listPtr, index, 0,
223                      objc, objv);
224
225       Similarly,  the  following  code appends the objc objects referenced by
226       the array objv to the end of the list listPtr:
227
228              result = Tcl_ListObjLength(interp, listPtr, &length);
229              if (result == TCL_OK) {
230                  result = Tcl_ListObjReplace(interp, listPtr, length, 0,
231                          objc, objv);
232              }
233
234       The count list elements starting at first  can  be  deleted  by  simply
235       calling Tcl_ListObjReplace with a NULL objvPtr:
236
237              result = Tcl_ListObjReplace(interp, listPtr, first, count,
238                      0, NULL);
239

SEE ALSO

241       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
242

KEYWORDS

244       append,  index,  insert,  internal  representation,  length, list, list
245       object, list type, object, object type, replace, string representation
246
247
248
249Tcl                                   8.0                       Tcl_ListObj(3)
Impressum