tcl.lang
Class TclList

java.lang.Object
  tcl.lang.TclList

All Implemented Interfaces:

InternalRep

public class TclList
extends Object
implements InternalRep

This class implements the list object type in Tcl.

Method Summary

static void	append(Interp interp, TclObject tobj, TclObject elemObj) Tcl_ListObjAppendElement -> TclList.append() Appends a TclObject element to a list object.
static void	append(Interp interp, TclObject tobj, TclObject[] objv, int startIdx, int endIdx) TclList.append() Appends multiple TclObject elements to a list object.
static TclObject	copy(Interp interp, TclObject list) copy (TclListObjCopy) -- Makes a "pure list" copy of a list value.
void	dispose() Called to free any storage for the type's internal rep.
InternalRep	duplicate() DupListInternalRep -> duplicate Returns a dupilcate of the current object.
static TclObject[]	getElements(Interp interp, TclObject tobj) Returns a TclObject array of the elements in a list object.
static ArrayList	getElementsList(Interp interp, TclObject tobj) Returns an ArrayList of TclObject elements in a list object.
static int	getLength(Interp interp, TclObject tobj) Queries the length of the list.
static TclObject	index(Interp interp, TclObject tobj, int index) This procedure returns a pointer to the index'th object from the list referenced by tobj.
static void	insert(Interp interp, TclObject tobj, int index, TclObject[] elements, int from, int to) This procedure inserts the elements in elements[] into the list at the given index.
static void	lsetElement(Interp interp, TclObject list, int index, TclObject value) TclListObjSetElement -- Set a single element of a list to a specified value in place (LsetCmd) Side effects: Tcl_Panic if listPtr designates a shared object.
static TclObject	newInstance() Creates a new instance of a TclObject with a TclList internal rep.
static void	replace(Interp interp, TclObject tobj, int index, int count, TclObject[] elements, int from, int to) This procedure replaces zero or more elements of the list referenced by tobj with the objects from an TclObject array.
static void	setElement(Interp interp, TclObject list, int index, TclObject value) TclListObjSetElement -- Set a single element of a list to a specified value Side effects: Tcl_Panic if listPtr designates a shared object.
static void	sort(Interp interp, TclObject tobj, int sortMode, int sortIndex, boolean sortIncreasing, boolean unique, String command) Sorts the list according to the sort mode and (optional) sort command.
String	toString() Called to query the string representation of the Tcl object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

dispose

public void dispose()

Called to free any storage for the type's internal rep.

Specified by:

dispose in interface InternalRep

duplicate

public InternalRep duplicate()

DupListInternalRep -> duplicate Returns a dupilcate of the current object.

Specified by:

duplicate in interface InternalRep

toString

public String toString()

Called to query the string representation of the Tcl object. This method is called only by TclObject.toString() when TclObject.stringRep is null.

Overrides:

toString in class Object

Returns:

the string representation of the Tcl object.

newInstance

public static TclObject newInstance()

Creates a new instance of a TclObject with a TclList internal rep.

Returns:

the TclObject with the given list value.

copy

public static TclObject copy(Interp interp,
                             TclObject list)

copy (TclListObjCopy) -- Makes a "pure list" copy of a list value. This provides for the C level a counterpart of the [lrange $list 0 end] command, while using internals details to be as efficient as possible. Side effects: None.

Parameters:

interp - Used to report errors if not null.

list - List object for which an element array is to be returned.

Returns:

Normally returns a new TclObject, that contains the same list value as 'list' does. The returned TclObject has a refCount of zero. If 'list' does not hold a list, null is returned, and if 'interp' is non-null, an error message is recorded there.

append

public static final void append(Interp interp,
                                TclObject tobj,
                                TclObject elemObj)
                         throws TclException

Tcl_ListObjAppendElement -> TclList.append() Appends a TclObject element to a list object.

Parameters:

interp - current interpreter.

tobj - the TclObject to append an element to.

elemObj - the element to append to the object.

Throws:

TclException - if tobj cannot be converted into a list.

append

public static final void append(Interp interp,
                                TclObject tobj,
                                TclObject[] objv,
                                int startIdx,
                                int endIdx)
                         throws TclException

TclList.append() Appends multiple TclObject elements to a list object.

Parameters:

interp - current interpreter.

tobj - the TclObject to append elements to.

objv - array containing elements to append.

startIdx - index to start appending values from

endIdx - index to stop appending values at

Throws:

TclException - if tobj cannot be converted into a list.

getLength

public static final int getLength(Interp interp,
                                  TclObject tobj)
                           throws TclException

Queries the length of the list. If tobj is not a list object, an attempt will be made to convert it to a list.

Parameters:

interp - current interpreter.

tobj - the TclObject to use as a list.

Returns:

the length of the list.

Throws:

TclException - if tobj is not a valid list.

getElements

public static TclObject[] getElements(Interp interp,
                                      TclObject tobj)
                               throws TclException

Returns a TclObject array of the elements in a list object. If tobj is not a list object, an attempt will be made to convert it to a list.

