* 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.

1 files changed, 39 insertions, 43 deletions

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