tcl/doc/CrtMathFnc.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   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$
   9 '\"
  10 .so man.macros
  11 .TH Tcl_CreateMathFunc 3 7.0 Tcl "Tcl Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tcl_CreateMathFunc \- Define a new math function for expressions
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tcl.h>\fR
  18 .sp
  19 \fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
  20 .SH ARGUMENTS
  21 .AS Tcl_ValueType clientData
  22 .AP Tcl_Interp *interp in
  23 Interpreter in which new function will be defined.
  24 .AP char *name in
  25 Name for new function.
  26 .AP int numArgs in
  27 Number of arguments to new function;  also gives size of \fIargTypes\fR array.
  28 .AP Tcl_ValueType *argTypes in
  29 Points to an array giving the permissible types for each argument to
  30 function.
  31 .AP Tcl_MathProc *proc in
  32 Procedure that implements the function.
  33 .AP ClientData clientData in
  34 Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
  35 .BE
  36
  37 .SH DESCRIPTION
  38 .PP
  39 Tcl allows a number of mathematical functions to be used in
  40 expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
  41 \fBTcl_CreateMathFunc\fR allows applications to add additional functions
  42 to those already provided by Tcl or to replace existing functions.
  43 \fIName\fR is the name of the function as it will appear in expressions.
  44 If \fIname\fR doesn't already exist as a function then a new function
  45 is created.  If it does exist, then the existing function is replaced.
  46 \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
  47 Each entry in the \fIargTypes\fR array must be either TCL_INT, TCL_DOUBLE,
  48 or TCL_EITHER to indicate whether the corresponding argument must be an
  49 integer, a double-precision floating value, or either, respectively.
  50 .PP
  51 Whenever the function is invoked in an expression Tcl will invoke
  52 \fIproc\fR.  \fIProc\fR should have arguments and result that match
  53 the type \fBTcl_MathProc\fR:
  54 .CS
  55 typedef int Tcl_MathProc(
  56         ClientData \fIclientData\fR,
  57         Tcl_Interp *\fIinterp\fR,
  58         Tcl_Value *\fIargs\fR,
  59         Tcl_Value *\fIresultPtr\fR);
  60 .CE
  61 .PP
  62 When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
  63 arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
  64 \fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
  65 which describe the actual arguments to the function:
  66 .CS
  67 typedef struct Tcl_Value {
  68         Tcl_ValueType \fItype\fR;
  69         long \fIintValue\fR;
  70         double \fIdoubleValue\fR;
  71 } Tcl_Value;
  72 .CE
  73 .PP
  74 The \fItype\fR field indicates the type of the argument and is
  75 either TCL_INT or TCL_DOUBLE.
  76 It will match the \fIargTypes\fR value specified for the function unless
  77 the \fIargTypes\fR value was TCL_EITHER. Tcl converts
  78 the argument supplied in the expression to the type requested in
  79 \fIargTypes\fR, if that is necessary.
  80 Depending on the value of the \fItype\fR field, the \fIintValue\fR
  81 or \fIdoubleValue\fR field will contain the actual value of the argument.
  82 .PP
  83 \fIProc\fR should compute its result and store it either as an integer
  84 in \fIresultPtr->intValue\fR or as a floating value in
  85 \fIresultPtr->doubleValue\fR.
  86 It should set also \fIresultPtr->type\fR to either TCL_INT or TCL_DOUBLE
  87 to indicate which value was set.
  88 Under normal circumstances \fIproc\fR should return TCL_OK.
  89 If an error occurs while executing the function, \fIproc\fR should
  90 return TCL_ERROR and leave an error message in the interpreter's result.
  91
  92 .SH KEYWORDS
  93 expression, mathematical function