ABCDEFGHIJKLMNOPQRSTUVWXYZ

ObjectType

Tcl_ObjType(3)              Tcl Library Procedures              Tcl_ObjType(3)



______________________________________________________________________________

NAME
       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 must  live
                                           forever,  typically by being stati-
                                           cally 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 possi-
       ble.  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 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.

       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;
       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  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 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)