1Tcl_ObjType(3)              Tcl Library Procedures              Tcl_ObjType(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_RegisterObjType,  Tcl_GetObjType,  Tcl_AppendAllObjTypes,  Tcl_Con‐
9       vertToType  - manipulate Tcl object types
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_RegisterObjType(typePtr)
15
16       Tcl_ObjType *
17       Tcl_GetObjType(typeName)
18
19       int
20       Tcl_AppendAllObjTypes(interp, objPtr)
21
22       int
23       Tcl_ConvertToType(interp, objPtr, typePtr)
24

ARGUMENTS

26       Tcl_ObjType *typePtr (in)          Points to the  structure  containing
27                                          information  about  the  Tcl  object
28                                          type.  This storage must  live  for‐
29                                          ever,  typically by being statically
30                                          allocated.
31
32       const char *typeName (in)          The name of a Tcl object  type  that
33                                          Tcl_GetObjType should look up.
34
35       Tcl_Interp *interp (in)            Interpreter to use for error report‐
36                                          ing.
37
38       Tcl_Obj *objPtr (in)               For   Tcl_AppendAllObjTypes,    this
39                                          points  to  the object onto which it
40                                          appends the name of each object type
41                                          as a list element.  For Tcl_Convert‐
42                                          ToType, this  points  to  an  object
43                                          that  must have been the result of a
44                                          previous call to Tcl_NewObj.
45_________________________________________________________________
46
47

DESCRIPTION

49       The procedures in this man page manage Tcl object types.  They are used
50       to register new object types, look up types, and force conversions from
51       one type to another.
52
53       Tcl_RegisterObjType registers a new Tcl object type in the table of all
54       object  types that Tcl_GetObjType can look up by name.  There are other
55       object types supported by Tcl as well, which Tcl chooses not to  regis‐
56       ter.   Extensions can likewise choose to register the object types they
57       create or not.  The argument typePtr points to a Tcl_ObjType  structure
58       that  describes the new type by giving its name and by supplying point‐
59       ers to four procedures that implement the  type.   If  the  type  table
60       already  contains  a  type  with  the  same  name  as in typePtr, it is
61       replaced with the new type.  The Tcl_ObjType structure is described  in
62       the section THE TCL_OBJTYPE STRUCTURE below.
63
64       Tcl_GetObjType  returns  a  pointer  to the registered Tcl_ObjType with
65       name typeName.  It returns NULL if no type with  that  name  is  regis‐
66       tered.
67
68       Tcl_AppendAllObjTypes  appends  the name of each registered object type
69       as a list element onto the Tcl object referenced by objPtr.  The return
70       value  is  TCL_OK unless there was an error converting objPtr to a list
71       object; in that case TCL_ERROR is returned.
72
73       Tcl_ConvertToType converts an object from one type to another if possi‐
74       ble.   It  creates a new internal representation for objPtr appropriate
75       for the target type typePtr and sets its typePtr member  as  determined
76       by calling the typePtr->setFromAnyProc routine.  Any internal represen‐
77       tation for objPtr's old type is freed.  If an error occurs during  con‐
78       version, it returns TCL_ERROR and leaves an error message in the result
79       object for interp unless interp is NULL.  Otherwise, it returns TCL_OK.
80       Passing  a  NULL  interp  allows  this  procedure  to be used as a test
81       whether the conversion can be done (and in fact was done).              │
82
83       In  many  cases,   the   typePtr->setFromAnyProc   routine   will   set │
84       objPtr->typePtr  to  the  argument value typePtr, but that is no longer │
85       guaranteed.  The setFromAnyProc is free to set the internal representa‐ │
86       tion  for objPtr to make use of another related Tcl_ObjType, if it sees │
87       fit.
88

THE TCL_OBJTYPE STRUCTURE

90       Extension writers can define new object types by defining  four  proce‐
91       dures  and  initializing  a Tcl_ObjType structure to describe the type.
92       Extension writers may also pass a pointer to their  Tcl_ObjType  struc‐
93       tire  to Tcl_RegisterObjType if they wish to permit other extensions to
94       look up their Tcl_ObjType by name with the Tcl_GetObjType routine.  The
95       Tcl_ObjType structure is defined as follows:
96
97              typedef struct Tcl_ObjType {
98                  char *name;
99                  Tcl_FreeInternalRepProc *freeIntRepProc;
100                  Tcl_DupInternalRepProc *dupIntRepProc;
101                  Tcl_UpdateStringProc *updateStringProc;
102                  Tcl_SetFromAnyProc *setFromAnyProc;
103              } Tcl_ObjType;
104
105   THE NAME FIELD
106       The  name member describes the name of the type, e.g. int.  When a type
107       is registered, this is the name used by callers  of  Tcl_GetObjType  to
108       lookup  the  type.  For unregistered types, the name field is primarily
109       of value for debugging.  The remaining four  members  are  pointers  to
110       procedures called by the generic Tcl object code:
111
112   THE SETFROMANYPROC FIELD
113       The  setFromAnyProc member contains the address of a function called to
114       create a valid internal representation from an object's  string  repre‐
115       sentation.
116
117              typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *interp,
118                      Tcl_Obj *objPtr);
119
120       If  an  internal  representation  cannot be created from the string, it
121       returns TCL_ERROR and puts a message describing the error in the result
122       object for interp unless interp is NULL.  If setFromAnyProc is success‐
123       ful, it stores the new internal representation, sets  objPtr's  typePtr
124       member  to  point  to  the  Tcl_ObjType struct corresponding to the new
125       internal representation, and returns TCL_OK.  Before  setting  the  new
126       internal representation, the setFromAnyProc must free any internal rep‐
127       resentation of objPtr's old type; it  does  this  by  calling  the  old
128       type's freeIntRepProc if it is not NULL.
129
130       As  an  example, the setFromAnyProc for the built-in Tcl list type gets
131       an up-to-date string representation  for  objPtr  by  calling  Tcl_Get‐
132       StringFromObj.   It  parses  the string to verify it is in a valid list
133       format and to obtain each element value in the list, and, if this  suc‐
134       ceeds, stores the list elements in objPtr's internal representation and
135       sets objPtr's typePtr member to point to the  list  type's  Tcl_ObjType
136       structure.
137
138       Do  not release objPtr's old internal representation unless you replace
139       it with a new one or reset the typePtr member to NULL.
140
141       The setFromAnyProc member may be set to NULL, if  the  routines  making
142       use of the internal representation have no need to derive that internal
143       representation from an arbitrary string value.  However, in this  case,
144       passing  a  pointer  to  the type to Tcl_ConvertToType() will lead to a
145       panic, so to avoid this possibility, the type should not be registered.
146
147   THE UPDATESTRINGPROC FIELD
148       The updateStringProc member contains the address of a  function  called
149       to  create a valid string representation from an object's internal rep‐
150       resentation.
151
152              typedef void (Tcl_UpdateStringProc) (Tcl_Obj *objPtr);
153
154       objPtr's bytes member is always NULL when it is called.  It must always
155       set bytes non-NULL before returning.  We require the string representa‐
156       tion's byte array to have a null after the last byte, at offset length,
157       and  to  have no null bytes before that; this allows string representa‐
158       tions  to  be  treated  as  conventional  null  character-terminated  C
159       strings.  These restrictions are easily met by using Tcl's internal UTF
160       encoding for the string representation, same as one would do for  other
161       Tcl  routines  accepting  string  values as arguments.  Storage for the
162       byte array must be allocated in the heap by Tcl_Alloc or ckalloc.  Note
163       that  updateStringProcs  must  allocate enough storage for the string's
164       bytes and the terminating null byte.
165
166       The updateStringProc for Tcl's built-in double type, for example, calls
167       Tcl_PrintDouble  to  write  to  a buffer of size TCL_DOUBLE_SPACE, then
168       allocates and copies the string representation to just enough space  to
169       hold  it.  A pointer to the allocated space is stored in the bytes mem‐
170       ber.
171
172       The updateStringProc member may be set to NULL, if the routines  making
173       use  of the internal representation are written so that the string rep‐
174       resentation is never invalidated.  Failure to meet this obligation will
175       lead  to  panics  or crashes when Tcl_GetStringFromObj or other similar
176       routines ask for the string representation.
177
178   THE DUPINTREPPROC FIELD
179       The dupIntRepProc member contains the address of a function  called  to
180       copy an internal representation from one object to another.
181
182              typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *srcPtr,
183                      Tcl_Obj *dupPtr);
184
185       dupPtr's  internal  representation  is made a copy of srcPtr's internal
186       representation.  Before the call, srcPtr's internal  representation  is
187       valid  and dupPtr's is not.  srcPtr's object type determines what copy‐
188       ing its internal representation means.
189
190       For example, the dupIntRepProc for the Tcl integer type  simply  copies
191       an  integer.   The  built-in  list type's dupIntRepProc uses a far more
192       sophisticated scheme to continue sharing storage as much as it  reason‐
193       ably can.
194
195   THE FREEINTREPPROC FIELD
196       The  freeIntRepProc  member  contains the address of a function that is
197       called when an object is freed.
198
199              typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *objPtr);
200
201       The freeIntRepProc function can deallocate the storage for the object's
202       internal representation and do other type-specific processing necessary
203       when an object is freed.
204
205       For example, the list type's freeIntRepProc respects the storage  shar‐
206       ing scheme established by the dupIntRepProc so that it only frees stor‐
207       age when the last object sharing it is being freed.
208
209       The freeIntRepProc member can be set  to  NULL  to  indicate  that  the
210       internal  representation  does not require freeing.  The freeIntRepProc
211       implementation must not access the bytes member of  the  object,  since
212       Tcl  makes  its own internal uses of that field during object deletion.
213       The defined tasks for the freeIntRepProc have no need  to  consult  the
214       bytes member.
215

SEE ALSO

217       Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
218

KEYWORDS

220       internal  representation,  object,  object type, string representation,
221       type conversion
222
223
224
225Tcl                                   8.0                       Tcl_ObjType(3)
Impressum