--- name: "ObjectType" section: "3tcl" platform: "linux" package: "tcl8.3-doc" version: "8.3.5-13" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/ObjectType/3tcl" --- # ObjectType(3tcl) manipulate Tcl object types ``` ``` ## NAME Tcl\_RegisterObjType, Tcl\_GetObjType, Tcl\_AppendAllObjTypes, Tcl\_ConvertToType - manipulate Tcl object types ## SYNOPSIS ``` #include Tcl_RegisterObjType(typePtr) Tcl_ObjType * Tcl_GetObjType(typeName) int Tcl_AppendAllObjTypes(interp, objPtr) int Tcl_ConvertToType(interp, objPtr, typePtr) ``` ## ARGUMENTS - Tcl\_ObjType *\*typePtr* (in) Points to the structure containing information about the Tcl object type. This storage must must live forever, typically by being statically allocated. - char *\*typeName* (in) The name of a Tcl object type that **Tcl\_GetObjType** should look up. - Tcl\_Interp *\*interp* (in) Interpreter to use for error reporting. - Tcl\_Obj *\*objPtr* (in) For **Tcl\_AppendAllObjTypes**, this points to the object onto which it appends the name of each object type as a list element. For **Tcl\_ConvertToType**, this points to an object that must have been the result of a previous call to **Tcl\_NewObj**. ``` ``` ## DESCRIPTION The procedures in this man page manage Tcl object types. The are used to register new object types, look up types, and force conversions from one type to another. **Tcl\_RegisterObjType** registers a new Tcl object type in the table of all object types supported by Tcl. The argument *typePtr* points to a Tcl\_ObjType structure that describes the new type by giving its name and by supplying pointers to four procedures that implement the type. If the type table already contains a type with the same name as in *typePtr*, it is replaced with the new type. The Tcl\_ObjType structure is described in the section **THE TCL\_OBJTYPE STRUCTURE** below. **Tcl\_GetObjType** returns a pointer to the Tcl\_ObjType with name *typeName*. It returns NULL if no type with that name is registered. **Tcl\_AppendAllObjTypes** appends the name of each object type as a list element onto the Tcl object referenced by *objPtr*. The return value is **TCL\_OK** unless there was an error converting *objPtr* to a list object; in that case **TCL\_ERROR** is returned. **Tcl\_ConvertToType** converts an object from one type to another if possible. It creates a new internal representation for *objPtr* appropriate for the target type *typePtr* and sets its *typePtr* member to that type. Any internal representation for *objPtr*'s old type is freed. If an error occurs during conversion, it returns **TCL\_ERROR** and leaves an error message in the result object for *interp* unless *interp* is NULL. Otherwise, it returns **TCL\_OK**. Passing a NULL *interp* allows this procedure to be used as a test whether the conversion can be done (and in fact was done). ## THE TCL\_OBJTYPE STRUCTURE Extension writers can define new object types by defining four procedures, initializing a Tcl\_ObjType structure to describe the type, and calling **Tcl\_RegisterObjType**. The **Tcl\_ObjType** structure is defined as follows: ``` typedef struct Tcl_ObjType { char *name; Tcl_FreeInternalRepProc *freeIntRepProc; Tcl_DupInternalRepProc *dupIntRepProc; Tcl_UpdateStringProc *updateStringProc; Tcl_SetFromAnyProc *setFromAnyProc; } Tcl_ObjType; ``` The *name* member describes the name of the type, e.g. **int**. Extension writers can look up an object type using its name with the **Tcl\_GetObjType** procedure. The remaining four members are pointers to procedures called by the generic Tcl object code: The *setFromAnyProc* member contains the address of a function called to create a valid internal representation from an object's string representation. ``` typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *interp, Tcl_Obj *objPtr); ``` If an internal representation can't be created from the string, it returns **TCL\_ERROR** and puts a message describing the error in the result object for *interp* unless *interp* is NULL. If *setFromAnyProc* is successful, it stores the new internal representation, sets *objPtr*'s *typePtr* member to point to *setFromAnyProc*'s **Tcl\_ObjType**, and returns **TCL\_OK**. Before setting the new internal representation, the *setFromAnyProc* must free any internal representation of *objPtr*'s old type; it does this by calling the old type's *freeIntRepProc* if it is not NULL. As an example, the *setFromAnyProc* for the builtin Tcl integer type gets an up-to-date string representation for *objPtr* by calling **Tcl\_GetStringFromObj**. It parses the string to obtain an integer and, if this succeeds, stores the integer in *objPtr*'s internal representation and sets *objPtr*'s *typePtr* member to point to the integer type's Tcl\_ObjType structure. The *updateStringProc* member contains the address of a function called to create a valid string representation from an object's internal representation. ``` typedef void (Tcl_UpdateStringProc) (Tcl_Obj *objPtr); ``` *objPtr*'s *bytes* member is always NULL when it is called. It must always set *bytes* non-NULL before returning. We require the string representation's byte array to have a null after the last byte, at offset *length*; this allows string representations that do not contain null bytes to be treated as conventional null character-terminated C strings. Storage for the byte array must be allocated in the heap by **Tcl\_Alloc**. Note that *updateStringProc*s must allocate enough storage for the string's bytes and the terminating null byte. The *updateStringProc* for Tcl's builtin list type, for example, builds an array of strings for each element object and then calls **Tcl\_Merge** to construct a string with proper Tcl list structure. It stores this string as the list object's string representation. The *dupIntRepProc* member contains the address of a function called to copy an internal representation from one object to another. ``` typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *srcPtr, Tcl_Obj *dupPtr); ``` *dupPtr*'s internal representation is made a copy of *srcPtr*'s internal representation. Before the call, *srcPtr*'s internal representation is valid and *dupPtr*'s is not. *srcPtr*'s object type determines what copying its internal representation means. For example, the *dupIntRepProc* for the Tcl integer type simply copies an integer. The builtin list type's *dupIntRepProc* allocates a new array that points at the original element objects; the elements are shared between the two lists (and their reference counts are incremented to reflect the new references). The *freeIntRepProc* member contains the address of a function that is called when an object is freed. ``` typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *objPtr); ``` The *freeIntRepProc* function can deallocate the storage for the object's internal representation and do other type-specific processing necessary when an object is freed. For example, Tcl list objects have an *internalRep.otherValuePtr* that points to an array of pointers to each element in the list. The list type's *freeIntRepProc* decrements the reference count for each element object (since the list will no longer refer to those objects), then deallocates the storage for the array of pointers. The *freeIntRepProc* member can be set to NULL to indicate that the internal representation does not require freeing. ## SEE ALSO Tcl\_NewObj, Tcl\_DecrRefCount, Tcl\_IncrRefCount ## KEYWORDS internal representation, object, object type, string representation, type conversion