1Tcl_BooleanObj(3)           Tcl Library Procedures           Tcl_BooleanObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_NewBooleanObj,     Tcl_SetBooleanObj,    Tcl_GetBooleanFromObj    -
9       store/retrieve boolean value in a Tcl_Obj
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Obj *
15       Tcl_NewBooleanObj(boolValue)
16
17       Tcl_SetBooleanObj(objPtr, boolValue)
18
19       int
20       Tcl_GetBooleanFromObj(interp, objPtr, boolPtr)
21

ARGUMENTS

23       int boolValue (in)                 Integer value  to  be  stored  as  a
24                                          boolean value in a Tcl_Obj.
25
26       Tcl_Obj *objPtr (in/out)           Points  to  the  Tcl_Obj in which to
27                                          store, or from which to  retrieve  a
28                                          boolean value.
29
30       Tcl_Interp *interp (in/out)        If   a   boolean   value  cannot  be
31                                          retrieved, an error message is  left
32                                          in  the  interpreter's  result value
33                                          unless interp is NULL.
34
35       int *boolPtr (out)                 Points  to  place   where   Tcl_Get‐
36                                          BooleanFromObj  stores  the  boolean
37                                          value (0 or 1) obtained from objPtr.
38______________________________________________________________________________
39
40

DESCRIPTION

42       These procedures are used to pass boolean values to  and  from  Tcl  as
43       Tcl_Obj's.   When  storing a boolean value into a Tcl_Obj, any non-zero
44       integer value in boolValue is taken to be the boolean value 1, and  the
45       integer value 0 is taken to be the boolean value 0.
46
47       Tcl_NewBooleanObj  creates  a  new  Tcl_Obj,  stores  the boolean value
48       boolValue in it, and returns a pointer to the  new  Tcl_Obj.   The  new
49       Tcl_Obj has reference count of zero.
50
51       Tcl_SetBooleanObj accepts objPtr, a pointer to an existing Tcl_Obj, and
52       stores in the Tcl_Obj *objPtr the boolean value boolValue.  This  is  a
53       write  operation  on  *objPtr, so objPtr must be unshared.  Attempts to
54       write to a shared Tcl_Obj will panic.  A successful write of  boolValue
55       into *objPtr implies the freeing of any former value stored in *objPtr.
56
57       Tcl_GetBooleanFromObj  attempts  to  retrieve  a boolean value from the
58       value stored in *objPtr.  If objPtr holds a string value recognized  by
59       Tcl_GetBoolean,  then  the  recognized  boolean value is written at the
60       address given by boolPtr.  If objPtr holds any value  recognized  as  a
61       number by Tcl, then if that value is zero a 0 is written at the address
62       given by boolPtr and if that value is non-zero a 1 is  written  at  the
63       address given by boolPtr.  In all cases where a value is written at the
64       address given by boolPtr, Tcl_GetBooleanFromObj returns TCL_OK.  If the
65       value  of  objPtr  does  not  meet  any  of  the conditions above, then
66       TCL_ERROR is returned and an error message is left in the interpreter's
67       result  unless  interp  is  NULL.   Tcl_GetBooleanFromObj may also make
68       changes to the internal fields of  *objPtr  so  that  future  calls  to
69       Tcl_GetBooleanFromObj  on  the  same objPtr can be performed more effi‐
70       ciently.
71
72       Note that the routines Tcl_GetBooleanFromObj and Tcl_GetBoolean are not
73       functional equivalents.  The set of values for which Tcl_GetBooleanFro‐
74       mObj will return TCL_OK is strictly larger than the set of  values  for
75       which  Tcl_GetBoolean  will  do  the  same.  For example, the value “5”
76       passed to Tcl_GetBooleanFromObj will lead to a TCL_OK return  (and  the
77       boolean  value  1),  while the same value passed to Tcl_GetBoolean will
78       lead to a TCL_ERROR return.
79
80

SEE ALSO

82       Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
83
84

KEYWORDS

86       boolean, value
87
88
89
90Tcl                                   8.5                    Tcl_BooleanObj(3)
Impressum