'''Tcl_Obj''' is the [C] structure that implements every [Tcl] value. ''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.'': -- attributed to [DKF] ** See Also ** [Creating and Using Tcl Handles in C Extensions]: [How to embed Tcl in C applications]: [Managing the reference count of Tcl objects]: [Tcl_Obj Deep Copy]: [Tcl_Obj refCount HOWTO]: [Tcl_Obj types list]: [Blessed Tcl_Obj Values]: [A Tcl_Obj Command Machine Code Generator]: [Tcl_Obj proposals]: Discussions of changes to the Tcl_Obj structure and its semantics are referred to [Tcl_Obj vs Command]: [Writing Extensions]: [Islist Extension]: [32-bit integer overflow]: [Category Tcl Library]: ** Documentation ** [http://www.usenix.org/legacy/publications/library/proceedings/tcl96/full_papers/lewis/%|%An On-the-fly Bytecode Compiler for Tcl] ,Brian T. Lewis ,1996: introduces Tcl_Obj [http://www.tcl.tk/man/tcl/TclLib/Object.htm%|%official reference for] Tcl_Obj and friends: [http://www.tcl.tk/man/tcl8.5/TclLib/ObjectType.htm%|%official reference for object types]: ** Description ** '''Tcl_Obj''' provides for both a string (UTF8) representation and an "internal" representation of the value, which is limited only by the constraints of the [C] language itself. Each Tcl_Obj carries information about the type of its internal representation, and how to perform a conversion from the string representation to the internal representation, and vice-versa. In this way, the string becomes the universal intermediate representation for conversions between types. To enhance performance, Tcl knows how to perform direct conversions between certain often-used types. A Tcl_Obj is 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 - a now obsolete facility. [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: 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]: 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). <> Concept | Internals | Tcl Library