Tcl_NewBooleanObj - store/retrieve boolean value in a Tcl_Obj
#include <tcl.h> Tcl_Obj * Tcl_NewBooleanObj(boolValue) Tcl_SetBooleanObj(objPtr, boolValue) int Tcl_GetBooleanFromObj(interp, objPtr, boolPtr)
Tcl_BooleanObj(3tcl) Tcl Library Procedures Tcl_BooleanObj(3tcl)
______________________________________________________________________________
NAME
Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj -
store/retrieve boolean value in a Tcl_Obj
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_NewBooleanObj(boolValue)
Tcl_SetBooleanObj(objPtr, boolValue)
int
Tcl_GetBooleanFromObj(interp, objPtr, boolPtr)
ARGUMENTS
int boolValue (in) Integer value to be stored as a
boolean value in a Tcl_Obj.
Tcl_Obj *objPtr (in/out) Points to the Tcl_Obj in which to
store, or from which to retrieve a
boolean value.
Tcl_Interp *interp (in/out) If a boolean value cannot be
retrieved, an error message is left
in the interpreter's result value
unless interp is NULL.
int *boolPtr (out) Points to place where Tcl_Get-
BooleanFromObj stores the boolean
value (0 or 1) obtained from objPtr.
______________________________________________________________________________
DESCRIPTION
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 boolValue is taken to be the boolean value 1, and the
integer value 0 is taken to be the boolean value 0.
Tcl_NewBooleanObj creates a new Tcl_Obj, stores the boolean value
boolValue in it, and returns a pointer to the new Tcl_Obj. The new
Tcl_Obj has reference count of zero.
Tcl_SetBooleanObj accepts objPtr, a pointer to an existing Tcl_Obj, and
stores in the Tcl_Obj *objPtr the boolean value boolValue. This is a
write operation on *objPtr, so objPtr must be unshared. Attempts to
write to a shared Tcl_Obj will panic. A successful write of boolValue
into *objPtr implies the freeing of any former value stored in *objPtr.
Tcl_GetBooleanFromObj attempts to retrieve a boolean value from the
value stored in *objPtr. If objPtr holds a string value recognized by
Tcl_GetBoolean, then the recognized boolean value is written at the
address given by boolPtr. If objPtr holds any value recognized as a
number by Tcl, then if that value is zero a 0 is written at the address
given by boolPtr and if that value is non-zero a 1 is written at the
address given by boolPtr. In all cases where a value is written at the
address given by boolPtr, Tcl_GetBooleanFromObj returns TCL_OK. If the
value of objPtr does not meet any of the conditions above, then
TCL_ERROR is returned and an error message is left in the interpreter's
result unless interp is NULL. Tcl_GetBooleanFromObj may also make
changes to the internal fields of *objPtr so that future calls to
Tcl_GetBooleanFromObj on the same objPtr can be performed more effi-
ciently.
Note that the routines Tcl_GetBooleanFromObj and Tcl_GetBoolean are not
functional equivalents. The set of values for which Tcl_GetBooleanFro-
mObj will return TCL_OK is strictly larger than the set of values for
which Tcl_GetBoolean will do the same. For example, the value "5"
passed to Tcl_GetBooleanFromObj will lead to a TCL_OK return (and the
boolean value 1), while the same value passed to Tcl_GetBoolean will
lead to a TCL_ERROR return.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | runtime/tcl-8 |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
SEE ALSO
Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
KEYWORDS
boolean, value
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://prdownloads.sourceforge.net/tcl/tcl-
core8.6.7-src.tar.gz.
Further information about this software can be found on the open source
community website at https://www.tcl.tk/.
Tcl 8.5 Tcl_BooleanObj(3tcl)