diff options
Diffstat (limited to 'doc/ListObj.3')
| -rw-r--r-- | doc/ListObj.3 | 29 |
1 files changed, 17 insertions, 12 deletions
diff --git a/doc/ListObj.3 b/doc/ListObj.3 index 9aaf858..070e1b6 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ListObj.3,v 1.4 2000/01/26 03:37:30 hobbs Exp $ +'\" RCS: @(#) $Id: ListObj.3,v 1.12 2007/12/13 15:22:31 dgp Exp $ '\" .so man.macros .TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures" @@ -38,7 +38,7 @@ int int \fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR) .SH ARGUMENTS -.AS Tcl_Interp "*CONST objv[]" out +.AS "Tcl_Obj *const" *elemListPtr in/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 @@ -73,13 +73,11 @@ 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 -.AP Tcl_Obj "*CONST\ objv[]" in +.AP "Tcl_Obj *const" objv[] 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. @@ -153,8 +151,9 @@ has reference count zero. 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. -The memory pointed to is managed by Tcl and should not be freed by the -caller. +The memory pointed to is managed by Tcl and should not be freed or written +to by the caller. If the list is empty, 0 is stored at \fIobjcPtr\fR +and NULL at \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 @@ -221,27 +220,33 @@ 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: +.PP .CS -result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv); +result = Tcl_ListObjReplace(interp, listPtr, index, 0, + objc, objv); .CE +.PP Similarly, the following code appends the \fIobjc\fR objects referenced by the array \fIobjv\fR to the end of the list \fIlistPtr\fR: +.PP .CS result = Tcl_ListObjLength(interp, listPtr, &length); if (result == TCL_OK) { - result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv); + result = Tcl_ListObjReplace(interp, listPtr, length, 0, + objc, objv); } .CE +.PP The \fIcount\fR list elements starting at \fIfirst\fR can be deleted by simply calling \fBTcl_ListObjReplace\fR with a NULL \fIobjvPtr\fR: +.PP .CS -result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL); +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 |