diff options
Diffstat (limited to 'doc/BoolObj.3')
-rw-r--r-- | doc/BoolObj.3 | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/doc/BoolObj.3 b/doc/BoolObj.3 new file mode 100644 index 0000000..7268e1f --- /dev/null +++ b/doc/BoolObj.3 @@ -0,0 +1,95 @@ +'\" +'\" 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. +'\" +.TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures" +.so man.macros +.BS +.SH NAME +Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +Tcl_Obj * +\fBTcl_NewBooleanObj\fR(\fIboolValue\fR) +.sp +\fBTcl_SetBooleanObj\fR(\fIobjPtr, boolValue\fR) +.sp +int +\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR) +.SH ARGUMENTS +.AS Tcl_Interp boolValue in/out +.AP int boolValue in +Integer value to be stored as a boolean value in a Tcl_Obj. +.AP Tcl_Obj *objPtr in/out +Points to the Tcl_Obj in which to store, or from which to +retrieve a boolean value. +.AP Tcl_Interp *interp in/out +If a boolean value cannot be retrieved, +an error message is left in the interpreter's result value +unless \fIinterp\fR is NULL. +.AP int *boolPtr out +Points to place where \fBTcl_GetBooleanFromObj\fR +stores the boolean value (0 or 1) obtained from \fIobjPtr\fR. +.BE + +.SH DESCRIPTION +.PP +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_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_IsShared, Tcl_GetBoolean + +.SH KEYWORDS +boolean, value |