summaryrefslogtreecommitdiffstats
path: root/doc/Object.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Object.3')
-rw-r--r--doc/Object.312
1 files changed, 11 insertions, 1 deletions
diff --git a/doc/Object.3 b/doc/Object.3
index 3b6abc8..00b4cec 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.21 2008/07/27 22:18:21 nijtmans Exp $
+'\" RCS: @(#) $Id: Object.3,v 1.22 2008/10/15 10:43:37 dkf Exp $
'\"
.so man.macros
.TH Tcl_Obj 3 8.5 Tcl "Tcl Library Procedures"
@@ -109,6 +109,7 @@ by defining their own \fBTcl_ObjType\fR structs.
.PP
Each Tcl object is represented by a \fBTcl_Obj\fR structure
which is defined as follows.
+.PP
.CS
typedef struct Tcl_Obj {
int \fIrefCount\fR;
@@ -131,6 +132,7 @@ typedef struct Tcl_Obj {
} \fIinternalRep\fR;
} \fBTcl_Obj\fR;
.CE
+.PP
The \fIbytes\fR and the \fIlength\fR members together hold
an object's UTF-8 string representation,
which is a \fIcounted string\fR not containing null bytes (UTF-8 null
@@ -232,20 +234,26 @@ to see how to create a new object type.
.PP
As an example of the lifetime of an object,
consider the following sequence of commands:
+.PP
.CS
\fBset x 123\fR
.CE
+.PP
This assigns to \fIx\fR an untyped object whose
\fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3.
The object's \fItypePtr\fR member is NULL.
+.PP
.CS
\fBputs "x is $x"\fR
.CE
+.PP
\fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL)
and is fetched for the command.
+.PP
.CS
\fBincr x\fR
.CE
+.PP
The \fBincr\fR command first gets an integer from \fIx\fR's object
by calling \fBTcl_GetIntFromObj\fR.
This procedure checks whether the object is already an integer object.
@@ -260,9 +268,11 @@ then invalidates its string representation
(by calling \fBTcl_InvalidateStringRep\fR)
since the string representation
no longer corresponds to the internal representation.
+.PP
.CS
\fBputs "x is now $x"\fR
.CE
+.PP
The string representation of \fIx\fR's object is needed
and is recomputed.
The string representation is now \fB124\fR