Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tcl_ObjType(3)		    Tcl	Library	Procedures		Tcl_ObjType(3)


       Tcl_RegisterObjType,  Tcl_GetObjType,  Tcl_AppendAllObjTypes,  Tcl_Con-
       vertToType  - manipulate	Tcl object types

       #include	<tcl.h>


       Tcl_ObjType *

       Tcl_AppendAllObjTypes(interp, objPtr)

       Tcl_ConvertToType(interp, objPtr, typePtr)

       Tcl_ObjType *typePtr (in)	  Points to the	 structure  containing
					  information  about  the  Tcl	object
					  type.	 This storage must  live  for-
					  ever,	 typically by being statically

       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 report-

       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_Convert-
					  ToType, this	points	to  an	object
					  that	must have been the result of a
					  previous call	to Tcl_NewObj.

       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  al-
       ready  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  sec-
       tion 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-

       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  ob- |
       jPtr-_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 |

       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-
       ture  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 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 member contains the address of a function called to
       create a	valid internal representation from an object's	string	repre-

	      typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *interp,
		      Tcl_Obj *objPtr);

       If an internal representation cannot be created from the	string,	it re-
       turns 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 in-
       ternal representation, and returns TCL_OK.  Before setting the new  in-
       ternal representation, the setFromAnyProc must free any internal	repre-
       sentation 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

       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 member contains the	address	of a  function	called
       to  create a valid string representation	from an	object's internal rep-

	      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 al-
       locates and copies the string representation to just  enough  space  to
       hold  it.  A pointer to the allocated space is stored in	the bytes mem-

       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 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 so-
       phisticated scheme to continue sharing storage as much as it reasonably

       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  in-
       ternal representation does not require freeing.	The freeIntRepProc im-
       plementation 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

       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount

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

Tcl				      8.0			Tcl_ObjType(3)


Want to link to this manual page? Use this URL:

home | help