Ubuntu Manpage: Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl

NAME

       Tcl_RegisterObjType,    Tcl_GetObjType,    Tcl_AppendAllObjTypes,   Tcl_ConvertToType    -
       manipulate Tcl object types

SYNOPSIS

       #include <tcl.h>

       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 live forever,
                                           typically by being statically allocated.

       CONST 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.  Do not release objPtr's old internal representation unless
       you replace it with a new one or reset the typePtr member to NULL.

       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 or ckalloc.  Note that
       updateStringProcs 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.

KEYWORDS