DragonFly On-Line Manual Pages

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)