NAME

       Tcl_RegisterObjType,   Tcl_GetObjType,   Tcl_AppendAllObj­
       Types, 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  struc­
                                           ture containing infor­
                                           mation about  the  Tcl
                                           object   type.    This
                                           storage must must live
                                           forever,  typically by
                                           being statically allo­
                                           cated.

       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_AppendAllObj­
                                           Types, 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.
_________________________________________________________________


       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  containes  a type with the same name as in
       typePtr, it is replaced with the new type.   The  Tcl_Obj­
       Type 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 represen­
       tation 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
       generic Tcl object code:

       The  setFromAnyProc member contains the address of a func­
       tion 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 set­
       FromAnyProc  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 set­
       FromAnyProc  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  struc­
       ture.

       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  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  con­
       struct 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  func­
       tion  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  dupIn­
       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 refer­
       ences).

       The freeIntRepProc member contains the address of a  func­
       tion 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.other­
       ValuePtr  that points to an array of pointers to each ele­
       ment in the list.  The list type's  freeIntRepProc  decre­
       ments  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 rep­
       resentation, type conversion