ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).



Tcl_ObjType(3)                             Tcl Library Procedures                             Tcl_ObjType(3)



____________________________________________________________________________________________________________

NAME
       Tcl_RegisterObjType,  Tcl_GetObjType,  Tcl_AppendAllObjTypes,  Tcl_ConvertToType   -  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 live forever, typically by being
                                           statically allocated.

       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  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 ref-erenced referenced
       erenced  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
       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 conver-sion, conversion,
       sion,  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).


THE TCL_OBJTYPE STRUCTURE
       Extension writers can define new object types by defining four procedures, 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_GetObjType 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 repre-sentation representation
       sentation from an object's string representation.
              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  mes-sage message
       sage  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
       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  call-ing calling
       ing  the  old  type's  freeIntRepProc  if  it is not NULL.  As an example, the setFromAnyProc for the
       builtin Tcl integer type gets an up-to-date string representation  for  objPtr  by  calling  Tcl_Get-StringFromObj. Tcl_GetStringFromObj.
       StringFromObj.   It  parses the string to obtain an integer and, if this succeeds, stores the integer
       in objPtr's internal representation and sets objPtr's typePtr 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 the typePtr member to NULL.

       The updateStringProc member contains the address of a function called to create a valid string repre-sentation representation
       sentation 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;  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 or ckalloc.  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 representa-tion. representation.
       tion.

       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 copying 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 ref-erence reference
       erence 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 internalRep.otherValuePtr that points to an array of pointers to each element  in  the  list.
       The list type's freeIntRepProc decrements the reference count for each element object (since the list
       will no longer refer to those objects), then deallocates the storage for the array of pointers.   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)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.