diff options
Diffstat (limited to 'doc/BoolObj.3')
| -rw-r--r-- | doc/BoolObj.3 | 106 |
1 files changed, 57 insertions, 49 deletions
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3 index 2814e4e..395d159 100644 --- a/doc/BoolObj.3 +++ b/doc/BoolObj.3 @@ -1,14 +1,15 @@ '\" '\" 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. '\" .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 @@ -21,20 +22,14 @@ Tcl_Obj * int \fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR) .SH ARGUMENTS -.AS Tcl_Interp *interp +.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 @@ -44,44 +39,57 @@ 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 -from the Tcl object \fIobjPtr\fR. -If the object is not already a boolean object, -it will attempt to convert it to one. -If an error occurs during conversion, it returns \fBTCL_ERROR\fR -and leaves an error message in the interpreter's result object -unless \fIinterp\fR is NULL. -Otherwise, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR -and stores the boolean value in the address given by \fIboolPtr\fR. -If the object is not already a boolean object, -the conversion will free any old internal representation. -Objects having a string representation equal to any of \fB0\fR, -\fBfalse\fR, \fBno\fR, or \fBoff\fR have a boolean value 0; if the -string representation is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or -\fBon\fR the boolean value is 1. -Any of these string values may be abbreviated, and upper-case spellings -are also acceptable. +\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 stores in the Tcl_Obj \fI*objPtr\fR +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 into \fI*objPtr\fR implies the freeing of +any former value stored in \fI*objPtr\fR. +.PP +\fBTcl_GetBooleanFromObj\fR attempts to retrieve 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_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 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. +The set of values for which \fBTcl_GetBooleanFromObj\fR +will return \fBTCL_OK\fR is strictly larger than +the set of values for which \fBTcl_GetBoolean\fR will do the same. +For example, the value +.QW 5 +passed to \fBTcl_GetBooleanFromObj\fR +will lead to a \fBTCL_OK\fR return (and the boolean value 1), +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_NewObj, Tcl_IsShared, Tcl_GetBoolean .SH KEYWORDS -boolean, boolean object, boolean type, internal representation, object, object type, string representation +boolean, object |