I686LINUX/util/I686LINUX/man/man3/Tcl_ConvertToType.3

   1 '\"
   2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id: ObjectType.3,v 1.7 2002/08/16 13:45:36 dkf Exp $
   8 '\"
   9 '\" The definitions below are for supplemental macros used in Tcl/Tk
  10 '\" manual entries.
  11 '\"
  12 '\" .AP type name in/out ?indent?
  13 '\"     Start paragraph describing an argument to a library procedure.
  14 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 '\"     needed;  use .AS below instead)
  18 '\"
  19 '\" .AS ?type? ?name?
  20 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 '\"     name are examples of largest possible arguments that will be passed
  22 '\"     to .AP later.  If args are omitted, default tab stops are used.
  23 '\"
  24 '\" .BS
  25 '\"     Start box enclosure.  From here until next .BE, everything will be
  26 '\"     enclosed in one large box.
  27 '\"
  28 '\" .BE
  29 '\"     End of box enclosure.
  30 '\"
  31 '\" .CS
  32 '\"     Begin code excerpt.
  33 '\"
  34 '\" .CE
  35 '\"     End code excerpt.
  36 '\"
  37 '\" .VS ?version? ?br?
  38 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 '\"     of man pages.  The first argument is ignored and used for recording
  40 '\"     the version when the .VS was added, so that the sidebars can be
  41 '\"     found and removed when they reach a certain age.  If another argument
  42 '\"     is present, then a line break is forced before starting the sidebar.
  43 '\"
  44 '\" .VE
  45 '\"     End of vertical sidebar.
  46 '\"
  47 '\" .DS
  48 '\"     Begin an indented unfilled display.
  49 '\"
  50 '\" .DE
  51 '\"     End of indented unfilled display.
  52 '\"
  53 '\" .SO
  54 '\"     Start of list of standard options for a Tk widget.  The
  55 '\"     options follow on successive lines, in four columns separated
  56 '\"     by tabs.
  57 '\"
  58 '\" .SE
  59 '\"     End of list of standard options for a Tk widget.
  60 '\"
  61 '\" .OP cmdName dbName dbClass
  62 '\"     Start of description of a specific option.  cmdName gives the
  63 '\"     option's name as specified in the class command, dbName gives
  64 '\"     the option's name in the option database, and dbClass gives
  65 '\"     the option's class in the option database.
  66 '\"
  67 '\" .UL arg1 arg2
  68 '\"     Print arg1 underlined, then print arg2 normally.
  69 '\"
  70 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
  71 '\"
  72 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  73 .if t .wh -1.3i ^B
  74 .nr ^l \n(.l
  75 .ad b
  76 '\"     # Start an argument description
  77 .de AP
  78 .ie !"\\$4"" .TP \\$4
  79 .el \{\
  80 .   ie !"\\$2"" .TP \\n()Cu
  81 .   el          .TP 15
  82 .\}
  83 .ta \\n()Au \\n()Bu
  84 .ie !"\\$3"" \{\
  85 \&\\$1  \\fI\\$2\\fP    (\\$3)
  86 .\".b
  87 .\}
  88 .el \{\
  89 .br
  90 .ie !"\\$2"" \{\
  91 \&\\$1  \\fI\\$2\\fP
  92 .\}
  93 .el \{\
  94 \&\\fI\\$1\\fP
  95 .\}
  96 .\}
  97 ..
  98 '\"     # define tabbing values for .AP
  99 .de AS
 100 .nr )A 10n
 101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 102 .nr )B \\n()Au+15n
 103 .\"
 104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 106 ..
 107 .AS Tcl_Interp Tcl_CreateInterp in/out
 108 '\"     # BS - start boxed text
 109 '\"     # ^y = starting y location
 110 '\"     # ^b = 1
 111 .de BS
 112 .br
 113 .mk ^y
 114 .nr ^b 1u
 115 .if n .nf
 116 .if n .ti 0
 117 .if n \l'\\n(.lu\(ul'
 118 .if n .fi
 119 ..
 120 '\"     # BE - end boxed text (draw box now)
 121 .de BE
 122 .nf
 123 .ti 0
 124 .mk ^t
 125 .ie n \l'\\n(^lu\(ul'
 126 .el \{\
 127 .\"     Draw four-sided box normally, but don't draw top of
 128 .\"     box if the box started on an earlier page.
 129 .ie !\\n(^b-1 \{\
 130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 131 .\}
 132 .el \}\
 133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 134 .\}
 135 .\}
 136 .fi
 137 .br
 138 .nr ^b 0
 139 ..
 140 '\"     # VS - start vertical sidebar
 141 '\"     # ^Y = starting y location
 142 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 143 .de VS
 144 .if !"\\$2"" .br
 145 .mk ^Y
 146 .ie n 'mc \s12\(br\s0
 147 .el .nr ^v 1u
 148 ..
 149 '\"     # VE - end of vertical sidebar
 150 .de VE
 151 .ie n 'mc
 152 .el \{\
 153 .ev 2
 154 .nf
 155 .ti 0
 156 .mk ^t
 157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 158 .sp -1
 159 .fi
 160 .ev
 161 .\}
 162 .nr ^v 0
 163 ..
 164 '\"     # Special macro to handle page bottom:  finish off current
 165 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 166 '\"     # page bottom macro.
 167 .de ^B
 168 .ev 2
 169 'ti 0
 170 'nf
 171 .mk ^t
 172 .if \\n(^b \{\
 173 .\"     Draw three-sided box if this is the box's first page,
 174 .\"     draw two sides but no top otherwise.
 175 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 177 .\}
 178 .if \\n(^v \{\
 179 .nr ^x \\n(^tu+1v-\\n(^Yu
 180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 181 .\}
 182 .bp
 183 'fi
 184 .ev
 185 .if \\n(^b \{\
 186 .mk ^y
 187 .nr ^b 2
 188 .\}
 189 .if \\n(^v \{\
 190 .mk ^Y
 191 .\}
 192 ..
 193 '\"     # DS - begin display
 194 .de DS
 195 .RS
 196 .nf
 197 .sp
 198 ..
 199 '\"     # DE - end display
 200 .de DE
 201 .fi
 202 .RE
 203 .sp
 204 ..
 205 '\"     # SO - start of list of standard options
 206 .de SO
 207 .SH "STANDARD OPTIONS"
 208 .LP
 209 .nf
 210 .ta 5.5c 11c
 211 .ft B
 212 ..
 213 '\"     # SE - end of list of standard options
 214 .de SE
 215 .fi
 216 .ft R
 217 .LP
 218 See the \\fBoptions\\fR manual entry for details on the standard options.
 219 ..
 220 '\"     # OP - start of full description for a single option
 221 .de OP
 222 .LP
 223 .nf
 224 .ta 4c
 225 Command-Line Name:      \\fB\\$1\\fR
 226 Database Name:  \\fB\\$2\\fR
 227 Database Class: \\fB\\$3\\fR
 228 .fi
 229 .IP
 230 ..
 231 '\"     # CS - begin code excerpt
 232 .de CS
 233 .RS
 234 .nf
 235 .ta .25i .5i .75i 1i
 236 ..
 237 '\"     # CE - end code excerpt
 238 .de CE
 239 .fi
 240 .RE
 241 ..
 242 .de UL
 243 \\$1\l'|0\(ul'\\$2
 244 ..
 245 .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
 246 .BS
 247 .SH NAME
 248 Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType  \- manipulate Tcl object types
 249 .SH SYNOPSIS
 250 .nf
 251 \fB#include <tcl.h>\fR
 252 .sp
 253 \fBTcl_RegisterObjType\fR(\fItypePtr\fR)
 254 .sp
 255 Tcl_ObjType *
 256 \fBTcl_GetObjType\fR(\fItypeName\fR)
 257 .sp
 258 int
 259 \fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR)
 260 .sp
 261 int
 262 \fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
 263 .SH ARGUMENTS
 264 .AS Tcl_ObjType *typeName in
 265 .AP Tcl_ObjType *typePtr in
 266 Points to the structure containing information about the Tcl object type.
 267 This storage must live forever,
 268 typically by being statically allocated.
 269 .AP "CONST char" *typeName in
 270 The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
 271 .AP Tcl_Interp *interp in
 272 Interpreter to use for error reporting.
 273 .AP Tcl_Obj *objPtr in
 274 For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which
 275 it appends the name of each object type as a list element.
 276 For \fBTcl_ConvertToType\fR, this points to an object that
 277 must have been the result of a previous call to \fBTcl_NewObj\fR.
 278 .BE
 279
 280 .SH DESCRIPTION
 281 .PP
 282 The procedures in this man page manage Tcl object types.
 283 The are used to register new object types,
 284 look up types,
 285 and force conversions from one type to another.
 286 .PP
 287 \fBTcl_RegisterObjType\fR registers a new Tcl object type
 288 in the table of all object types supported by Tcl.
 289 The argument \fItypePtr\fR points to a Tcl_ObjType structure that
 290 describes the new type by giving its name
 291 and by supplying pointers to four procedures
 292 that implement the type.
 293 If the type table already contains a type
 294 with the same name as in \fItypePtr\fR,
 295 it is replaced with the new type.
 296 The Tcl_ObjType structure is described
 297 in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
 298 .PP
 299 \fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
 300 with name \fItypeName\fR.
 301 It returns NULL if no type with that name is registered.
 302 .PP
 303 \fBTcl_AppendAllObjTypes\fR appends the name of each object type
 304 as a list element onto the Tcl object referenced by \fIobjPtr\fR.
 305 The return value is \fBTCL_OK\fR unless there was an error
 306 converting \fIobjPtr\fR to a list object;
 307 in that case \fBTCL_ERROR\fR is returned.
 308 .PP
 309 \fBTcl_ConvertToType\fR converts an object from one type to another
 310 if possible.
 311 It creates a new internal representation for \fIobjPtr\fR
 312 appropriate for the target type \fItypePtr\fR
 313 and sets its \fItypePtr\fR member to that type.
 314 Any internal representation for \fIobjPtr\fR's old type is freed.
 315 If an error occurs during conversion, it returns \fBTCL_ERROR\fR
 316 and leaves an error message in the result object for \fIinterp\fR
 317 unless \fIinterp\fR is NULL.
 318 Otherwise, it returns \fBTCL_OK\fR.
 319 Passing a NULL \fIinterp\fR allows this procedure to be used
 320 as a test whether the conversion can be done (and in fact was done).
 321
 322 .SH "THE TCL_OBJTYPE STRUCTURE"
 323 .PP
 324 Extension writers can define new object types by defining four
 325 procedures,
 326 initializing a Tcl_ObjType structure to describe the type,
 327 and calling \fBTcl_RegisterObjType\fR.
 328 The \fBTcl_ObjType\fR structure is defined as follows:
 329 .CS
 330 typedef struct Tcl_ObjType {
 331         char *\fIname\fR;
 332         Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
 333         Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
 334         Tcl_UpdateStringProc *\fIupdateStringProc\fR;
 335         Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
 336 } Tcl_ObjType;
 337 .CE
 338 .PP
 339 The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
 340 Extension writers can look up an object type using its name
 341 with the \fBTcl_GetObjType\fR procedure.
 342 The remaining four members are pointers to procedures
 343 called by the generic Tcl object code:
 344 .PP
 345 The \fIsetFromAnyProc\fR member contains the address of a function
 346 called to create a valid internal representation
 347 from an object's string representation.
 348 .CS
 349 typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
 350 .CE
 351 If an internal representation can't be created from the string,
 352 it returns \fBTCL_ERROR\fR and puts a message
 353 describing the error in the result object for \fIinterp\fR
 354 unless \fIinterp\fR is NULL.
 355 If \fIsetFromAnyProc\fR is successful,
 356 it stores the new internal representation,
 357 sets \fIobjPtr\fR's \fItypePtr\fR member to point to
 358 \fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
 359 Before setting the new internal representation,
 360 the \fIsetFromAnyProc\fR must free any internal representation
 361 of \fIobjPtr\fR's old type;
 362 it does this by calling the old type's \fIfreeIntRepProc\fR
 363 if it is not NULL.
 364 As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type
 365 gets an up-to-date string representation for \fIobjPtr\fR
 366 by calling \fBTcl_GetStringFromObj\fR.
 367 It parses the string to obtain an integer and,
 368 if this succeeds,
 369 stores the integer in \fIobjPtr\fR's internal representation
 370 and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
 371 Tcl_ObjType structure.
 372 Do not release \fIobjPtr\fR's old internal representation unless you
 373 replace it with a new one or reset the \fItypePtr\fR member to NULL.
 374 .PP
 375 The \fIupdateStringProc\fR member contains the address of a function
 376 called to create a valid string representation
 377 from an object's internal representation.
 378 .CS
 379 typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
 380 .CE
 381 \fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
 382 It must always set \fIbytes\fR non-NULL before returning.
 383 We require the string representation's byte array
 384 to have a null after the last byte, at offset \fIlength\fR;
 385 this allows string representations that do not contain null bytes
 386 to be treated as conventional null character-terminated C strings.
 387 Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR
 388 or \fBckalloc\fR.  Note that \fIupdateStringProc\fRs must allocate
 389 enough storage for the string's bytes and the terminating null byte.
 390 The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
 391 builds an array of strings for each element object
 392 and then calls \fBTcl_Merge\fR
 393 to construct a string with proper Tcl list structure.
 394 It stores this string as the list object's string representation.
 395 .PP
 396 The \fIdupIntRepProc\fR member contains the address of a function
 397 called to copy an internal representation from one object to another.
 398 .CS
 399 typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
 400 .CE
 401 \fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
 402 internal representation.
 403 Before the call,
 404 \fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
 405 \fIsrcPtr\fR's object type determines what
 406 copying its internal representation means.
 407 For example, the \fIdupIntRepProc\fR for the Tcl integer type
 408 simply copies an integer.
 409 The builtin list type's \fIdupIntRepProc\fR
 410 allocates a new array that points at the original element objects;
 411 the elements are shared between the two lists
 412 (and their reference counts are incremented to reflect the new references).
 413 .PP
 414 The \fIfreeIntRepProc\fR member contains the address of a function
 415 that is called when an object is freed.
 416 .CS
 417 typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
 418 .CE
 419 The \fIfreeIntRepProc\fR function can deallocate the storage
 420 for the object's internal representation
 421 and do other type-specific processing necessary when an object is freed.
 422 For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
 423 that points to an array of pointers to each element in the list.
 424 The list type's \fIfreeIntRepProc\fR decrements
 425 the reference count for each element object
 426 (since the list will no longer refer to those objects),
 427 then deallocates the storage for the array of pointers.
 428 The \fIfreeIntRepProc\fR member can be set to NULL
 429 to indicate that the internal representation does not require freeing.
 430
 431 .SH "SEE ALSO"
 432 Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
 433
 434 .SH KEYWORDS
 435 internal representation, object, object type, string representation, type conversion