96 lines
3.6 KiB
Groff
96 lines
3.6 KiB
Groff
|
'\"
|
||
|
|
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||
|
|
'\" Contributions from Don Porter, NIST, 2005. (not subject to US copyright)
|
||
|
|
'\"
|
||
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
||
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||
|
|
'\"
|
||
|
|
.TH Tcl_BooleanObj 3 8.5 Tcl "Tcl Library Procedures"
|
||
|
|
.so man.macros
|
||
|
|
.BS
|
||
|
|
.SH NAME
|
||
|
|
Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- store/retrieve boolean value in a Tcl_Obj
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
\fB#include <tcl.h>\fR
|
||
|
|
.sp
|
||
|
|
Tcl_Obj *
|
||
|
|
\fBTcl_NewBooleanObj\fR(\fIboolValue\fR)
|
||
|
|
.sp
|
||
|
|
\fBTcl_SetBooleanObj\fR(\fIobjPtr, boolValue\fR)
|
||
|
|
.sp
|
||
|
|
int
|
||
|
|
\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
|
||
|
|
.SH ARGUMENTS
|
||
|
|
.AS Tcl_Interp boolValue in/out
|
||
|
|
.AP int boolValue in
|
||
|
|
Integer value to be stored as a boolean value in a Tcl_Obj.
|
||
|
|
.AP Tcl_Obj *objPtr in/out
|
||
|
|
Points to the Tcl_Obj in which to store, or from which to
|
||
|
|
retrieve a boolean value.
|
||
|
|
.AP Tcl_Interp *interp in/out
|
||
|
|
If a boolean value cannot be retrieved,
|
||
|
|
an error message is left in the interpreter's result value
|
||
|
|
unless \fIinterp\fR is NULL.
|
||
|
|
.AP int *boolPtr out
|
||
|
|
Points to place where \fBTcl_GetBooleanFromObj\fR
|
||
|
|
stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
|
||
|
|
.BE
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
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 \fIboolValue\fR is taken to be
|
||
|
|
the boolean value \fB1\fR, and the integer value \fB0\fR is
|
||
|
|
taken to be the boolean value \fB0\fR.
|
||
|
|
.PP
|
||
|
|
\fBTcl_NewBooleanObj\fR creates a new Tcl_Obj, stores the boolean
|
||
|
|
value \fIboolValue\fR in it, and returns a pointer to the new Tcl_Obj.
|
||
|
|
The new Tcl_Obj has reference count of zero.
|
||
|
|
.PP
|
||
|
|
\fBTcl_SetBooleanObj\fR accepts \fIobjPtr\fR, a pointer to
|
||
|
|
an existing Tcl_Obj, and stores in the Tcl_Obj \fI*objPtr\fR
|
||
|
|
the boolean value \fIboolValue\fR. This is a write operation
|
||
|
|
on \fI*objPtr\fR, so \fIobjPtr\fR must be unshared. Attempts to
|
||
|
|
write to a shared Tcl_Obj will panic. A successful write
|
||
|
|
of \fIboolValue\fR into \fI*objPtr\fR implies the freeing of
|
||
|
|
any former value stored in \fI*objPtr\fR.
|
||
|
|
.PP
|
||
|
|
\fBTcl_GetBooleanFromObj\fR attempts to retrieve a boolean value
|
||
|
|
from the value stored in \fI*objPtr\fR.
|
||
|
|
If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR,
|
||
|
|
then the recognized boolean value is written at the address given
|
||
|
|
by \fIboolPtr\fR.
|
||
|
|
If \fIobjPtr\fR holds any value recognized as
|
||
|
|
a number by Tcl, then if that value is zero a 0 is written at
|
||
|
|
the address given by \fIboolPtr\fR and if that
|
||
|
|
value is non-zero a 1 is written at the address given by \fIboolPtr\fR.
|
||
|
|
In all cases where a value is written at the address given
|
||
|
|
by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
|
||
|
|
If the value of \fIobjPtr\fR does not meet any of the conditions
|
||
|
|
above, then \fBTCL_ERROR\fR is returned and an error message is
|
||
|
|
left in the interpreter's result unless \fIinterp\fR is NULL.
|
||
|
|
\fBTcl_GetBooleanFromObj\fR may also make changes to the internal
|
||
|
|
fields of \fI*objPtr\fR so that future calls to
|
||
|
|
\fBTcl_GetBooleanFromObj\fR on the same \fIobjPtr\fR can be
|
||
|
|
performed more efficiently.
|
||
|
|
.PP
|
||
|
|
Note that the routines \fBTcl_GetBooleanFromObj\fR and
|
||
|
|
\fBTcl_GetBoolean\fR are not functional equivalents.
|
||
|
|
The set of values for which \fBTcl_GetBooleanFromObj\fR
|
||
|
|
will return \fBTCL_OK\fR is strictly larger than
|
||
|
|
the set of values for which \fBTcl_GetBoolean\fR will do the same.
|
||
|
|
For example, the value
|
||
|
|
.QW 5
|
||
|
|
passed to \fBTcl_GetBooleanFromObj\fR
|
||
|
|
will lead to a \fBTCL_OK\fR return (and the boolean value 1),
|
||
|
|
while the same value passed to \fBTcl_GetBoolean\fR will lead to
|
||
|
|
a \fBTCL_ERROR\fR return.
|
||
|
|
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
Tcl_NewObj, Tcl_IsShared, Tcl_GetBoolean
|
||
|
|
|
||
|
|
.SH KEYWORDS
|
||
|
|
boolean, value
|