1 | '\" |
---|
2 | '\" Copyright (c) 1996-1997 Sun Microsystems, Inc. |
---|
3 | '\" |
---|
4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
6 | '\" |
---|
7 | '\" RCS: @(#) $Id: ListObj.3,v 1.12 2007/12/13 15:22:31 dgp Exp $ |
---|
8 | '\" |
---|
9 | .so man.macros |
---|
10 | .TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures" |
---|
11 | .BS |
---|
12 | .SH NAME |
---|
13 | Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl objects as lists |
---|
14 | .SH SYNOPSIS |
---|
15 | .nf |
---|
16 | \fB#include <tcl.h>\fR |
---|
17 | .sp |
---|
18 | int |
---|
19 | \fBTcl_ListObjAppendList\fR(\fIinterp, listPtr, elemListPtr\fR) |
---|
20 | .sp |
---|
21 | int |
---|
22 | \fBTcl_ListObjAppendElement\fR(\fIinterp, listPtr, objPtr\fR) |
---|
23 | .sp |
---|
24 | Tcl_Obj * |
---|
25 | \fBTcl_NewListObj\fR(\fIobjc, objv\fR) |
---|
26 | .sp |
---|
27 | \fBTcl_SetListObj\fR(\fIobjPtr, objc, objv\fR) |
---|
28 | .sp |
---|
29 | int |
---|
30 | \fBTcl_ListObjGetElements\fR(\fIinterp, listPtr, objcPtr, objvPtr\fR) |
---|
31 | .sp |
---|
32 | int |
---|
33 | \fBTcl_ListObjLength\fR(\fIinterp, listPtr, intPtr\fR) |
---|
34 | .sp |
---|
35 | int |
---|
36 | \fBTcl_ListObjIndex\fR(\fIinterp, listPtr, index, objPtrPtr\fR) |
---|
37 | .sp |
---|
38 | int |
---|
39 | \fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR) |
---|
40 | .SH ARGUMENTS |
---|
41 | .AS "Tcl_Obj *const" *elemListPtr in/out |
---|
42 | .AP Tcl_Interp *interp in |
---|
43 | If an error occurs while converting an object to be a list object, |
---|
44 | an error message is left in the interpreter's result object |
---|
45 | unless \fIinterp\fR is NULL. |
---|
46 | .AP Tcl_Obj *listPtr in/out |
---|
47 | Points to the list object to be manipulated. |
---|
48 | If \fIlistPtr\fR does not already point to a list object, |
---|
49 | an attempt will be made to convert it to one. |
---|
50 | .AP Tcl_Obj *elemListPtr in/out |
---|
51 | For \fBTcl_ListObjAppendList\fR, this points to a list object |
---|
52 | containing elements to be appended onto \fIlistPtr\fR. |
---|
53 | Each element of *\fIelemListPtr\fR will |
---|
54 | become a new element of \fIlistPtr\fR. |
---|
55 | If *\fIelemListPtr\fR is not NULL and |
---|
56 | does not already point to a list object, |
---|
57 | an attempt will be made to convert it to one. |
---|
58 | .AP Tcl_Obj *objPtr in |
---|
59 | For \fBTcl_ListObjAppendElement\fR, |
---|
60 | points to the Tcl object that will be appended to \fIlistPtr\fR. |
---|
61 | For \fBTcl_SetListObj\fR, |
---|
62 | this points to the Tcl object that will be converted to a list object |
---|
63 | containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR. |
---|
64 | .AP int *objcPtr in |
---|
65 | Points to location where \fBTcl_ListObjGetElements\fR |
---|
66 | stores the number of element objects in \fIlistPtr\fR. |
---|
67 | .AP Tcl_Obj ***objvPtr out |
---|
68 | A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array |
---|
69 | of pointers to the element objects of \fIlistPtr\fR. |
---|
70 | .AP int objc in |
---|
71 | The number of Tcl objects that \fBTcl_NewListObj\fR |
---|
72 | will insert into a new list object, |
---|
73 | and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR. |
---|
74 | For \fBTcl_SetListObj\fR, |
---|
75 | the number of Tcl objects to insert into \fIobjPtr\fR. |
---|
76 | .AP "Tcl_Obj *const" objv[] in |
---|
77 | An array of pointers to objects. |
---|
78 | \fBTcl_NewListObj\fR will insert these objects into a new list object |
---|
79 | and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR. |
---|
80 | Each object will become a separate list element. |
---|
81 | .AP int *intPtr out |
---|
82 | Points to location where \fBTcl_ListObjLength\fR |
---|
83 | stores the length of the list. |
---|
84 | .AP int index in |
---|
85 | Index of the list element that \fBTcl_ListObjIndex\fR |
---|
86 | is to return. |
---|
87 | The first element has index 0. |
---|
88 | .AP Tcl_Obj **objPtrPtr out |
---|
89 | Points to place where \fBTcl_ListObjIndex\fR is to store |
---|
90 | a pointer to the resulting list element object. |
---|
91 | .AP int first in |
---|
92 | Index of the starting list element that \fBTcl_ListObjReplace\fR |
---|
93 | is to replace. |
---|
94 | The list's first element has index 0. |
---|
95 | .AP int count in |
---|
96 | The number of elements that \fBTcl_ListObjReplace\fR |
---|
97 | is to replace. |
---|
98 | .BE |
---|
99 | |
---|
100 | .SH DESCRIPTION |
---|
101 | .PP |
---|
102 | Tcl list objects have an internal representation that supports |
---|
103 | the efficient indexing and appending. |
---|
104 | The procedures described in this man page are used to |
---|
105 | create, modify, index, and append to Tcl list objects from C code. |
---|
106 | .PP |
---|
107 | \fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR |
---|
108 | both add one or more objects |
---|
109 | to the end of the list object referenced by \fIlistPtr\fR. |
---|
110 | \fBTcl_ListObjAppendList\fR appends each element of the list object |
---|
111 | referenced by \fIelemListPtr\fR while |
---|
112 | \fBTcl_ListObjAppendElement\fR appends the single object |
---|
113 | referenced by \fIobjPtr\fR. |
---|
114 | Both procedures will convert the object referenced by \fIlistPtr\fR |
---|
115 | to a list object if necessary. |
---|
116 | If an error occurs during conversion, |
---|
117 | both procedures return \fBTCL_ERROR\fR and leave an error message |
---|
118 | in the interpreter's result object if \fIinterp\fR is not NULL. |
---|
119 | Similarly, if \fIelemListPtr\fR does not already refer to a list object, |
---|
120 | \fBTcl_ListObjAppendList\fR will attempt to convert it to one |
---|
121 | and if an error occurs during conversion, |
---|
122 | will return \fBTCL_ERROR\fR |
---|
123 | and leave an error message in the interpreter's result object |
---|
124 | if interp is not NULL. |
---|
125 | Both procedures invalidate any old string representation of \fIlistPtr\fR |
---|
126 | and, if it was converted to a list object, |
---|
127 | free any old internal representation. |
---|
128 | Similarly, \fBTcl_ListObjAppendList\fR frees any old internal representation |
---|
129 | of \fIelemListPtr\fR if it converts it to a list object. |
---|
130 | After appending each element in \fIelemListPtr\fR, |
---|
131 | \fBTcl_ListObjAppendList\fR increments the element's reference count |
---|
132 | since \fIlistPtr\fR now also refers to it. |
---|
133 | For the same reason, \fBTcl_ListObjAppendElement\fR |
---|
134 | increments \fIobjPtr\fR's reference count. |
---|
135 | If no error occurs, |
---|
136 | the two procedures return \fBTCL_OK\fR after appending the objects. |
---|
137 | .PP |
---|
138 | \fBTcl_NewListObj\fR and \fBTcl_SetListObj\fR |
---|
139 | create a new object or modify an existing object to hold |
---|
140 | the \fIobjc\fR elements of the array referenced by \fIobjv\fR |
---|
141 | where each element is a pointer to a Tcl object. |
---|
142 | If \fIobjc\fR is less than or equal to zero, |
---|
143 | they return an empty object. |
---|
144 | The new object's string representation is left invalid. |
---|
145 | The two procedures increment the reference counts |
---|
146 | of the elements in \fIobjc\fR since the list object now refers to them. |
---|
147 | The new list object returned by \fBTcl_NewListObj\fR |
---|
148 | has reference count zero. |
---|
149 | .PP |
---|
150 | \fBTcl_ListObjGetElements\fR returns a count and a pointer to an array of |
---|
151 | the elements in a list object. It returns the count by storing it in the |
---|
152 | address \fIobjcPtr\fR. Similarly, it returns the array pointer by storing |
---|
153 | it in the address \fIobjvPtr\fR. |
---|
154 | The memory pointed to is managed by Tcl and should not be freed or written |
---|
155 | to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR |
---|
156 | and NULL at \fIobjvPtr\fR. |
---|
157 | If \fIlistPtr\fR is not already a list object, \fBTcl_ListObjGetElements\fR |
---|
158 | will attempt to convert it to one; if the conversion fails, it returns |
---|
159 | \fBTCL_ERROR\fR and leaves an error message in the interpreter's result |
---|
160 | object if \fIinterp\fR is not NULL. |
---|
161 | Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer. |
---|
162 | .PP |
---|
163 | \fBTcl_ListObjLength\fR returns the number of elements in the list object |
---|
164 | referenced by \fIlistPtr\fR. |
---|
165 | It returns this count by storing an integer in the address \fIintPtr\fR. |
---|
166 | If the object is not already a list object, |
---|
167 | \fBTcl_ListObjLength\fR will attempt to convert it to one; |
---|
168 | if the conversion fails, it returns \fBTCL_ERROR\fR |
---|
169 | and leaves an error message in the interpreter's result object |
---|
170 | if \fIinterp\fR is not NULL. |
---|
171 | Otherwise it returns \fBTCL_OK\fR after storing the list's length. |
---|
172 | .PP |
---|
173 | The procedure \fBTcl_ListObjIndex\fR returns a pointer to the object |
---|
174 | at element \fIindex\fR in the list referenced by \fIlistPtr\fR. |
---|
175 | It returns this object by storing a pointer to it |
---|
176 | in the address \fIobjPtrPtr\fR. |
---|
177 | If \fIlistPtr\fR does not already refer to a list object, |
---|
178 | \fBTcl_ListObjIndex\fR will attempt to convert it to one; |
---|
179 | if the conversion fails, it returns \fBTCL_ERROR\fR |
---|
180 | and leaves an error message in the interpreter's result object |
---|
181 | if \fIinterp\fR is not NULL. |
---|
182 | If the index is out of range, |
---|
183 | that is, \fIindex\fR is negative or |
---|
184 | greater than or equal to the number of elements in the list, |
---|
185 | \fBTcl_ListObjIndex\fR stores a NULL in \fIobjPtrPtr\fR |
---|
186 | and returns \fBTCL_OK\fR. |
---|
187 | Otherwise it returns \fBTCL_OK\fR after storing the element's |
---|
188 | object pointer. |
---|
189 | The reference count for the list element is not incremented; |
---|
190 | the caller must do that if it needs to retain a pointer to the element. |
---|
191 | .PP |
---|
192 | \fBTcl_ListObjReplace\fR replaces zero or more elements |
---|
193 | of the list referenced by \fIlistPtr\fR |
---|
194 | with the \fIobjc\fR objects in the array referenced by \fIobjv\fR. |
---|
195 | If \fIlistPtr\fR does not point to a list object, |
---|
196 | \fBTcl_ListObjReplace\fR will attempt to convert it to one; |
---|
197 | if the conversion fails, it returns \fBTCL_ERROR\fR |
---|
198 | and leaves an error message in the interpreter's result object |
---|
199 | if \fIinterp\fR is not NULL. |
---|
200 | Otherwise, it returns \fBTCL_OK\fR after replacing the objects. |
---|
201 | If \fIobjv\fR is NULL, no new elements are added. |
---|
202 | If the argument \fIfirst\fR is zero or negative, |
---|
203 | it refers to the first element. |
---|
204 | If \fIfirst\fR is greater than or equal to the |
---|
205 | number of elements in the list, then no elements are deleted; |
---|
206 | the new elements are appended to the list. |
---|
207 | \fIcount\fR gives the number of elements to replace. |
---|
208 | If \fIcount\fR is zero or negative then no elements are deleted; |
---|
209 | the new elements are simply inserted before the one |
---|
210 | designated by \fIfirst\fR. |
---|
211 | \fBTcl_ListObjReplace\fR invalidates \fIlistPtr\fR's |
---|
212 | old string representation. |
---|
213 | The reference counts of any elements inserted from \fIobjv\fR |
---|
214 | are incremented since the resulting list now refers to them. |
---|
215 | Similarly, the reference counts for any replaced objects are decremented. |
---|
216 | .PP |
---|
217 | Because \fBTcl_ListObjReplace\fR combines |
---|
218 | both element insertion and deletion, |
---|
219 | it can be used to implement a number of list operations. |
---|
220 | For example, the following code inserts the \fIobjc\fR objects |
---|
221 | referenced by the array of object pointers \fIobjv\fR |
---|
222 | just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR: |
---|
223 | .PP |
---|
224 | .CS |
---|
225 | result = Tcl_ListObjReplace(interp, listPtr, index, 0, |
---|
226 | objc, objv); |
---|
227 | .CE |
---|
228 | .PP |
---|
229 | Similarly, the following code appends the \fIobjc\fR objects |
---|
230 | referenced by the array \fIobjv\fR |
---|
231 | to the end of the list \fIlistPtr\fR: |
---|
232 | .PP |
---|
233 | .CS |
---|
234 | result = Tcl_ListObjLength(interp, listPtr, &length); |
---|
235 | if (result == TCL_OK) { |
---|
236 | result = Tcl_ListObjReplace(interp, listPtr, length, 0, |
---|
237 | objc, objv); |
---|
238 | } |
---|
239 | .CE |
---|
240 | .PP |
---|
241 | The \fIcount\fR list elements starting at \fIfirst\fR can be deleted |
---|
242 | by simply calling \fBTcl_ListObjReplace\fR |
---|
243 | with a NULL \fIobjvPtr\fR: |
---|
244 | .PP |
---|
245 | .CS |
---|
246 | result = Tcl_ListObjReplace(interp, listPtr, first, count, |
---|
247 | 0, NULL); |
---|
248 | .CE |
---|
249 | .SH "SEE ALSO" |
---|
250 | Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult |
---|
251 | .SH KEYWORDS |
---|
252 | append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation |
---|