  CLASS
    tcl.lang.TclObject -- the basic notion of an "object" in Tcl.
  CONSTRUCTORS
  METHODS
    TclObject(InternalRep rep)
    void setInternalRep(InternalRep rep)
    InternalRep getInternalRep()
    String toString()
    void invalidateStringRep()
    void preserve()
    void release()
    boolean isShared()
    TclObject takeExclusive()
  ARGUMENTS
  DESCRIPTION
    TclObject
    setInternalRep
    getInternalRep
    toString
    invalidateStringRep
    preserve
    release
    isShared
    takeExclusive
  EQUIVALENT C FUNCTIONS
  SEE ALSO
  KEYWORDS

### CLASS

tcl.lang.TclObject -- the basic notion of an "object" in Tcl.

### CONSTRUCTORS

TclObject

### METHODS

TclObject(InternalRep rep)

void setInternalRep(InternalRep rep)

InternalRep getInternalRep()

String toString()

void invalidateStringRep()

void preserve()

void release()

boolean isShared()

TclObject takeExclusive()

### ARGUMENTS

InternalRep rep ()
  Internal representation to be stored in newly created TclObject.

### DESCRIPTION

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

### SEE ALSO

InternalRep, TclBoolean, TclDouble, TclList, TclIndex, TclInteger, TclString, ReflectObject, Interp

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