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.

Currently, the following internal representations are supported: 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 invalidateStringlRep 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 of classes derrived from the InternalRep class, such as TclList.append() and TclInteger.set(), modify the contents of a TclObject. When you are about to call these methods to modify the value of a TclObject, you must call preserve (if you haven't already done so) and then call takeExclusive. takeExclusive will make a copy of the TclObject if it is shared. The TclObject returned by the takeExclusive will always have a reference count of 1.

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. This methods allows you to query the class of a returned object to determine what type of TclObject it is.
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 saves the value of a TclObject for later use. Each call to preserve will internally increment the "reference count" of the TclObject by one.
release: After saving the value of a TclObject for later use (via the preserve method), call the release method when you no longer need the TclObject's value. Each call to release will internally 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.)
takeExclusive: The takeExclusive method makes a copy of the TclObject if it is shared. The TclObject returned by the takeExclusive will always have a reference count of 1.

EQUIVALENT C FUNCTIONS

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

KEYWORDS

internal representation, object, object creation, object type, reference counting, string representation, type conversion

Copyright © 1996-1998 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.