Import Tcl-core 8.6.6 (as of svn r86089)

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