TclJava Library Procedures - TclObject manual page

The Java API to the Tcl interpreter is object-based -- in most cases, the values passed to and from the Tcl interpreter are instances of TclObject. This includes variable values and command arguments.

A TclObject is dual-ported: it behaves like a String but also holds an internal representation that can be manipulated more efficiently. For example, a TclList is represented as a TclObject that holds the list's string representation as well as a Vector to hold the objects for each list element. Dual-ported objects avoid most runtime type conversions. This improves the speed of many operations since an appropriate representation is immediately available.

A number internal representations are supported, including: TclBoolean, TclDouble, TclList, TclIndex, TclInteger, TclString and ReflectObject. Most of these internal representations have a newInstance() method, which can be used to create a new TclObject instance that contains the specific internal representation. You should always create TclObject instances with the newInstance() methods; use the "new" operator to create TclObject instances only when you are writing new internal representations.

The type of the internal representation of Tcl objects can mutate. Methods such as setInternalRep and invalidateStringRep are facilities for mutating the internal rep.

To improve memory efficiency, TclObject supports copy-on-write operations. When you need to save the value of a TclObject for later use, call the preserve method; when you no longer need its value, call the release method. Internally, each call to preserve will internally increment the "reference count" of the TclObject by one; conversely, each call to release decrements the reference count by one.

Some methods, such as TclList. append() and TclInteger.set(), modify the contents of a TclObject. These methods cannot be called with a shared TclObject argument. Before calling such a method, take care to duplicate any shared object argument.

Shared TclObject Example

import tcl.lang.*;

public class ListAppendCmd implements Command {
    public void 
    cmdProc(
        Interp interp,
        TclObject[] objv)
    throws TclException
    {
        TclObject obj = objv[1];
        if (obj.isShared())
            obj = obj.duplicate();
        TclList.append(interp, obj, TclString.newInstance("hi"));
        interp.setResult(obj);
        return;
    }
}

TclObject: The TclObject constructor creates a new TclObject with the internal representation of rep.
setInternalRep: The setInternalRep method changes the internal representation of the TclObject to the value rep.
getInternalRep: The getInternalRep method returns the internal representation of the TclObject. In most cases, one should not use this method to determine how to treat different types. Instead, the code should be written so that it attempts to convert to a given type and deals with a conversion failure. For example, an object that could be converted into a valid Tcl list might not have a TclList internal representation. One would need to attempt the conversion to see if it would be successful.
toString: The toString method returns the string representation of the TclObject.
invalidateStringRep: The invalidateStringRep method marks the String representation of the TclObject as invalid. This method should be called only by subclasses of the InternalRep prior to a call the setInternalRep.
preserve: The preserve method increments the "reference count" of a TclObject so that it can be used later. Each call to preserve should be matched by a call to release.
release: Invoke the release method when you no longer need access to a TclObject. Each call to release will decrement the "reference count" of the TclObject by one.
isShared: The isShared method returns true if the TclObject is shared (its reference count is greater than one.)
duplicate: The duplicate method returns a copy of the TclObject. The TclObject returned by duplicate will always have a reference count of 0.

EQUIVALENT C FUNCTIONS

Tcl_NewObj, Tcl_ConvertToType, TclObj.typePtr, Tcl_GetStringFromObj, Tcl_InvalidateStringRep, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared, Tcl_DuplicateObj

CLASS

CONSTRUCTORS

METHODS

ARGUMENTS

DESCRIPTION

EQUIVALENT C FUNCTIONS

SEE ALSO