diff options
Diffstat (limited to 'contrib/tcl/doc/ListObj.3')
| -rw-r--r-- | contrib/tcl/doc/ListObj.3 | 249 |
1 files changed, 0 insertions, 249 deletions
diff --git a/contrib/tcl/doc/ListObj.3 b/contrib/tcl/doc/ListObj.3 deleted file mode 100644 index c19e2344ba09..000000000000 --- a/contrib/tcl/doc/ListObj.3 +++ /dev/null @@ -1,249 +0,0 @@ -'\" -'\" 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 |