Seth Woolley's Man Viewer

Tcl_RegisterObjType(3) - Tcl_AppendAllObjTypes, Tcl_ConvertToType, Tcl_GetObjType, Tcl_RegisterObjType - manipulate Tcl object types - man 3 Tcl_RegisterObjType

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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(1,8))      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(1,8))      The name of a Tcl object type  that
                                           Tcl_GetObjType should look(1,8,3 Search::Dict) up.

       Tcl_Interp    *interp     (in(1,8))      Interpreter   to   use   for  error(8,n)
                                           reporting.

       Tcl_Obj       *objPtr     (in(1,8))      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(1,8) this man(1,5,7) page manage Tcl object types.  The are used
       to register new object types, look(1,8,3 Search::Dict) up types, and force conversions from
       one type to another.

       Tcl_RegisterObjType registers a new Tcl object type in(1,8) 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(1,8)
       typePtr, it is replaced with the new type.  The  Tcl_ObjType  structure
       is described in(1,8) the section THE TCL_OBJTYPE STRUCTURE below.

       Tcl_GetObjType returns a pointer to the Tcl_ObjType with name typeName.
       It returns NULL if(3,n) 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(8,n) converting objPtr to a list object; in(1,8)
       that case TCL_ERROR is returned.

       Tcl_ConvertToType converts an object from one type to another if(3,n) 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(8,n)  occurs  during  conversion,  it  returns TCL_ERROR and leaves an
       error(8,n) message in(1,8) 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(1,8)
       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(1,8,3 Search::Dict) 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(3,n)  repre-
       sentation.
              typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *interp, Tcl_Obj *objPtr);
       If  an  internal  representation  can't  be created from the string(3,n), it
       returns TCL_ERROR and puts(3,n) a message describing the error(8,n) in(1,8) 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(3,n) it is not NULL.  As  an  exam-
       ple, the setFromAnyProc for the builtin Tcl integer type gets(3,n) an up-to-
       date string(3,n) representation for objPtr by calling  Tcl_GetStringFromObj.
       It parses the string(3,n) to obtain an integer and, if(3,n) this succeeds, stores
       the integer in(1,8) 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(1,7,1 tput) the typePtr member to NULL.

       The  updateStringProc  member contains the address of a function called
       to create a valid string(3,n) 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(7,n,1 builtins) bytes non-NULL before returning.  We require the string(3,n) representa-
       tion's byte array to have a null after the last byte, at offset length;
       this allows string(3,n) 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(1,8)  the  heap  by  Tcl_Alloc  or
       ckalloc.   Note that updateStringProcs must allocate enough storage for
       the string(3,n)'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(3,n)
       with  proper  Tcl  list  structure.   It stores this string(3,n) as the list
       object's string(3,n) 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(1,8) 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(7,n,1 builtins) 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(3,n)  representation,
       type conversion



Tcl                                   8.0                       Tcl_ObjType(3)

References for this manual (incoming links)