tcl/doc/ExprLongObj.3

   1 '\"
   2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id$
   8 '\"
   9 .so man.macros
  10 .TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures"
  11 .BS
  12 .SH NAME
  13 Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj \- evaluate an expression
  14 .SH SYNOPSIS
  15 .nf
  16 \fB#include <tcl.h>\fR
  17 .sp
  18 int
  19 \fBTcl_ExprLongObj\fR(\fIinterp, objPtr, longPtr\fR)
  20 .sp
  21 int
  22 \fBTcl_ExprDoubleObj\fR(\fIinterp, objPtr, doublePtr\fR)
  23 .sp
  24 int
  25 \fBTcl_ExprBooleanObj\fR(\fIinterp, objPtr, booleanPtr\fR)
  26 .sp
  27 int
  28 \fBTcl_ExprObj\fR(\fIinterp, objPtr, resultPtrPtr\fR)
  29 .SH ARGUMENTS
  30 .AS Tcl_Interp **resultPtrPtr out
  31 .AP Tcl_Interp *interp in
  32 Interpreter in whose context to evaluate \fIstring\fR or \fIobjPtr\fR.
  33 .AP Tcl_Obj *objPtr in
  34 Pointer to an object containing the expression to evaluate.
  35 .AP long *longPtr out
  36 Pointer to location in which to store the integer value of the
  37 expression.
  38 .AP int *doublePtr out
  39 Pointer to location in which to store the floating-point value of the
  40 expression.
  41 .AP int *booleanPtr out
  42 Pointer to location in which to store the 0/1 boolean value of the
  43 expression.
  44 .AP Tcl_Obj **resultPtrPtr out
  45 Pointer to location in which to store a pointer to the object
  46 that is the result of the expression.
  47 .BE
  48
  49 .SH DESCRIPTION
  50 .PP
  51 These four procedures all evaluate an expression, returning
  52 the result in one of four different forms.
  53 The expression is given by the \fIobjPtr\fR argument, and it
  54 can have any of the forms accepted by the \fBexpr\fR command.
  55 .PP
  56 The \fIinterp\fR argument refers to an interpreter used to
  57 evaluate the expression (e.g. for variables and nested Tcl
  58 commands) and to return error information.
  59 .PP
  60 For all of these procedures the return value is a standard
  61 Tcl result: \fBTCL_OK\fR means the expression was successfully
  62 evaluated, and \fBTCL_ERROR\fR means that an error occurred while
  63 evaluating the expression.
  64 If \fBTCL_ERROR\fR is returned,
  65 then a message describing the error
  66 can be retrieved using \fBTcl_GetObjResult\fR.
  67 If an error occurs while executing a Tcl command embedded in
  68 the expression then that error will be returned.
  69 .PP
  70 If the expression is successfully evaluated, then its value is
  71 returned in one of four forms, depending on which procedure
  72 is invoked.
  73 \fBTcl_ExprLongObj\fR stores an integer value at \fI*longPtr\fR.
  74 If the expression's actual value is a floating-point number,
  75 then it is truncated to an integer.
  76 If the expression's actual value is a non-numeric string then
  77 an error is returned.
  78 .PP
  79 \fBTcl_ExprDoubleObj\fR stores a floating-point value at \fI*doublePtr\fR.
  80 If the expression's actual value is an integer, it is converted to
  81 floating-point.
  82 If the expression's actual value is a non-numeric string then
  83 an error is returned.
  84 .PP
  85 \fBTcl_ExprBooleanObj\fR stores a 0/1 integer value at \fI*booleanPtr\fR.
  86 If the expression's actual value is an integer or floating-point
  87 number, then they store 0 at \fI*booleanPtr\fR if
  88 the value was zero and 1 otherwise.
  89 If the expression's actual value is a non-numeric string then
  90 it must be one of the values accepted by \fBTcl_GetBoolean\fR
  91 such as ``yes'' or ``no'', or else an error occurs.
  92 .PP
  93 If \fBTcl_ExprObj\fR successfully evaluates the expression,
  94 it stores a pointer to the Tcl object
  95 containing the expression's value at \fI*resultPtrPtr\fR.
  96 In this case, the caller is responsible for calling
  97 \fBTcl_DecrRefCount\fR to decrement the object's reference count
  98 when it is finished with the object.
  99
 100 .SH "SEE ALSO"
 101 Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
 102
 103 .SH KEYWORDS
 104 boolean, double, evaluate, expression, integer, object, string