Ubuntu Manpage: Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType

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