1 | '\" |
---|
2 | '\" Copyright (c) 1996-1997 Sun Microsystems, Inc. |
---|
3 | '\" Contributions from Don Porter, NIST, 2005. (not subject to US copyright) |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: BoolObj.3,v 1.11 2007/12/13 15:22:30 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | Tcl_Obj * |
---|
20 | \fBTcl_NewBooleanObj\fR(\fIboolValue\fR) |
---|
21 | .sp |
---|
22 | \fBTcl_SetBooleanObj\fR(\fIobjPtr, boolValue\fR) |
---|
23 | .sp |
---|
24 | int |
---|
25 | \fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR) |
---|
26 | .SH ARGUMENTS |
---|
27 | .AS Tcl_Interp boolValue in/out |
---|
28 | .AP int boolValue in |
---|
29 | Integer value to be stored as a boolean value in a Tcl_Obj. |
---|
30 | .AP Tcl_Obj *objPtr in/out |
---|
31 | Points to the Tcl_Obj in which to store, or from which to |
---|
32 | retrieve a boolean value. |
---|
33 | .AP Tcl_Interp *interp in/out |
---|
34 | If a boolean value cannot be retrieved, |
---|
35 | an error message is left in the interpreter's result object |
---|
36 | unless \fIinterp\fR is NULL. |
---|
37 | .AP int *boolPtr out |
---|
38 | Points to place where \fBTcl_GetBooleanFromObj\fR |
---|
39 | stores the boolean value (0 or 1) obtained from \fIobjPtr\fR. |
---|
40 | .BE |
---|
41 | |
---|
42 | .SH DESCRIPTION |
---|
43 | .PP |
---|
44 | These procedures are used to pass boolean values to and from |
---|
45 | Tcl as Tcl_Obj's. When storing a boolean value into a Tcl_Obj, |
---|
46 | any non-zero integer value in \fIboolValue\fR is taken to be |
---|
47 | the boolean value \fB1\fR, and the integer value \fB0\fR is |
---|
48 | taken to be the boolean value \fB0\fR. |
---|
49 | .PP |
---|
50 | \fBTcl_NewBooleanObj\fR creates a new Tcl_Obj, stores the boolean |
---|
51 | value \fIboolValue\fR in it, and returns a pointer to the new Tcl_Obj. |
---|
52 | The new Tcl_Obj has reference count of zero. |
---|
53 | .PP |
---|
54 | \fBTcl_SetBooleanObj\fR accepts \fIobjPtr\fR, a pointer to |
---|
55 | an existing Tcl_Obj, and stores in the Tcl_Obj \fI*objPtr\fR |
---|
56 | the boolean value \fIboolValue\fR. This is a write operation |
---|
57 | on \fI*objPtr\fR, so \fIobjPtr\fR must be unshared. Attempts to |
---|
58 | write to a shared Tcl_Obj will panic. A successful write |
---|
59 | of \fIboolValue\fR into \fI*objPtr\fR implies the freeing of |
---|
60 | any former value stored in \fI*objPtr\fR. |
---|
61 | .PP |
---|
62 | \fBTcl_GetBooleanFromObj\fR attempts to retrive a boolean value |
---|
63 | from the value stored in \fI*objPtr\fR. |
---|
64 | If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR, |
---|
65 | then the recognized boolean value is written at the address given |
---|
66 | by \fIboolPtr\fR. |
---|
67 | If \fIobjPtr\fR holds any value recognized as |
---|
68 | a number by Tcl, then if that value is zero a 0 is written at |
---|
69 | the address given by \fIboolPtr\fR and if that |
---|
70 | value is non-zero a 1 is written at the address given by \fIboolPtr\fR. |
---|
71 | In all cases where a value is written at the address given |
---|
72 | by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR. |
---|
73 | If the value of \fIobjPtr\fR does not meet any of the conditions |
---|
74 | above, then \fBTCL_ERROR\fR is returned and an error message is |
---|
75 | left in the interpreter's result unless \fIinterp\fR is NULL. |
---|
76 | \fBTcl_GetBooleanFromObj\fR may also make changes to the internal |
---|
77 | fields of \fI*objPtr\fR so that future calls to |
---|
78 | \fBTcl_GetBooleanFromObj\fR on the same \fIobjPtr\fR can be |
---|
79 | performed more efficiently. |
---|
80 | .PP |
---|
81 | Note that the routines \fBTcl_GetBooleanFromObj\fR and |
---|
82 | \fBTcl_GetBoolean\fR are not functional equivalents. |
---|
83 | The set of values for which \fBTcl_GetBooleanFromObj\fR |
---|
84 | will return \fBTCL_OK\fR is strictly larger than |
---|
85 | the set of values for which \fBTcl_GetBoolean\fR will do the same. |
---|
86 | For example, the value |
---|
87 | .QW 5 |
---|
88 | passed to \fBTcl_GetBooleanFromObj\fR |
---|
89 | will lead to a \fBTCL_OK\fR return (and the boolean value 1), |
---|
90 | while the same value passed to \fBTcl_GetBoolean\fR will lead to |
---|
91 | a \fBTCL_ERROR\fR return. |
---|
92 | |
---|
93 | .SH "SEE ALSO" |
---|
94 | Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean |
---|
95 | |
---|
96 | .SH KEYWORDS |
---|
97 | boolean, object |
---|