Tcl_GetBooleanFromObj(interp, objPtr, boolPtr)
These procedures are used to pass boolean values to and from
Tcl as Tcl_Objs. 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 retrive 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
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 interpreters 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 efficiently.
Note that the routines Tcl_GetBooleanFromObj and
Tcl_GetBoolean are not functional equivalents.
The set of values for which Tcl_GetBooleanFromObj
will return TCL_OK is strictly larger than
the set of values for which Tcl_GetBoolean will do the same.
For example, the value
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.