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(intValue)

Tcl_SetBooleanObj(objPtr, intValue)

int
Tcl_GetBooleanFromObj(interp, objPtr, intPtr)

ARGUMENTS

int intValue (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 *intPtr (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 storing a boolean value into a Tcl_Obj, any non-zero
integer value in intValue 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
intValue 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 intValue. 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 intValue 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 intPtr. 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 intPtr and if that value is non-zero a 1 is written
at the address given by intPtr. In all cases where a value is
written at the address given by intPtr, 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 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 "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, value

Tcl 8.5 Tcl_BooleanObj(3)