Tcl_RegisterObjType,  Tcl_GetObjType,  Tcl_AppendAllObjTypes,  Tcl_Con-
       vertToType  - 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  for-
                                           ever, 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
       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 proce-
       dure 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 proce-
       dures, 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_GetObj-
       Type 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  repre-
       sentation.
              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 success-
       ful, 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  exam-
       ple, 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 type-
       Ptr  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  rep-
       resentation.
              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 representa-
       tion's byte array to have a null after the last byte, at offset length;
       representation.  Before the call, srcPtr's internal  representation  is
       valid  and dupPtr's is not.  srcPtr's object type determines what copy-
       ing 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  inter-
       nalRep.otherValuePtr  that  points to an array of pointers to each ele-
       ment in the list.  The list type's freeIntRepProc decrements the refer-
       ence count for each element object (since the list will no longer refer
       to those objects), then deallocates the storage for the array of point-
       ers.  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



Tcl                                   8.0                       Tcl_ObjType(3)