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 value types

       #include	<tcl.h>


       const Tcl_ObjType *

       Tcl_AppendAllObjTypes(interp, objPtr)

       Tcl_ConvertToType(interp, objPtr, typePtr)

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

       const char *typeName (in)	  The name of a	Tcl  value  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  value onto which it
					  appends the name of each value  type
					  as a list element.  For Tcl_Convert-
					  ToType, this points to a value  that
					  must	have been the result of	a pre-
					  vious	call to	Tcl_NewObj.

       The procedures in this man page manage Tcl value	types  (sometimes  re-
       ferred  to  as  object  types  or Tcl_ObjTypes for historical reasons).
       They are	used to	register new value types, look	up  types,  and	 force
       conversions from	one type to another.

       Tcl_RegisterObjType  registers a	new Tcl	value type in the table	of all
       value types that	Tcl_GetObjType can look	up by name.  There  are	 other
       value  types  supported by Tcl as well, which Tcl chooses not to	regis-
       ter.  Extensions	can likewise choose to register	the value  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 value type as
       a  list	element	 onto  the Tcl value referenced	by objPtr.  The	return
       value is	TCL_OK unless there was	an error converting objPtr to  a  list
       value; in that case TCL_ERROR is	returned.

       Tcl_ConvertToType  converts  a value 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
       value  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 value 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 {
		  const	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 value code:

       The setFromAnyProc member contains the address of a function called  to
       create  a valid internal	representation from a value's string represen-

	      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
       value 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 a value's internal	repre-

	      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	value 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 value type determines what copying
       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 a value is freed.

	      typedef void Tcl_FreeInternalRepProc(
		      Tcl_Obj *objPtr);

       The  freeIntRepProc function can	deallocate the storage for the value's
       internal	representation and do other type-specific processing necessary
       when a value 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 value 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 value, since Tcl
       makes its own internal uses of that field during	value  deletion.   The
       defined	tasks for the freeIntRepProc have no need to consult the bytes

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

       internal	representation,	value, value type, string representation, type

Tcl				      8.0			Tcl_ObjType(3)


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

home | help