| |
Tcl_BooleanObj(3) Tcl Library Procedures Tcl_BooleanObj(3)
_________________________________________________________________________________________________
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 mes-
sage is left in the interpreter's result object unless
interp is NULL.
int *boolPtr (out) Points to place where Tcl_GetBooleanFromObj 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 stor-
ing 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 rec-
ognized 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_GetBooleanFro-
mObj 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 efficiently.
Note that the routines Tcl_GetBooleanFromObj and Tcl_GetBoolean are not functional equiva-
lents. 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 "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.
SEE ALSO
Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
KEYWORDS
boolean, object
Tcl 8.5 Tcl_BooleanObj(3) |
|
