<HTML><HEAD><TITLE>Tcl Library Procedures - Tcl_ObjType manual page</TITLE></HEAD><BODY>
<H3><A NAME="M2">NAME</A></H3>
Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType - manipulate Tcl object types
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include <tcl.h></B><BR>
<B>Tcl_RegisterObjType</B>(<I>typePtr</I>)<BR>
Tcl_ObjType *<BR>
<B>Tcl_GetObjType</B>(<I>typeName</I>)<BR>
int<BR>
<B>Tcl_AppendAllObjTypes</B>(<I>interp, objPtr</I>)<BR>
int<BR>
<B>Tcl_ConvertToType</B>(<I>interp, objPtr, typePtr</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL>
<P><DT>Tcl_ObjType <B>*typePtr</B> (in)<DD>
Points to the structure containing information about the Tcl object type.
This storage must must live forever,
typically by being statically allocated.
<P><DT>char <B>*typeName</B> (in)<DD>
The name of a Tcl object type that <B>Tcl_GetObjType</B> should look up.
<P><DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*interp</B> (in)<DD>
Interpreter to use for error reporting.
<P><DT>Tcl_Obj <B>*objPtr</B> (in)<DD>
For <B>Tcl_AppendAllObjTypes</B>, this points to the object onto which
it appends the name of each object type as a list element.
For <B>Tcl_ConvertToType</B>, this points to an object that
must have been the result of a previous call to <B><A HREF="../TclLib/Object.htm">Tcl_NewObj</A></B>.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
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.
<P>
<B>Tcl_RegisterObjType</B> registers a new Tcl object type
in the table of all object types supported by Tcl.
The argument <I>typePtr</I> 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 containes a type
with the same name as in <I>typePtr</I>,
it is replaced with the new type.
The Tcl_ObjType structure is described
in the section <B>THE TCL_OBJTYPE STRUCTURE</B> below.
<P>
<B>Tcl_GetObjType</B> returns a pointer to the Tcl_ObjType
with name <I>typeName</I>.
It returns NULL if no type with that name is registered.
<P>
<B>Tcl_AppendAllObjTypes</B> appends the name of each object type
as a list element onto the Tcl object referenced by <I>objPtr</I>.
The return value is <B>TCL_OK</B> unless there was an error
converting <I>objPtr</I> to a list object;
in that case <B>TCL_ERROR</B> is returned.
<P>
<B>Tcl_ConvertToType</B> converts an object from one type to another
if possible.
It creates a new internal representation for <I>objPtr</I>
appropriate for the target type <I>typePtr</I>
and sets its <I>typePtr</I> member to that type.
Any internal representation for <I>objPtr</I>'s old type is freed.
If an error occurs during conversion, it returns <B>TCL_ERROR</B>
and leaves an error message in the result object for <I>interp</I>
unless <I>interp</I> is NULL.
Otherwise, it returns <B>TCL_OK</B>.
Passing a NULL <I>interp</I> allows this procedure to be used
as a test whether the conversion can be done (and in fact was done).
<H3><A NAME="M6">THE TCL_OBJTYPE STRUCTURE</A></H3>
Extension writers can define new object types by defining four
procedures,
initializing a Tcl_ObjType structure to describe the type,
and calling <B>Tcl_RegisterObjType</B>.
The <B>Tcl_ObjType</B> structure is defined as follows:
<PRE>typedef struct Tcl_ObjType {
char *<I>name</I>;
Tcl_FreeInternalRepProc *<I>freeIntRepProc</I>;
Tcl_DupInternalRepProc *<I>dupIntRepProc</I>;
Tcl_UpdateStringProc *<I>updateStringProc</I>;
Tcl_SetFromAnyProc *<I>setFromAnyProc</I>;
} Tcl_ObjType;</PRE>
<P>
The <I>name</I> member describes the name of the type, e.g. <B>int</B>.
Extension writers can look up an object type using its name
with the <B>Tcl_GetObjType</B> procedure.
The remaining four members are pointers to procedures
called by the generic Tcl object code:
<P>
The <I>setFromAnyProc</I> member contains the address of a function
called to create a valid internal representation
from an object's string representation.
<PRE>typedef int (Tcl_SetFromAnyProc) (<A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<I>interp</I>, Tcl_Obj *<I>objPtr</I>);</PRE>
If an internal representation can't be created from the string,
it returns <B>TCL_ERROR</B> and puts a message
describing the error in the result object for <I>interp</I>
unless <I>interp</I> is NULL.
If <I>setFromAnyProc</I> is successful,
it stores the new internal representation,
sets <I>objPtr</I>'s <I>typePtr</I> member to point to
<I>setFromAnyProc</I>'s <B>Tcl_ObjType</B>, and returns <B>TCL_OK</B>.
Before setting the new internal representation,
the <I>setFromAnyProc</I> must free any internal representation
of <I>objPtr</I>'s old type;
it does this by calling the old type's <I>freeIntRepProc</I>
if it is not NULL.
As an example, the <I>setFromAnyProc</I> for the builtin Tcl integer type
gets an up-to-date string representation for <I>objPtr</I>
by calling <B><A HREF="../TclLib/StringObj.htm">Tcl_GetStringFromObj</A></B>.
It parses the string to obtain an integer and,
if this succeeds,
stores the integer in <I>objPtr</I>'s internal representation
and sets <I>objPtr</I>'s <I>typePtr</I> member to point to the integer type's
Tcl_ObjType structure.
<P>
The <I>updateStringProc</I> member contains the address of a function
called to create a valid string representation
from an object's internal representation.
<PRE>typedef void (Tcl_UpdateStringProc) (Tcl_Obj *<I>objPtr</I>);</PRE>
<I>objPtr</I>'s <I>bytes</I> member is always NULL when it is called.
It must always set <I>bytes</I> non-NULL before returning.
We require the string representation's byte array
to have a null after the last byte, at offset <I>length</I>;
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 <B><A HREF="../TclLib/Alloc.htm">Tcl_Alloc</A></B>.
Note that <I>updateStringProc</I>s must allocate
enough storage for the string's bytes and the terminating null byte.
The <I>updateStringProc</I> for Tcl's builtin list type, for example,
builds an array of strings for each element object
and then calls <B><A HREF="../TclLib/SplitList.htm">Tcl_Merge</A></B>
to construct a string with proper Tcl list structure.
It stores this string as the list object's string representation.
<P>
The <I>dupIntRepProc</I> member contains the address of a function
called to copy an internal representation from one object to another.
<PRE>typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *<I>srcPtr</I>, Tcl_Obj *<I>dupPtr</I>);</PRE>
<I>dupPtr</I>'s internal representation is made a copy of <I>srcPtr</I>'s
internal representation.
Before the call,
<I>srcPtr</I>'s internal representation is valid and <I>dupPtr</I>'s is not.
<I>srcPtr</I>'s object type determines what
copying its internal representation means.
For example, the <I>dupIntRepProc</I> for the Tcl integer type
simply copies an integer.
The builtin list type's <I>dupIntRepProc</I>
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).
<P>
The <I>freeIntRepProc</I> member contains the address of a function
that is called when an object is freed.
<PRE>typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *<I>objPtr</I>);</PRE>
The <I>freeIntRepProc</I> 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 <I>internalRep.otherValuePtr</I>
that points to an array of pointers to each element in the list.
The list type's <I>freeIntRepProc</I> 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 <I>freeIntRepProc</I> member can be set to NULL
to indicate that the internal representation does not require freeing.
<H3><A NAME="M7">SEE ALSO</A></H3>
<B><A HREF="../TclLib/Object.htm">Tcl_NewObj</A></B>, <B><A HREF="../TclLib/Object.htm">Tcl_DecrRefCount</A></B>, <B><A HREF="../TclLib/Object.htm">Tcl_IncrRefCount</A></B>
<H3><A NAME="M8">KEYWORDS</A></H3>
<A href="../Keywords/I.htm#internal representation">internal representation</A>, <A href="../Keywords/O.htm#object">object</A>, <A href="../Keywords/O.htm#object type">object type</A>, <A href="../Keywords/S.htm#string representation">string representation</A>, <A href="../Keywords/T.htm#type conversion">type conversion</A>
<HR><PRE>
<A HREF="../copyright.htm">Copyright</A> © 1996-1997 Sun Microsystems, Inc.
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
</BODY></HTML>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
bd5c3d824c3db63ffd9226c15941e6ad
>
files
>
2070
