1Tcl_BooleanObj(3) Tcl Library Procedures Tcl_BooleanObj(3)
2______________________________________________________________________________
6
8 Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj -
9 store/retrieve boolean value in a Tcl_Obj
10
12 #include <tcl.h>
13 Tcl_Obj *
15 Tcl_NewBooleanObj(boolValue)
16 Tcl_SetBooleanObj(objPtr, boolValue)
18 int
20 Tcl_GetBooleanFromObj(interp, objPtr, boolPtr)
21
23 int boolValue (in) Integer value to be stored as a
24 boolean value in a Tcl_Obj.
25 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 Tcl_Interp *interp (in/out) If a boolean value cannot be
31 retrieved, an error message is left
32 in the interpreter's result object
33 unless interp is NULL.
34 int *boolPtr (out) Points to place where Tcl_Get‐
36 BooleanFromObj stores the boolean
37 value (0 or 1) obtained from objPtr.
38_________________________________________________________________
39
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 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 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 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 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
82 Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
83
86 boolean, object
87Tcl 8.5 Tcl_BooleanObj(3)