250 lines
10 KiB
Groff
250 lines
10 KiB
Groff
'\"
|
|
'\" 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
|