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.
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 }
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:
Each Tcl_ObjType structure contains the following four function pointers plus a name.
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."