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

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_RegisterObjType(typePtr)
15
16       const 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       const Tcl_ObjType *typePtr (in)    Points to the  structure  containing
27                                          information   about  the  Tcl  value
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  value  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  value onto which it
40                                          appends the name of each value  type
41                                          as a list element.  For Tcl_Convert‐
42                                          ToType, this points to a value  that
43                                          must  have been the result of a pre‐
44                                          vious call to Tcl_NewObj.
45______________________________________________________________________________
46
47

DESCRIPTION

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

THE TCL_OBJTYPE STRUCTURE

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

SEE ALSO

222       Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)
223

KEYWORDS

225       internal representation, value, value type, string representation, type
226       conversion
227
228
229
230Tcl                                   8.0                       Tcl_ObjType(3)
Impressum