'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: BoolObj.3,v 1.7 2005/05/10 18:33:54 kennykb Exp $
'\" 
.so man.macros
.TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- manipulate Tcl objects as boolean values
.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 used to initialize or set a boolean object.
If the integer is nonzero, the boolean object is set to 1;
otherwise the boolean object is set to 0.
.AP Tcl_Obj *objPtr in/out
For \fBTcl_SetBooleanObj\fR, this points to the object to be converted
to boolean type.
For \fBTcl_GetBooleanFromObj\fR, this refers to the object
from which to get a boolean value; 
if \fIobjPtr\fR does not already point to a boolean object,
an attempt will be made to convert it to one.
.AP Tcl_Interp *interp in/out
If an error occurs during conversion,
an error message is left in the interpreter's result object
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 create, modify, and read
boolean Tcl objects from C code.
\fBTcl_NewBooleanObj\fR and \fBTcl_SetBooleanObj\fR
will create a new object of boolean type
or modify an existing object to have boolean type. 
Both of these procedures set the object to have the
boolean value (0 or 1) specified by \fIboolValue\fR;
if \fIboolValue\fR is nonzero, the object is set to 1,
otherwise to 0.
\fBTcl_NewBooleanObj\fR returns a pointer to a newly created object
with reference count zero.
Both procedures set the object's type to be boolean
and assign the boolean value to the object's internal representation
\fIlongValue\fR member.
\fBTcl_SetBooleanObj\fR invalidates any old string representation
and, if the object is not already a boolean object,
frees any old internal representation.
.PP
\fBTcl_GetBooleanFromObj\fR attempts to return a boolean value
corresponding to the value of the Tcl object \fIobjPtr\fR.
If \fIobjPtr\fR is of the boolean type, its boolean value
is written at the address given by \fIboolPtr\fR.  
If \fIobjPtr\fR has a string representation recognized by
\fBTcl_GetBoolean\fR, then \fIobjPtr\fR is converted to boolean
type and its 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_OK\fR is returned.
If the value of \fIobjPtr\fR does not meet any of the conditions
above, then \fBTCL_ERROR\fR is returned and error message is 
left in the interpreter's result unless \fIinterp\fR is NULL.
.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 "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_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult,
Tcl_GetBoolean

.SH KEYWORDS
boolean, boolean object, boolean type, internal representation, object, object type, string representation