Tcl_NewBooleanObj(3tcl)

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
                                        message 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  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                     Last change: 8.5                        1

Tcl_BooleanObj(3)    Tcl Library Procedures     Tcl_BooleanObj(3)

     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, object

Tcl                     Last change: 8.5                        2