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_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 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 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