Tcl_ObjType(3)       Tcl Library Procedures        Tcl_ObjType(3)



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


     #include <tcl.h>


     Tcl_ObjType *

     Tcl_AppendAllObjTypes(interp, objPtr)

     Tcl_ConvertToType(interp, objPtr, typePtr)


     Tcl_ObjType *typePtr (in)          Points to  the  structure
                                        containing    information
                                        about  the   Tcl   object
                                        type.   This storage must
                                        live  forever,  typically
                                        by being statically allo-

     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
                                        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                     Last change: 8.0                        1

Tcl_ObjType(3)       Tcl Library Procedures        Tcl_ObjType(3)

     The procedures in this man page  manage  Tcl  object  types.
     They  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 that Tcl_GetObjType can look up by
     name.  There are other object  types  supported  by  Tcl  as
     well,  which  Tcl  chooses  not to register.  Extensions can
     likewise choose to register the object types they create  or
     not.  The argument typePtr points to a Tcl_ObjType structure
     that describes the new type by giving its name and  by  sup-
     plying  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_GetObjType  returns  a   pointer   to   the   registered
     Tcl_ObjType  with name typeName.  It returns NULL if no type
     with that name is registered.

     Tcl_AppendAllObjTypes appends the name  of  each  registered
     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 representa-
     tion for objPtr appropriate for the target type typePtr  and
     sets  its  typePtr  member  as  determined  by  calling  the
     typePtr->setFromAnyProc routine. 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.  Oth-
     erwise, 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).                           |

     In many cases, the typePtr->setFromAnyProc routine will  set  |
     objPtr->typePtr  to  the argument value typePtr, but that is  |
     no longer guaranteed.  The setFromAnyProc is free to set the  |
     internal  representation  for  objPtr to make use of another  |
     related Tcl_ObjType, if it sees fit.


     Extension writers can define new object  types  by  defining
     four  procedures and initializing a Tcl_ObjType structure to
     describe the  type.   Extension  writers  may  also  pass  a
     pointer     to     their     Tcl_ObjType     structure    to
     Tcl_RegisterObjType if they wish to permit other  extensions
     to look up their Tcl_ObjType by name with the Tcl_GetObjType

Tcl                     Last change: 8.0                        2

Tcl_ObjType(3)       Tcl Library Procedures        Tcl_ObjType(3)

     routine.  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.
     When  a type is registered, this is the name used by callers
     of Tcl_GetObjType to  lookup  the  type.   For  unregistered
     types,  the  name field is primarily of value for debugging.
     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 cannot  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  the  Tcl_ObjType  struct corresponding to the new
     internal representation, 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 built-in Tcl  list
     type  gets an up-to-date string representation for objPtr by
     calling Tcl_GetStringFromObj.  It parses the string to  ver-
     ify  it is in a valid list format and to obtain each element
     value in the list, and, if this succeeds,  stores  the  list
     elements   in  objPtr's  internal  representation  and  sets
     objPtr's  typePtr  member  to  point  to  the  list   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

Tcl                     Last change: 8.0                        3

Tcl_ObjType(3)       Tcl Library Procedures        Tcl_ObjType(3)

     The setFromAnyProc member may be set to NULL,  if  the  rou-
     tines making use of the internal representation have no need
     to derive that internal  representation  from  an  arbitrary
     string  value.   However, in this case, passing a pointer to
     the type to Tcl_ConvertToType() will lead to a panic, so  to
     avoid this possibility, the type should not be registered.

     The updateStringProc member contains the address of a  func-
     tion  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, and to have no null bytes
     before  that;  this  allows  string  representations  to  be
     treated as conventional null character-terminated C strings.
     These restrictions are easily met by  using  Tcl's  internal
     UTF  encoding  for  the  string  representation, same as one
     would do for other Tcl routines accepting string  values  as
     arguments.   Storage for the byte array must be allocated in
     the heap  by  Tcl_Alloc  or  ckalloc.   Note  that  updateS-
     tringProcs  must  allocate  enough  storage for the string's
     bytes and the terminating null byte.

     The updateStringProc for Tcl's  built-in  double  type,  for
     example,  calls Tcl_PrintDouble to write to a buffer of size
     TCL_DOUBLE_SPACE,  then  allocates  and  copies  the  string
     representation  to  just enough space to hold it.  A pointer
     to the allocated space is stored in the bytes member.

     The updateStringProc member may be set to NULL, if the  rou-
     tines  making use of the internal representation are written
     so that the  string  representation  is  never  invalidated.
     Failure  to  meet  this  obligation  will  lead to panics or
     crashes when Tcl_GetStringFromObj or other similar  routines
     ask for the string representation.

     The dupIntRepProc member contains the address of a  function
     called to copy an internal representation from one object to

          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

Tcl                     Last change: 8.0                        4

Tcl_ObjType(3)       Tcl Library Procedures        Tcl_ObjType(3)

     object type determines what copying its internal representa-
     tion means.

     For example, the dupIntRepProc for the Tcl integer type sim-
     ply  copies an integer.  The built-in list type's dupIntRep-
     Proc uses a far more sophisticated scheme to continue  shar-
     ing storage as much as it reasonably can.

     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, the list  type's  freeIntRepProc  respects  the
     storage  sharing  scheme established by the dupIntRepProc so
     that it only frees storage when the last object  sharing  it
     is being freed.

     The freeIntRepProc member can be set  to  NULL  to  indicate
     that  the  internal representation does not require freeing.
     The freeIntRepProc implementation must not access the  bytes
     member  of the object, since Tcl makes its own internal uses
     of that field during object deletion.  The defined tasks for
     the freeIntRepProc have no need to consult the bytes member.


     Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount


     internal  representation,  object,   object   type,   string
     representation, type conversion

Tcl                     Last change: 8.0                        5

Man(1) output converted with man2html