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 8.4 Tcl "Tcl Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tcl.h>\fR
  18 .sp
  19 void
  20 \fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
  21 .sp
  22 .VS 8.4
  23 int
  24 \fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr, clientDataPtr\fR)
  25 .sp
  26 Tcl_Obj *
  27 \fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR)
  28 .VE
  29 .SH ARGUMENTS
  30 .AS Tcl_ValueType *clientDataPtr
  31 .AP Tcl_Interp *interp in
  32 Interpreter in which new function will be defined.
  33 .VS 8.4
  34 .AP "CONST char" *name in
  35 .VE
  36 Name for new function.
  37 .AP int numArgs in
  38 Number of arguments to new function;  also gives size of \fIargTypes\fR array.
  39 .AP Tcl_ValueType *argTypes in
  40 Points to an array giving the permissible types for each argument to
  41 function.
  42 .AP Tcl_MathProc *proc in
  43 Procedure that implements the function.
  44 .AP ClientData clientData in
  45 Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
  46 .AP int *numArgsPtr out
  47 Points to a variable that will be set to contain the number of
  48 arguments to the function.
  49 .AP Tcl_ValueType *argTypesPtr out
  50 Points to a variable that will be set to contain a pointer to an array
  51 giving the permissible types for each argument to the function which
  52 will need to be freed up using \fITcl_Free\fR.
  53 .AP Tcl_MathProc *procPtr out
  54 Points to a variable that will be set to contain a pointer to the
  55 implementation code for the function (or NULL if the function is
  56 implemented directly in bytecode.)
  57 .AP ClientData *clientDataPtr out
  58 Points to a variable that will be set to contain the clientData
  59 argument passed to \fITcl_CreateMathFunc\fR when the function was
  60 created if the function is not implemented directly in bytecode.
  61 .AP "CONST char" *pattern in
  62 Pattern to match against function names so as to filter them (by
  63 passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
  64 .BE
  65
  66 .SH DESCRIPTION
  67 .PP
  68 Tcl allows a number of mathematical functions to be used in
  69 expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
  70 \fBTcl_CreateMathFunc\fR allows applications to add additional functions
  71 to those already provided by Tcl or to replace existing functions.
  72 \fIName\fR is the name of the function as it will appear in expressions.
  73 If \fIname\fR doesn't already exist as a function then a new function
  74 is created.  If it does exist, then the existing function is replaced.
  75 \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
  76 Each entry in the \fIargTypes\fR array must be either TCL_INT, TCL_DOUBLE,
  77 or TCL_EITHER to indicate whether the corresponding argument must be an
  78 integer, a double-precision floating value, or either, respectively.
  79 .PP
  80 Whenever the function is invoked in an expression Tcl will invoke
  81 \fIproc\fR.  \fIProc\fR should have arguments and result that match
  82 the type \fBTcl_MathProc\fR:
  83 .CS
  84 typedef int Tcl_MathProc(
  85         ClientData \fIclientData\fR,
  86         Tcl_Interp *\fIinterp\fR,
  87         Tcl_Value *\fIargs\fR,
  88         Tcl_Value *\fIresultPtr\fR);
  89 .CE
  90 .PP
  91 When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
  92 arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
  93 \fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
  94 which describe the actual arguments to the function:
  95 .CS
  96 typedef struct Tcl_Value {
  97         Tcl_ValueType \fItype\fR;
  98         long \fIintValue\fR;
  99         double \fIdoubleValue\fR;
 100 } Tcl_Value;
 101 .CE
 102 .PP
 103 The \fItype\fR field indicates the type of the argument and is
 104 either TCL_INT or TCL_DOUBLE.
 105 It will match the \fIargTypes\fR value specified for the function unless
 106 the \fIargTypes\fR value was TCL_EITHER. Tcl converts
 107 the argument supplied in the expression to the type requested in
 108 \fIargTypes\fR, if that is necessary.
 109 Depending on the value of the \fItype\fR field, the \fIintValue\fR
 110 or \fIdoubleValue\fR field will contain the actual value of the argument.
 111 .PP
 112 \fIProc\fR should compute its result and store it either as an integer
 113 in \fIresultPtr->intValue\fR or as a floating value in
 114 \fIresultPtr->doubleValue\fR.
 115 It should set also \fIresultPtr->type\fR to either TCL_INT or TCL_DOUBLE
 116 to indicate which value was set.
 117 Under normal circumstances \fIproc\fR should return TCL_OK.
 118 If an error occurs while executing the function, \fIproc\fR should
 119 return TCL_ERROR and leave an error message in the interpreter's result.
 120 .PP
 121 .VS 8.4
 122 \fBTcl_GetMathFuncInfo\fR retrieves the values associated with
 123 function \fIname\fR that were passed to a preceding
 124 \fBTcl_CreateMathFunc\fR call.  Normally, the return code is
 125 \fBTCL_OK\fR but if the named function does not exist, \fBTCL_ERROR\fR
 126 is returned and an error message is placed in the interpreter's
 127 result.
 128 .PP
 129 If an error did not occur, the array reference placed in the variable
 130 pointed to by \fIargTypesPtr\fR is newly allocated, and should be
 131 released by passing it to \fBTcl_Free\fR.  Some functions (the
 132 standard set implemented in the core) are implemented directly at the
 133 bytecode level; attempting to retrieve values for them causes a NULL
 134 to be stored in the variable pointed to by \fIprocPtr\fR and the
 135 variable pointed to by \fIclientDataPtr\fR will not be modified.
 136 .PP
 137 \fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all
 138 the math functions defined in the interpreter whose name matches
 139 \fIpattern\fR.  In the case of an error, NULL is returned and an error
 140 message is left in the interpreter result, and otherwise the returned
 141 object will have a reference count of zero.
 142 .VE
 143
 144 .SH KEYWORDS
 145 expression, mathematical function
 146
 147 .SH "SEE ALSO"
 148 expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3)