Tcl_Obj

This structure is the fundamental value used in the Tcl core, and represents a value that may have either a string (UTF8) representation, an arbitrary other representation (e.g. an integer if it is a number (integer/double), or a collection of values if it is a list, or whatever) or both, and may move between these representations pretty much at will. It is reference counted, and the allocator for it is very heavily tuned.

NEM - See [1] for the orginal paper, written by Brian T. Lewis [2].

It has a deeply unfortunate name, but the far more apt Tcl_Value was previously taken for handling user-defined expr functions...

RS thinks that the name is ok if one does not expect OO features, class membership etc. Objects have been there long before OO, and the name is certainly not under a monopoly (I'd object against that ;-). But the basic feature of Tcl_Obj's is that they have a string representation and possibly a problem-oriented one, but each can be regenerated from the other (also if you define your obj Obj types). If such type conversions occur frequently, this costs performance - the so-called shimmering occurs. E.g. see what happens to i below:

 for {set i 0} {$i<10} {incr i} { #here we need the integer rep
    puts [string length $i]      ;#here the string rep..
    puts [llength $i]            ;# and here the list rep, so int rep goes away 
 }

Related man pages

[CMcC] I've put together a summary page of Tcl_Objs current for 8.4, containing information culled from the source.

A Tcl_Obj is defined as a structure containing:

an integer refCount: representing the number of references to this Tcl_Obj
a char *bytes: being the string representation of the object (under the doctrine `everything's a string'). For a non-empty string, objv[i]->bytes points to Tcl_Alloc()ated memory. For an empty string, objv[i]->bytes points to a static char in the Tcl library that holds a NUL byte.
an integer length: being the length of the string representation in bytes (minus the extra byte for the terminating NUL)
a pointer to a Tcl_ObjType: which contains the type's name, and pointers to functions implementing the four fundamental operations which all Tcl_Obj instances are expected to implement.
a union internalRep: which is used to store up to two pointers of information which is opaque to Tcl.

Each Tcl_ObjType structure contains the following four function pointers plus a name.

freeIntRepProc: Called to free any storage for the type's internal rep. NULL if the internal rep does not need freeing.
dupIntRepProc: Called to create a new object as a copy of an existing object; NULL indicates that the default strategy (memcpy the whole internalRep union) is sufficient.
updateStringProc: Called to update the string rep from the type's internal representation. (Not sure what NULL means for this; IME that's not an especially good idea. DKF: It's OK provided you never ever set the bytes field to NULL.)
setFromAnyProc: Called to convert the object's internal rep to this type. Frees the internal rep of the old type. Returns TCL_ERROR on failure. NULL indicates that objects of this type can't normally be created (typically because extra context is needed.)

DKF: Note also that you must not allocate a Tcl_Obj manually. Always call Tcl_NewObj (or one of its close relatives, such as Tcl_NewIntObj) to do it for you. This is because Tcl uses a special memory management engine for them that is tuned to be extra efficient — useful because Tcl uses these things a lot — and that's only accessible through Tcl_NewObj (or some wholly internal APIs that aren't exposed outside the Tcl library).

Apparently DKF once said: "Tcl_Obj's are like storks. They have two legs, the internal representation and the string representation. They can stand on either leg, or on both."

Discussions of changes to the Tcl_Obj structure and its semantics are referred to Tcl_Obj proposals.

See also edit