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 [http://www.usenix.org/publications/library/proceedings/tcl96/full_papers/lewis/] for the orginal paper, written by Brian T. Lewis [http://www.intel.com/technology/techresearch/people/bios/lewis_b.htm].

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 ob 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
   * http://www.tcl.tk/man/tcl8.5/TclLib/Object.htm
   * http://www.tcl.tk/man/tcl8.5/TclLib/ObjectType.htm
----
[[[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

   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
   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 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 (copy 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.)''
   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.)

----
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:
   * [Managing the reference count of Tcl objects]
   * [How to write C-coded extensions for Tcl]
   * [Creating and Using Tcl Handles in C Extensions]
   * [How to embed Tcl in C applications]
   * [Islist Extension]
   * [32-bit integer overflow]
   * [Category Tcl Library]
----

[[[Category Concept]|[Category Internals]|[Category Tcl Library]]]