diff options
Diffstat (limited to 'tcl8.6/doc/ObjectType.3')
-rw-r--r-- | tcl8.6/doc/ObjectType.3 | 256 |
1 files changed, 0 insertions, 256 deletions
diff --git a/tcl8.6/doc/ObjectType.3 b/tcl8.6/doc/ObjectType.3 deleted file mode 100644 index bf414ac..0000000 --- a/tcl8.6/doc/ObjectType.3 +++ /dev/null @@ -1,256 +0,0 @@ -'\" -'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH NAME -Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl value types -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -\fBTcl_RegisterObjType\fR(\fItypePtr\fR) -.sp -const Tcl_ObjType * -\fBTcl_GetObjType\fR(\fItypeName\fR) -.sp -int -\fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR) -.sp -int -\fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR) -.SH ARGUMENTS -.AS "const char" *typeName -.AP "const Tcl_ObjType" *typePtr in -Points to the structure containing information about the Tcl value type. -This storage must live forever, -typically by being statically allocated. -.AP "const char" *typeName in -The name of a Tcl value type that \fBTcl_GetObjType\fR should look up. -.AP Tcl_Interp *interp in -Interpreter to use for error reporting. -.AP Tcl_Obj *objPtr in -For \fBTcl_AppendAllObjTypes\fR, this points to the value onto which -it appends the name of each value type as a list element. -For \fBTcl_ConvertToType\fR, this points to a value that -must have been the result of a previous call to \fBTcl_NewObj\fR. -.BE - -.SH DESCRIPTION -.PP -The procedures in this man page manage Tcl value types (sometimes -referred to as object types or \fBTcl_ObjType\fRs for historical reasons). -They are used to register new value types, look up types, -and force conversions from one type to another. -.PP -\fBTcl_RegisterObjType\fR registers a new Tcl value type -in the table of all value types that \fBTcl_GetObjType\fR -can look up by name. There are other value types supported by Tcl -as well, which Tcl chooses not to register. Extensions can likewise -choose to register the value types they create or not. -The argument \fItypePtr\fR points to a Tcl_ObjType structure that -describes the new type by giving its name -and by supplying pointers to four procedures -that implement the type. -If the type table already contains a type -with the same name as in \fItypePtr\fR, -it is replaced with the new type. -The Tcl_ObjType structure is described -in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below. -.PP -\fBTcl_GetObjType\fR returns a pointer to the registered Tcl_ObjType -with name \fItypeName\fR. -It returns NULL if no type with that name is registered. -.PP -\fBTcl_AppendAllObjTypes\fR appends the name of each registered value type -as a list element onto the Tcl value referenced by \fIobjPtr\fR. -The return value is \fBTCL_OK\fR unless there was an error -converting \fIobjPtr\fR to a list value; -in that case \fBTCL_ERROR\fR is returned. -.PP -\fBTcl_ConvertToType\fR converts a value from one type to another -if possible. -It creates a new internal representation for \fIobjPtr\fR -appropriate for the target type \fItypePtr\fR -and sets its \fItypePtr\fR member as determined by calling the -\fItypePtr->setFromAnyProc\fR routine. -Any internal representation for \fIobjPtr\fR's old type is freed. -If an error occurs during conversion, it returns \fBTCL_ERROR\fR -and leaves an error message in the result value for \fIinterp\fR -unless \fIinterp\fR is NULL. -Otherwise, it returns \fBTCL_OK\fR. -Passing a NULL \fIinterp\fR allows this procedure to be used -as a test whether the conversion can be done (and in fact was done). -.VS 8.5 -.PP -In many cases, the \fItypePtr->setFromAnyProc\fR routine will -set \fIobjPtr->typePtr\fR to the argument value \fItypePtr\fR, -but that is no longer guaranteed. The \fIsetFromAnyProc\fR is -free to set the internal representation for \fIobjPtr\fR to make -use of another related Tcl_ObjType, if it sees fit. -.VE 8.5 -.SH "THE TCL_OBJTYPE STRUCTURE" -.PP -Extension writers can define new value types by defining four -procedures and -initializing a Tcl_ObjType structure to describe the type. -Extension writers may also pass a pointer to their Tcl_ObjType -structure to \fBTcl_RegisterObjType\fR if they wish to permit -other extensions to look up their Tcl_ObjType by name with -the \fBTcl_GetObjType\fR routine. -The \fBTcl_ObjType\fR structure is defined as follows: -.PP -.CS -typedef struct Tcl_ObjType { - const char *\fIname\fR; - Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR; - Tcl_DupInternalRepProc *\fIdupIntRepProc\fR; - Tcl_UpdateStringProc *\fIupdateStringProc\fR; - Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR; -} \fBTcl_ObjType\fR; -.CE -.SS "THE NAME FIELD" -.PP -The \fIname\fR member describes the name of the type, e.g. \fBint\fR. -When a type is registered, this is the name used by callers -of \fBTcl_GetObjType\fR to lookup the type. For unregistered -types, the \fIname\fR field is primarily of value for debugging. -The remaining four members are pointers to procedures -called by the generic Tcl value code: -.SS "THE SETFROMANYPROC FIELD" -.PP -The \fIsetFromAnyProc\fR member contains the address of a function -called to create a valid internal representation -from a value's string representation. -.PP -.CS -typedef int \fBTcl_SetFromAnyProc\fR( - Tcl_Interp *\fIinterp\fR, - Tcl_Obj *\fIobjPtr\fR); -.CE -.PP -If an internal representation cannot be created from the string, -it returns \fBTCL_ERROR\fR and puts a message -describing the error in the result value for \fIinterp\fR -unless \fIinterp\fR is NULL. -If \fIsetFromAnyProc\fR is successful, -it stores the new internal representation, -sets \fIobjPtr\fR's \fItypePtr\fR member to point to -the \fBTcl_ObjType\fR struct corresponding to the new -internal representation, and returns \fBTCL_OK\fR. -Before setting the new internal representation, -the \fIsetFromAnyProc\fR must free any internal representation -of \fIobjPtr\fR's old type; -it does this by calling the old type's \fIfreeIntRepProc\fR -if it is not NULL. -.PP -As an example, the \fIsetFromAnyProc\fR for the built-in Tcl list type -gets an up-to-date string representation for \fIobjPtr\fR -by calling \fBTcl_GetStringFromObj\fR. -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 succeeds, -stores the list elements in \fIobjPtr\fR's internal representation -and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the list type's -Tcl_ObjType structure. -.PP -Do not release \fIobjPtr\fR's old internal representation unless you -replace it with a new one or reset the \fItypePtr\fR member to NULL. -.PP -The \fIsetFromAnyProc\fR 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 \fBTcl_ConvertToType\fR will -lead to a panic, so to avoid this possibility, the type -should \fInot\fR be registered. -.SS "THE UPDATESTRINGPROC FIELD" -.PP -The \fIupdateStringProc\fR member contains the address of a function -called to create a valid string representation -from a value's internal representation. -.PP -.CS -typedef void \fBTcl_UpdateStringProc\fR( - Tcl_Obj *\fIobjPtr\fR); -.CE -.PP -\fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called. -It must always set \fIbytes\fR non-NULL before returning. -We require the string representation's byte array -to have a null after the last byte, at offset \fIlength\fR, -and to have no null bytes before that; this allows string representations -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 \fBTcl_Alloc\fR -or \fBckalloc\fR. Note that \fIupdateStringProc\fRs must allocate -enough storage for the string's bytes and the terminating null byte. -.PP -The \fIupdateStringProc\fR for Tcl's built-in double type, for example, -calls Tcl_PrintDouble to write to a buffer of size TCL_DOUBLE_SPACE, -then allocates and copies the string representation to just enough -space to hold it. A pointer to the allocated space is stored in -the \fIbytes\fR member. -.PP -The \fIupdateStringProc\fR member may be set to NULL, if the routines -making use of the internal representation are written so that the -string representation is never invalidated. Failure to meet this -obligation will lead to panics or crashes when \fBTcl_GetStringFromObj\fR -or other similar routines ask for the string representation. -.SS "THE DUPINTREPPROC FIELD" -.PP -The \fIdupIntRepProc\fR member contains the address of a function -called to copy an internal representation from one value to another. -.PP -.CS -typedef void \fBTcl_DupInternalRepProc\fR( - Tcl_Obj *\fIsrcPtr\fR, - Tcl_Obj *\fIdupPtr\fR); -.CE -.PP -\fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's -internal representation. -Before the call, -\fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not. -\fIsrcPtr\fR's value type determines what -copying its internal representation means. -.PP -For example, the \fIdupIntRepProc\fR for the Tcl integer type -simply copies an integer. -The built-in list type's \fIdupIntRepProc\fR uses a far more -sophisticated scheme to continue sharing storage as much as it -reasonably can. -.SS "THE FREEINTREPPROC FIELD" -.PP -The \fIfreeIntRepProc\fR member contains the address of a function -that is called when a value is freed. -.PP -.CS -typedef void \fBTcl_FreeInternalRepProc\fR( - Tcl_Obj *\fIobjPtr\fR); -.CE -.PP -The \fIfreeIntRepProc\fR function can deallocate the storage -for the value's internal representation -and do other type-specific processing necessary when a value is freed. -.PP -For example, the list type's \fIfreeIntRepProc\fR respects -the storage sharing scheme established by the \fIdupIntRepProc\fR -so that it only frees storage when the last value sharing it -is being freed. -.PP -The \fIfreeIntRepProc\fR member can be set to NULL -to indicate that the internal representation does not require freeing. -The \fIfreeIntRepProc\fR implementation must not access the -\fIbytes\fR member of the value, since Tcl makes its own internal -uses of that field during value deletion. The defined tasks for -the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR -member. -.SH "SEE ALSO" -Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3) -.SH KEYWORDS -internal representation, value, value type, string representation, type conversion |