Subversion Repositories or1k

'\"

'\" 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.

'\"

'\" RCS: @(#) $Id: ListObj.3,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $

'\"

.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 \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