The objects referenced by the returned array should be treated as readonly and their ref counts are _not_ incremented; the caller must do that if it holds on to a reference.

Parameters:

interp - the current interpreter.

tobj - the list to sort.

Returns:

a TclObject array of the elements in a list object.

Throws:

TclException - if tobj is not a valid list.

getElementsList

public static ArrayList getElementsList(Interp interp,
                                        TclObject tobj)
                                 throws TclException

Returns an ArrayList of TclObject elements in a list object. If tobj is not a list object, an attempt will be made to convert it to a list.

Note that the actual internal ArrayList of a TclList object is returned, so be careful when changing the list.

Parameters:

interp - the current interpreter.

tobj - the list to sort.

Returns:

an ArrayList of elements in a list object.

Throws:

TclException - if tobj is not a valid list.

setElement

public static void setElement(Interp interp,
                              TclObject list,
                              int index,
                              TclObject value)
                       throws TclException

TclListObjSetElement -- Set a single element of a list to a specified value Side effects: Tcl_Panic if listPtr designates a shared object. Otherwise, attempts to convert it to a list with a non-shared internal rep. Decrements the ref count of the object at the specified index within the list, replaces with the object designated by valuePtr, and increments the ref count of the replacement object. It is the caller's responsibility to invalidate the string representation of the object.

Parameters:

interp - Tcl interpreter; used for error reporting if not null

list - List object in which element should be stored

index - Index of element to store

value - Tcl object to store in the designated list element

Throws:

TclException

lsetElement

public static void lsetElement(Interp interp,
                               TclObject list,
                               int index,
                               TclObject value)
                        throws TclException

TclListObjSetElement -- Set a single element of a list to a specified value in place (LsetCmd) Side effects: Tcl_Panic if listPtr designates a shared object. Otherwise, attempts to convert it to a list with a non-shared internal rep. Decrements the ref count of the object at the specified index within the list, replaces with the object designated by valuePtr, and increments the ref count of the replacement object. It is the caller's responsibility to invalidate the string representation of the object. This method also avoids extra toArray() of the internal ArrayList.

Parameters:

interp - Tcl interpreter; used for error reporting if not null

list - List object in which element should be stored

index - Index of element to store

value - Tcl object to store in the designated list element

Throws:

TclException

index

public static final TclObject index(Interp interp,
                                    TclObject tobj,
                                    int index)
                             throws TclException

This procedure returns a pointer to the index'th object from the list referenced by tobj. The first element has index 0. If index is negative or greater than or equal to the number of elements in the list, a null is returned. If tobj is not a list object, an attempt will be made to convert it to a list.

Parameters:

interp - current interpreter.

tobj - the TclObject to use as a list.

index - the index of the requested element.

Returns:

the the requested element.

Throws:

TclException - if tobj is not a valid list.

insert

public static final void insert(Interp interp,
                                TclObject tobj,
                                int index,
                                TclObject[] elements,
                                int from,
                                int to)
                         throws TclException

This procedure inserts the elements in elements[] into the list at the given index. If tobj is not a list object, an attempt will be made to convert it to a list.

Parameters:

interp - current interpreter.

tobj - the TclObject to use as a list.

index - the starting index of the insertion operation. <=0 means the beginning of the list. >= TclList.getLength(tobj) means the end of the list.

elements - the element(s) to insert.

from - insert elements starting from elements[from] (inclusive)

to - insert elements up to elements[to] (inclusive)

Throws:

TclException - if tobj is not a valid list.

replace

public static final void replace(Interp interp,
                                 TclObject tobj,
                                 int index,
                                 int count,
                                 TclObject[] elements,
                                 int from,
                                 int to)
                          throws TclException

This procedure replaces zero or more elements of the list referenced by tobj with the objects from an TclObject array. If tobj is not a list object, an attempt will be made to convert it to a list.

Parameters:

interp - current interpreter.

tobj - the TclObject to use as a list.

index - the starting index of the replace operation. <=0 means the beginning of the list. >= TclList.getLength(tobj) means the end of the list.

count - the number of elements to delete from the list. <=0 means no elements should be deleted and the operation is equivalent to an insertion operation.

elements - the element(s) to insert.

from - insert elements starting from elements[from] (inclusive)

to - insert elements up to elements[to] (inclusive)

Throws:

TclException - if tobj is not a valid list.

sort

public static void sort(Interp interp,
                        TclObject tobj,
                        int sortMode,
                        int sortIndex,
                        boolean sortIncreasing,
                        boolean unique,
                        String command)
                 throws TclException

Sorts the list according to the sort mode and (optional) sort command. If tobj is not a list object, an attempt will be made to convert it to a list.

Parameters:

interp - the current interpreter.

tobj - the list to sort.

sortMode - the sorting mode.

sortIncreasing - true if to sort the elements in increasing order.

unique - true if only the last set of duplicate elements found in the list have to be retained

command - the command to compute the order of two elements.

Throws:

TclException - if tobj is not a valid list.