TclObjType(3) Tcl Library Procedures TclObjType(3)

NAME
       TclRegisterObjType,  TclGetObjType,  TclAppendAllObjTypes,  TclCon-
       vertToType  - manipulate Tcl object types

SYNOPSIS
       ##iinncclluuddee <>

       TTccllRReeggiisstteerrOObbjjTTyyppee(typePtr)

       TclObjType *
       TTccllGGeettOObbjjTTyyppee(typeName)

       int
       TTccllAAppppeennddAAllllOObbjjTTyyppeess(interp, objPtr)

       int
       TTccllCCoonnvveerrttTTooTTyyppee(interp, objPtr, typePtr)

AARRGGUUMMEENNTTSS
       TclObjType   *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
                                           TTccllGGeettOObbjjTTyyppee should look up.

       TclInterp    *interp     (in)      Interpreter   to   use   for  error
                                           reporting.

       TclObj       *objPtr     (in)      For   TTccllAAppppeennddAAllllOObbjjTTyyppeess,   this
                                           points  to the object onto which it
                                           appends the  name  of  each  object
                                           type   as   a  list  element.   For
                                           TTccllCCoonnvveerrttTTooTTyyppee, this  points  to
                                           an  object  that must have been the
                                           result  of  a  previous   call   to
                                           TTccllNNeewwOObbjj.



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.

       TTccllRReeggiisstteerrOObbjjTTyyppee registers a new Tcl object type in the table of all
       object types supported by  Tcl.   The  argument  typePtr  points  to  a
       TclObjType  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  TclObjType  structure
       is described in the section TTHHEE TTCCLLOOBBJJTTYYPPEE SSTTRRUUCCTTUURREE below.

       TTccllGGeettOObbjjTTyyppee returns a pointer to the TclObjType with name typeName.
       It returns NULL if no type with that name is registered.

       TTccllAAppppeennddAAllllOObbjjTTyyppeess appends the name of each object type  as  a  list
       element  onto the Tcl object referenced by objPtr.  The return value is
       TTCCLLOOKK unless there was an error converting objPtr to a list object; in
       that case TTCCLLEERRRROORR is returned.

       TTccllCCoonnvveerrttTTooTTyyppee 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 TTCCLLEERRRROORR and leaves an
       error message in the result object for interp unless  interp  is  NULL.
       Otherwise, it returns TTCCLLOOKK.  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).


TTHHEE TTCCLLOOBBJJTTYYPPEE SSTTRRUUCCTTUURREE
       Extension  writers  can define new object types by defining four proce-
       dures, initializing a TclObjType structure to describe the  type,  and
       calling  TTccllRReeggiisstteerrOObbjjTTyyppee.   The TTccllOObbjjTTyyppee structure is defined as
       follows:
              typedef struct TclObjType {
                char *name;
                TclFreeInternalRepProc *freeIntRepProc;
                TclDupInternalRepProc *dupIntRepProc;
                TclUpdateStringProc *updateStringProc;
                TclSetFromAnyProc *setFromAnyProc;
              } TclObjType;

       The name member describes the name of the type,  e.g.  iinntt.   Extension
       writers  can look up an object type using its name with the TTccllGGeettOObbjj-
       TTyyppee 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 (TclSetFromAnyProc) (TclInterp *interp, TclObj *objPtr);
       If  an  internal  representation  can't  be created from the string, it
       returns TTCCLLEERRRROORR 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 TTccllOObbjjTTyyppee, and returns TTCCLLOOKK.
       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  TTccllGGeettSSttrriinnggFFrroommOObbjj.
       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 TclObjType 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 (TclUpdateStringProc) (TclObj *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  TTccllAAlllloocc  or
       cckkaalllloocc.   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 TTccllMMeerrggee 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 (TclDupInternalRepProc) (TclObj *srcPtr, TclObj *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 (TclFreeInternalRepProc) (TclObj *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
       TclNewObj, TclDecrRefCount, TclIncrRefCount


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



Tcl                                   8.0                       TclObjType(3)