diff options
Diffstat (limited to 'doc/ListObj.3')
| -rw-r--r-- | doc/ListObj.3 | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/doc/ListObj.3 b/doc/ListObj.3 new file mode 100644 index 0000000..c19e234 --- /dev/null +++ b/doc/ListObj.3 @@ -0,0 +1,249 @@ +'\" +'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) @(#) ListObj.3 1.10 97/10/08 11:36:58 +'\" +.so man.macros +.TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl objects as lists +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +int +\fBTcl_ListObjAppendList\fR(\fIinterp, listPtr, elemListPtr\fR) +.sp +int +\fBTcl_ListObjAppendElement\fR(\fIinterp, listPtr, objPtr\fR) +.sp +Tcl_Obj * +\fBTcl_NewListObj\fR(\fIobjc, objv\fR) +.sp +\fBTcl_SetListObj\fR(\fIobjPtr, objc, objv\fR) +.sp +int +\fBTcl_ListObjGetElements\fR(\fIinterp, listPtr, objcPtr, objvPtr\fR) +.sp +int +\fBTcl_ListObjLength\fR(\fIinterp, listPtr, intPtr\fR) +.sp +int +\fBTcl_ListObjIndex\fR(\fIinterp, listPtr, index, objPtrPtr\fR) +.sp +int +\fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR) +.SH ARGUMENTS +.AS Tcl_Interp "*CONST objv[]" out +.AP Tcl_Interp *interp in +If an error occurs while converting an object to be a list object, +an error message is left in the interpreter's result object +unless \fIinterp\fR is NULL. +.AP Tcl_Obj *listPtr in/out +Points to the list object to be manipulated. +If \fIlistPtr\fR does not already point to a list object, +an attempt will be made to convert it to one. +.AP Tcl_Obj *elemListPtr in/out +For \fBTcl_ListObjAppendList\fR, this points to a list object +containing elements to be appended onto \fIlistPtr\fR. +Each element of *\fIelemListPtr\fR will +become a new element of \fIlistPtr\fR. +If *\fIelemListPtr\fR is not NULL and +does not already point to a list object, +an attempt will be made to convert it to one. +.AP Tcl_Obj *objPtr in +For \fBTcl_ListObjAppendElement\fR, +points to the Tcl object that will be appended to \fIlistPtr\fR. +For \fBTcl_SetListObj\fR, +this points to the Tcl object that will be converted to a list object +containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR. +.AP int *objcPtr in +Points to location where \fBTcl_ListObjGetElements\fR +stores the number of element objects in \fIlistPtr\fR. +.AP Tcl_Obj ***objvPtr out +A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array +of pointers to the element objects of \fIlistPtr\fR. +.AP int objc in +The number of Tcl objects that \fBTcl_NewListObj\fR +will insert into a new list object, +and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR. +For \fBTcl_SetListObj\fR, +the number of Tcl objects to insert into \fIobjPtr\fR. +.VS +.TP +Tcl_Obj *CONST \fIobjv\fR[] (in) +. +An array of pointers to objects. +\fBTcl_NewListObj\fR will insert these objects into a new list object +and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR. +Each object will become a separate list element. +.VE +.AP int *intPtr out +Points to location where \fBTcl_ListObjLength\fR +stores the length of the list. +.AP int index in +Index of the list element that \fBTcl_ListObjIndex\fR +is to return. +The first element has index 0. +.AP Tcl_Obj **objPtrPtr out +Points to place where \fBTcl_ListObjIndex\fR is to store +a pointer to the resulting list element object. +.AP int first in +Index of the starting list element that \fBTcl_ListObjReplace\fR +is to replace. +The list's first element has index 0. +.AP int count in +The number of elements that \fBTcl_ListObjReplace\fR +is to replace. +.BE + +.SH DESCRIPTION +.PP +Tcl list objects have an internal representation that supports +the efficient indexing and appending. +The procedures described in this man page are used to +create, modify, index, and append to Tcl list objects from C code. +.PP +\fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR +both add one or more objects +to the end of the list object referenced by \fIlistPtr\fR. +\fBTcl_ListObjAppendList\fR appends each element of the list object +referenced by \fIelemListPtr\fR while +\fBTcl_ListObjAppendElement\fR appends the single object +referenced by \fIobjPtr\fR. +Both procedures will convert the object referenced by \fIlistPtr\fR +to a list object if necessary. +If an error occurs during conversion, +both procedures return \fBTCL_ERROR\fR and leave an error message +in the interpreter's result object if \fIinterp\fR is not NULL. +Similarly, if \fIelemListPtr\fR does not already refer to a list object, +\fBTcl_ListObjAppendList\fR will attempt to convert it to one +and if an error occurs during conversion, +will return \fBTCL_ERROR\fR +and leave an error message in the interpreter's result object +if interp is not NULL. +Both procedures invalidate any old string representation of \fIlistPtr\fR +and, if it was converted to a list object, +free any old internal representation. +Similarly, \fBTcl_ListObjAppendList\fR frees any old internal representation +of \fIelemListPtr\fR if it converts it to a list object. +After appending each element in \fIelemListPtr\fR, +\fBTcl_ListObjAppendList\fR increments the element's reference count +since \fIlistPtr\fR now also refers to it. +For the same reason, \fBTcl_ListObjAppendElement\fR +increments \fIobjPtr\fR's reference count. +If no error occurs, +the two procedures return \fBTCL_OK\fR after appending the objects. +.PP +\fBTcl_NewListObj\fR and \fBTcl_SetListObj\fR +create a new object or modify an existing object to hold +the \fIobjc\fR elements of the array referenced by \fIobjv\fR +where each element is a pointer to a Tcl object. +If \fIobjc\fR is less than or equal to zero, +they return an empty object. +The new object's string representation is left invalid. +The two procedures increment the reference counts +of the elements in \fIobjc\fR since the list object now refers to them. +The new list object returned by \fBTcl_NewListObj\fR +has reference count zero. +.PP +\fBTcl_ListObjGetElements\fR returns a count and +a pointer to an array of the elements in a list object. +It returns the count by storing it in the address \fIobjcPtr\fR. +Similarly, it returns the array pointer by storing it +in the address \fIobjvPtr\fR. +If \fIlistPtr\fR is not already a list object, +\fBTcl_ListObjGetElements\fR will attempt to convert it to one; +if the conversion fails, it returns \fBTCL_ERROR\fR +and leaves an error message in the interpreter's result object +if \fIinterp\fR is not NULL. +Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer. +.PP +\fBTcl_ListObjLength\fR returns the number of elements in the list object +referenced by \fIlistPtr\fR. +It returns this count by storing an integer in the address \fIintPtr\fR. +If the object is not already a list object, +\fBTcl_ListObjLength\fR will attempt to convert it to one; +if the conversion fails, it returns \fBTCL_ERROR\fR +and leaves an error message in the interpreter's result object +if \fIinterp\fR is not NULL. +Otherwise it returns \fBTCL_OK\fR after storing the list's length. +.PP +The procedure \fBTcl_ListObjIndex\fR returns a pointer to the object +at element \fIindex\fR in the list referenced by \fIlistPtr\fR. +It returns this object by storing a pointer to it +in the address \fIobjPtrPtr\fR. +If \fIlistPtr\fR does not already refer to a list object, +\fBTcl_ListObjIndex\fR will attempt to convert it to one; +if the conversion fails, it returns \fBTCL_ERROR\fR +and leaves an error message in the interpreter's result object +if \fIinterp\fR is not NULL. +If the index is out of range, +that is, \fIindex\fR is negative or +greater than or equal to the number of elements in the list, +\fBTcl_ListObjIndex\fR stores a NULL in \fIobjPtrPtr\fR +and returns \fBTCL_OK\fR. +Otherwise it returns \fBTCL_OK\fR after storing the element's +object pointer. +The reference count for the list element is not incremented; +the caller must do that if it needs to retain a pointer to the element. +.PP +\fBTcl_ListObjReplace\fR replaces zero or more elements +of the list referenced by \fIlistPtr\fR +with the \fIobjc\fR objects in the array referenced by \fIobjv\fR. +If \fIlistPtr\fR does not point to a list object, +\fBTcl_ListObjReplace\fR will attempt to convert it to one; +if the conversion fails, it returns \fBTCL_ERROR\fR +and leaves an error message in the interpreter's result object +if \fIinterp\fR is not NULL. +Otherwise, it returns \fBTCL_OK\fR after replacing the objects. +If \fIobjv\fR is NULL, no new elements are added. +If the argument \fIfirst\fR is zero or negative, +it refers to the first element. +If \fIfirst\fR is greater than or equal to the +number of elements in the list, then no elements are deleted; +the new elements are appended to the list. +\fIcount\fR gives the number of elements to replace. +If \fIcount\fR is zero or negative then no elements are deleted; +the new elements are simply inserted before the one +designated by \fIfirst\fR. +\fBTcl_ListObjReplace\fR invalidates \fIlistPtr\fR's +old string representation. +The reference counts of any elements inserted from \fIobjv\fR +are incremented since the resulting list now refers to them. +Similarly, the reference counts for any replaced objects are decremented. +.PP +Because \fBTcl_ListObjReplace\fR combines +both element insertion and deletion, +it can be used to implement a number of list operations. +For example, the following code inserts the \fIobjc\fR objects +referenced by the array of object pointers \fIobjv\fR +just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR: +.CS +result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv); +.CE +Similarly, the following code appends the \fIobjc\fR objects +referenced by the array \fIobjv\fR +to the end of the list \fIlistPtr\fR: +.CS +result = Tcl_ListObjLength(interp, listPtr, &length); +if (result == TCL_OK) { + result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv); +} +.CE +The \fIcount\fR list elements starting at \fIfirst\fR can be deleted +by simply calling \fBTcl_ListObjReplace\fR +with a NULL \fIobjvPtr\fR: +.CS +result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL); +.CE + +.SH "SEE ALSO" +Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult + +.SH KEYWORDS +append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation |