summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordgp <dgp@users.sourceforge.net>2005-05-18 16:44:26 (GMT)
committerdgp <dgp@users.sourceforge.net>2005-05-18 16:44:26 (GMT)
commite97ce00b8da9890c3e43d724721d2f463ad8f5a8 (patch)
tree7259c2e1b8b193e8e4a7dcb6e21d13c9a1934e85
parentf063018fe11304895ff9ac81830ac933c831ca5f (diff)
downloadtcl-e97ce00b8da9890c3e43d724721d2f463ad8f5a8.zip
tcl-e97ce00b8da9890c3e43d724721d2f463ad8f5a8.tar.gz
tcl-e97ce00b8da9890c3e43d724721d2f463ad8f5a8.tar.bz2
* doc/BoolObj.3: Rewrite of documentation dropping many details
about the internals of Tcl_Objs. Shorter documentation focuses on the function and use of the routines.
-rw-r--r--ChangeLog4
-rw-r--r--doc/BoolObj.382
2 files changed, 43 insertions, 43 deletions
diff --git a/ChangeLog b/ChangeLog
index 1a6eab0..04bf525 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
2005-05-18 Don Porter <dgp@users.sourceforge.net>
+ * doc/BoolObj.3: Rewrite of documentation dropping many details
+ about the internals of Tcl_Objs. Shorter documentation focuses on
+ the function and use of the routines.
+
* generic/tclInt.h: Revision to the "boolean" Tcl_ObjType, so
* generic/tclObj.c: that only string values like "yes" and "false"
* tests/obj.test: are kept as the "boolean" Tcl_ObjType. The
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3
index ec6a3c9..df97a20 100644
--- a/doc/BoolObj.3
+++ b/doc/BoolObj.3
@@ -1,16 +1,17 @@
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
+'\" Contributions from Don Porter, NIST, 2005. (not subject to US copyright)
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: BoolObj.3,v 1.7 2005/05/10 18:33:54 kennykb Exp $
+'\" RCS: @(#) $Id: BoolObj.3,v 1.8 2005/05/18 16:44:35 dgp Exp $
'\"
.so man.macros
-.TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
+.TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- manipulate Tcl objects as boolean values
+Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -25,18 +26,12 @@ int
.SH ARGUMENTS
.AS Tcl_Interp boolValue in/out
.AP int boolValue in
-Integer value used to initialize or set a boolean object.
-If the integer is nonzero, the boolean object is set to 1;
-otherwise the boolean object is set to 0.
+Integer value to be stored as a boolean value in a Tcl_Obj.
.AP Tcl_Obj *objPtr in/out
-For \fBTcl_SetBooleanObj\fR, this points to the object to be converted
-to boolean type.
-For \fBTcl_GetBooleanFromObj\fR, this refers to the object
-from which to get a boolean value;
-if \fIobjPtr\fR does not already point to a boolean object,
-an attempt will be made to convert it to one.
+Points to the Tcl_Obj in which to store, or from which to
+retrieve a boolean value.
.AP Tcl_Interp *interp in/out
-If an error occurs during conversion,
+If a boolean value cannot be retrieved,
an error message is left in the interpreter's result object
unless \fIinterp\fR is NULL.
.AP int *boolPtr out
@@ -46,40 +41,42 @@ stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
.SH DESCRIPTION
.PP
-These procedures are used to create, modify, and read
-boolean Tcl objects from C code.
-\fBTcl_NewBooleanObj\fR and \fBTcl_SetBooleanObj\fR
-will create a new object of boolean type
-or modify an existing object to have boolean type.
-Both of these procedures set the object to have the
-boolean value (0 or 1) specified by \fIboolValue\fR;
-if \fIboolValue\fR is nonzero, the object is set to 1,
-otherwise to 0.
-\fBTcl_NewBooleanObj\fR returns a pointer to a newly created object
-with reference count zero.
-Both procedures set the object's type to be boolean
-and assign the boolean value to the object's internal representation
-\fIlongValue\fR member.
-\fBTcl_SetBooleanObj\fR invalidates any old string representation
-and, if the object is not already a boolean object,
-frees any old internal representation.
+These procedures are used to pass boolean values to and from
+Tcl as Tcl_Obj's. When storing a boolean value into a Tcl_Obj,
+any non-zero integer value in \fIboolValue\fR is taken to be
+the boolean value \fB1\fR, and the integer value \fB0\fR is
+taken to be the boolean value \fB0\fR.
.PP
-\fBTcl_GetBooleanFromObj\fR attempts to return a boolean value
-corresponding to the value of the Tcl object \fIobjPtr\fR.
-If \fIobjPtr\fR is of the boolean type, its boolean value
-is written at the address given by \fIboolPtr\fR.
-If \fIobjPtr\fR has a string representation recognized by
-\fBTcl_GetBoolean\fR, then \fIobjPtr\fR is converted to boolean
-type and its boolean value is written at the address given
-by \fIboolPtr\fR. If \fIobjPtr\fR holds any value recognized as
+\fBTcl_NewBooleanObj\fR creates a new Tcl_Obj, stores the boolean
+value \fIboolValue\fR in it, and returns a pointer to the new Tcl_Obj.
+The new Tcl_Obj has reference count of zero.
+.PP
+\fBTcl_SetBooleanObj\fR accepts \fIobjPtr\fR, a pointer to
+an existing Tcl_Obj, and sets the value of \fI*objPtr\fR to
+the boolean value \fIboolValue\fR. This is a write operation
+on \fI*objPtr\fR, so \fIobjPtr\fR must be unshared. Attempts to
+write to a shared Tcl_Obj will panic. A successful write
+of \fIboolValue\fR to \fI*objPtr\fR implies the freeing of
+any former value stored in \fI*objPtr\fR.
+.PP
+\fBTcl_GetBooleanFromObj\fR attempts to retrive a boolean value
+from the value stored in \fI*objPtr\fR.
+If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR,
+then the recognized boolean value is written at the address given
+by \fIboolPtr\fR.
+If \fIobjPtr\fR holds any value recognized as
a number by Tcl, then if that value is zero a 0 is written at
the address given by \fIboolPtr\fR and if that
value is non-zero a 1 is written at the address given by \fIboolPtr\fR.
In all cases where a value is written at the address given
-by \fIboolPtr\fR, \fBTCL_OK\fR is returned.
+by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
If the value of \fIobjPtr\fR does not meet any of the conditions
-above, then \fBTCL_ERROR\fR is returned and error message is
+above, then \fBTCL_ERROR\fR is returned and an error message is
left in the interpreter's result unless \fIinterp\fR is NULL.
+\fBTcl_GetBooleanFromObj\fR may also make changes to the internal
+fields of \fI*objPtr\fR so that future calls to
+\fBTcl_GetBooleanFromObj\fR on the same \fIobjPtr\fR can be
+performed more efficiently.
.PP
Note that the routines \fBTcl_GetBooleanFromObj\fR and
\fBTcl_GetBoolean\fR are not functional equivalents.
@@ -92,8 +89,7 @@ while the same value passed to \fBTcl_GetBoolean\fR will lead to
a \fBTCL_ERROR\fR return.
.SH "SEE ALSO"
-Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult,
-Tcl_GetBoolean
+Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
.SH KEYWORDS
-boolean, boolean object, boolean type, internal representation, object, object type, string representation
+boolean, object