manpagez: man pages & more
man ObjectType(3)
Home | html | info | man
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

       Points to the structure containing information  about  the  Tcl  object
       type.   This  storage  must live forever, typically by being statically
       allocated.  The name of a Tcl object type  that  Tcl_GetObjType  should
       look up.  Interpreter to use for error reporting.  For Tcl_AppendAllOb-
       jTypes, 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.  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 regis-
       ter.  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 supplying  point-
       ers  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  registered  Tcl_ObjType  with
       name  typeName.   It  returns  NULL if no type with that name is regis-
       tered.

       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 possi-
       ble.  It creates a new internal representation for  objPtr  appropriate
       for  the  target type typePtr and sets its typePtr member as determined
       by calling the typePtr->setFromAnyProc routine.  Any internal represen-
       tation  for objPtr's old type is freed.  If an error occurs during con-
       version, 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).

       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 representa-
       tion for objPtr to make use of another related Tcl_ObjType, if it  sees
       fit.


THE TCL_OBJTYPE STRUCTURE

       Extension  writers  can define new object types by defining four proce-
       dures and initializing a Tcl_ObjType structure to  describe  the  type.
       Extension  writers  may also pass a pointer to their Tcl_ObjType struc-
       tire to Tcl_RegisterObjType if they wish to permit other extensions  to
       look up their Tcl_ObjType by name with the Tcl_GetObjType 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 FIELD
       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 FIELD
       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 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 success-
       ful,  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 rep-
       resentation  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_Get-
       StringFromObj.  It parses the string to verify it is in  a  valid  list
       format  and to obtain each element value in the list, and, if this suc-
       ceeds, 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 NULL.

       The  setFromAnyProc  member  may be set to NULL, if the routines 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 FIELD
       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,
       and  to  have no null bytes before that; this allows string representa-
       tions  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  updateStringProcs  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 mem-
       ber.

       The updateStringProc member may be set to NULL, if the routines  making
       use  of the internal representation are written so that the string rep-
       resentation 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 FIELD
       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  built-in  list type's dupIntRepProc uses a far more
       sophisticated scheme to continue sharing storage as much as it  reason-
       ably can.

   THE FREEINTREPPROC FIELD
       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  shar-
       ing scheme established by the dupIntRepProc so that it only frees stor-
       age 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.


SEE ALSO

       Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)


KEYWORDS

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



Tcl                                   8.0                       Tcl_ObjType(3)

ObjectType 8.5.4 - Generated Tue Aug 19 20:57:24 CDT 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.