diff options
| -rw-r--r-- | doc/ListObj.3 | 18 | ||||
| -rw-r--r-- | doc/Object.3 | 16 | ||||
| -rw-r--r-- | doc/ObjectType.3 | 35 |
3 files changed, 43 insertions, 26 deletions
diff --git a/doc/ListObj.3 b/doc/ListObj.3 index a17ab66..4e0ae12 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ListObj.3,v 1.10 2005/05/10 18:33:56 kennykb Exp $ +'\" RCS: @(#) $Id: ListObj.3,v 1.11 2007/07/04 15:24:45 dkf Exp $ '\" .so man.macros .TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures" @@ -220,27 +220,33 @@ it can be used to implement a number of list operations. For example, the following code inserts the \fIobjc\fR objects referenced by the array of object pointers \fIobjv\fR just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR: +.PP .CS -result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv); +result = Tcl_ListObjReplace(interp, listPtr, index, 0, + objc, objv); .CE +.PP Similarly, the following code appends the \fIobjc\fR objects referenced by the array \fIobjv\fR to the end of the list \fIlistPtr\fR: +.PP .CS result = Tcl_ListObjLength(interp, listPtr, &length); if (result == TCL_OK) { - result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv); + result = Tcl_ListObjReplace(interp, listPtr, length, 0, + objc, objv); } .CE +.PP The \fIcount\fR list elements starting at \fIfirst\fR can be deleted by simply calling \fBTcl_ListObjReplace\fR with a NULL \fIobjvPtr\fR: +.PP .CS -result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL); +result = Tcl_ListObjReplace(interp, listPtr, first, count, + 0, NULL); .CE - .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult - .SH KEYWORDS append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation diff --git a/doc/Object.3 b/doc/Object.3 index 6a0848b..2d3a206 100644 --- a/doc/Object.3 +++ b/doc/Object.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Object.3,v 1.15 2006/08/03 22:46:34 nijtmans Exp $ +'\" RCS: @(#) $Id: Object.3,v 1.16 2007/07/04 15:24:45 dkf Exp $ '\" .so man.macros .TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures" @@ -106,7 +106,6 @@ Seven types are predefined in the Tcl core including integer, double, list, and bytecode. Extension writers can extend the set of types by using the procedure \fBTcl_RegisterObjType\fR . - .SH "THE TCL_OBJ STRUCTURE" .PP Each Tcl object is represented by a \fBTcl_Obj\fR structure @@ -230,7 +229,6 @@ creates a new internal representation for an object and changes its \fItypePtr\fR. See the man page for \fBTcl_RegisterObjType\fR to see how to create a new object type. - .SH "EXAMPLE OF THE LIFETIME OF AN OBJECT" .PP As an example of the lifetime of an object, @@ -270,7 +268,6 @@ The string representation of \fIx\fR's object is needed and is recomputed. The string representation is now \fB124\fR and both representations are again valid. - .SH "STORAGE MANAGEMENT OF OBJECTS" .PP Tcl objects are allocated on the heap and are shared as much as possible @@ -323,21 +320,22 @@ For example, the following code appears in the command procedure that implements \fBlinsert\fR. This procedure modifies the list object passed to it in \fIobjv[1]\fR by inserting \fIobjc-3\fR new elements before \fIindex\fR. +.PP .CS listPtr = objv[1]; if (Tcl_IsShared(listPtr)) { - listPtr = Tcl_DuplicateObj(listPtr); + listPtr = Tcl_DuplicateObj(listPtr); } -result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3])); +result = Tcl_ListObjReplace(interp, listPtr, index, 0, + (objc-3), &(objv[3])); .CE +.PP As another example, \fBincr\fR's command procedure must check whether the variable's object is shared before incrementing the integer in its internal representation. If it is shared, it needs to duplicate the object in order to avoid accidentally changing values in other data structures. - .SH "SEE ALSO" -Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType - +Tcl_ConvertToType(3), Tcl_GetIntFromObj(3), Tcl_ListObjAppendElement(3), Tcl_ListObjIndex(3), Tcl_ListObjReplace(3), Tcl_RegisterObjType(3) .SH KEYWORDS internal representation, object, object creation, object type, reference counting, string representation, type conversion diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index 42afabb..3101ffa 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ObjectType.3,v 1.13 2006/08/03 22:41:27 nijtmans Exp $ +'\" RCS: @(#) $Id: ObjectType.3,v 1.14 2007/07/04 15:24:45 dkf Exp $ '\" .so man.macros .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures" @@ -82,7 +82,6 @@ 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). - .SH "THE TCL_OBJTYPE STRUCTURE" .PP Extension writers can define new object types by defining four @@ -90,28 +89,34 @@ procedures, initializing a Tcl_ObjType structure to describe the type, and calling \fBTcl_RegisterObjType\fR. The \fBTcl_ObjType\fR structure is defined as follows: +.PP .CS typedef struct Tcl_ObjType { - char *\fIname\fR; - Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR; - Tcl_DupInternalRepProc *\fIdupIntRepProc\fR; - Tcl_UpdateStringProc *\fIupdateStringProc\fR; - Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR; + char *\fIname\fR; + Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR; + Tcl_DupInternalRepProc *\fIdupIntRepProc\fR; + Tcl_UpdateStringProc *\fIupdateStringProc\fR; + Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR; } Tcl_ObjType; .CE +.SS "THE NAME FIELD" .PP The \fIname\fR member describes the name of the type, e.g. \fBint\fR. Extension writers can look up an object type using its name with the \fBTcl_GetObjType\fR procedure. The remaining four members are pointers to procedures called by the generic Tcl object code: +.SS "THE SETFROMANYPROC FIELD" .PP The \fIsetFromAnyProc\fR member contains the address of a function called to create a valid internal representation from an object's string representation. +.PP .CS -typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR); +typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIobjPtr\fR); .CE +.PP If an internal representation can't be created from the string, it returns \fBTCL_ERROR\fR and puts a message describing the error in the result object for \fIinterp\fR @@ -135,13 +140,16 @@ and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's Tcl_ObjType structure. 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. +.SS "THE UPDATESTRINGPROC FIELD" .PP The \fIupdateStringProc\fR member contains the address of a function called to create a valid string representation from an object's internal representation. +.PP .CS typedef void (Tcl_UpdateStringProc) (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 @@ -156,12 +164,16 @@ builds an array of strings for each element object and then calls \fBTcl_Merge\fR to construct a string with proper Tcl list structure. It stores this string as the list object's 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 object to another. +.PP .CS -typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR); +typedef void (Tcl_DupInternalRepProc) (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, @@ -174,12 +186,15 @@ The built-in list type's \fIdupIntRepProc\fR allocates a new array that points at the original element objects; the elements are shared between the two lists (and their reference counts are incremented to reflect the new references). +.SS "THE FREEINTREPPROC FIELD" .PP The \fIfreeIntRepProc\fR member contains the address of a function that is called when an object is freed. +.PP .CS typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR); .CE +.PP The \fIfreeIntRepProc\fR function can deallocate the storage for the object's internal representation and do other type-specific processing necessary when an object is freed. @@ -194,9 +209,7 @@ to indicate that the internal representation does not require freeing. The \fIfreeIntRepProc\fR implementation should not access the \fIbytes\fR member of the object, as this may potentially have already been deleted. - .SH "SEE ALSO" Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount - .SH KEYWORDS internal representation, object, object type, string representation, type conversion |