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 values 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 a value to be a  list
41                                                 value,  an  error  message is
42                                                 left  in  the   interpreter's
43                                                 result value unless interp is
44                                                 NULL.
45
46       Tcl_Obj *listPtr (in/out)                 Points to the list  value  to
47                                                 be  manipulated.   If listPtr
48                                                 does not already point  to  a
49                                                 list  value,  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 value
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  value,  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 value that
66                                                 will be appended to  listPtr.
67                                                 For    Tcl_SetListObj,   this
68                                                 points to the Tcl value  that
69                                                 will  be  converted to a list
70                                                 value  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  values
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    values    of
83                                                 listPtr.
84
85       int objc (in)                             The number of Tcl values that
86                                                 Tcl_NewListObj  will   insert
87                                                 into  a  new  list value, and
88                                                 Tcl_ListObjReplace       will
89                                                 insert   into  listPtr.   For
90                                                 Tcl_SetListObj, the number of
91                                                 Tcl  values  to  insert  into
92                                                 objPtr.
93
94       Tcl_Obj *const objv[] (in)                An array of pointers to  val‐
95                                                 ues.    Tcl_NewListObj   will
96                                                 insert these  values  into  a
97                                                 new list value and Tcl_ListO‐
98                                                 bjReplace  will  insert  them
99                                                 into   an  existing  listPtr.
100                                                 Each value will become a sep‐
101                                                 arate 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 value.
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 values have an internal representation that supports the effi‐
131       cient indexing and appending.  The procedures  described  in  this  man
132       page  are  used to create, modify, index, and append to Tcl list values
133       from C code.
134
135       Tcl_ListObjAppendList and Tcl_ListObjAppendElement both add one or more
136       values to the end of the list value referenced by listPtr.  Tcl_ListOb‐
137       jAppendList appends each element of the list value referenced by  elem‐
138       ListPtr  while Tcl_ListObjAppendElement appends the single value refer‐
139       enced by objPtr.  Both procedures will convert the value referenced  by
140       listPtr  to  a list value if necessary.  If an error occurs during con‐
141       version, both procedures return TCL_ERROR and leave an error message in
142       the  interpreter's  result  value if interp is not NULL.  Similarly, if
143       elemListPtr does not already refer  to  a  list  value,  Tcl_ListObjAp‐
144       pendList  will attempt to convert it to one and if an error occurs dur‐
145       ing conversion, will return TCL_ERROR and leave an error message in the
146       interpreter's  result  value  if  interp  is not NULL.  Both procedures
147       invalidate any old string representation of listPtr and, if it was con‐
148       verted  to  a  list value, free any old internal representation.  Simi‐
149       larly, Tcl_ListObjAppendList frees any old internal  representation  of
150       elemListPtr  if  it  converts it to a list value.  After appending each
151       element in elemListPtr, Tcl_ListObjAppendList increments the  element's
152       reference count since listPtr now also refers to it.  For the same rea‐
153       son, Tcl_ListObjAppendElement increments objPtr's reference count.   If
154       no  error  occurs, the two procedures return TCL_OK after appending the
155       values.
156
157       Tcl_NewListObj and Tcl_SetListObj create  a  new  value  or  modify  an
158       existing  value  to  hold  the objc elements of the array referenced by
159       objv where each element is a pointer to a Tcl value.  If objc  is  less
160       than  or  equal  to  zero, they return an empty value.  The new value's
161       string representation is left invalid.  The  two  procedures  increment
162       the  reference  counts of the elements in objc since the list value now
163       refers to them.  The new list value returned by Tcl_NewListObj has ref‐
164       erence count zero.
165
166       Tcl_ListObjGetElements returns a count and a pointer to an array of the
167       elements in a list value.  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 value, Tcl_ListObjGetElements will attempt to convert it to one;
173       if the conversion fails, it returns TCL_ERROR and leaves an error  mes‐
174       sage  in  the interpreter's result value if interp is not NULL.  Other‐
175       wise it returns TCL_OK after storing the count and array pointer.
176
177       Tcl_ListObjLength returns the number of elements in the list value ref‐
178       erenced by listPtr.  It returns this count by storing an integer in the
179       address intPtr.  If the value is not already a list value,  Tcl_ListOb‐
180       jLength  will attempt to convert it to one; if the conversion fails, it
181       returns TCL_ERROR and leaves an  error  message  in  the  interpreter's
182       result  value if interp is not NULL.  Otherwise it returns TCL_OK after
183       storing the list's length.
184
185       The procedure Tcl_ListObjIndex returns a pointer to the value  at  ele‐
186       ment index in the list referenced by listPtr.  It returns this value by
187       storing a pointer to it in the address objPtrPtr.  If listPtr does  not
188       already refer to a list value, Tcl_ListObjIndex will attempt to convert
189       it to one; if the conversion fails, it returns TCL_ERROR and leaves  an
190       error  message in the interpreter's result value if interp is not NULL.
191       If the index is out of range, that is, index  is  negative  or  greater
192       than  or  equal to the number of elements in the list, Tcl_ListObjIndex
193       stores a NULL in objPtrPtr and returns TCL_OK.   Otherwise  it  returns
194       TCL_OK  after storing the element's value pointer.  The reference count
195       for the list element is not incremented; the caller must do that if  it
196       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 values in the array referenced by  objv.
200       If  listPtr  does  not  point  to a list value, 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 value
203       if interp is not NULL.  Otherwise, it returns  TCL_OK  after  replacing
204       the  values.  If objv is NULL, no new elements are added.  If the argu‐
205       ment first is zero or negative, it refers to  the  first  element.   If
206       first  is  greater than or equal to the number of elements in the list,
207       then no elements are deleted; the new  elements  are  appended  to  the
208       list.  count gives the number of elements to replace.  If count is zero
209       or negative then no elements are deleted; the new elements  are  simply
210       inserted before the one designated by first.  Tcl_ListObjReplace inval‐
211       idates listPtr's old string representation.  The  reference  counts  of
212       any  elements  inserted  from  objv are incremented since the resulting
213       list now refers to them.   Similarly,  the  reference  counts  for  any
214       replaced values 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 values referenced by the
219       array of value 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 values referenced by the
226       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(3),  Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjRe‐
242       sult(3)
243

KEYWORDS

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