summaryrefslogtreecommitdiffstats
path: root/doc/ObjectType.3
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2007-07-04 15:24:45 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2007-07-04 15:24:45 (GMT)
commitf41a7b9a9464e3211cf4935e2d0d56994cd727c7 (patch)
treeb278be58d13b204b0a6959bc385f6b577ecefd11 /doc/ObjectType.3
parente5f7a7f23ddbcd485a524a6fd1f60c2f6787c794 (diff)
downloadtcl-f41a7b9a9464e3211cf4935e2d0d56994cd727c7.zip
tcl-f41a7b9a9464e3211cf4935e2d0d56994cd727c7.tar.gz
tcl-f41a7b9a9464e3211cf4935e2d0d56994cd727c7.tar.bz2
Remove over-wide lines from nroff output.
Diffstat (limited to 'doc/ObjectType.3')
-rw-r--r--doc/ObjectType.335
1 files changed, 24 insertions, 11 deletions
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