1Tcl_ObjType(3) Tcl Library Procedures Tcl_ObjType(3)
2______________________________________________________________________________
6
8 Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_Con‐
9 vertToType - manipulate Tcl object types
10
12 #include <tcl.h>
13 Tcl_RegisterObjType(typePtr)
15 Tcl_ObjType *
17 Tcl_GetObjType(typeName)
18 int
20 Tcl_AppendAllObjTypes(interp, objPtr)
21 int
23 Tcl_ConvertToType(interp, objPtr, typePtr)
24
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 const char *typeName (in) The name of a Tcl object type that
33 Tcl_GetObjType should look up.
34 Tcl_Interp *interp (in) Interpreter to use for error report‐
36 ing.
37 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
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 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 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 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 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 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
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 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 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 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 typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *interp,
118 Tcl_Obj *objPtr);
119 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 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 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 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 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 typedef void (Tcl_UpdateStringProc) (Tcl_Obj *objPtr);
153 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 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 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 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 typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *srcPtr,
183 Tcl_Obj *dupPtr);
184 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 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 THE FREEINTREPPROC FIELD
196 The freeIntRepProc member contains the address of a function that is
197 called when an object is freed.
198 typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *objPtr);
200 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 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 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
217 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
218
220 internal representation, object, object type, string representation,
221 type conversion
222Tcl 8.0 Tcl_ObjType(3)