'\" '\" Copyright (c) 1989-1993 The Regents of the University of California. '\" Copyright (c) 1994-1996 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: CrtMathFnc.3,v 1.5.14.2 2003/04/16 22:26:16 dkf Exp $ '\" .so man.macros .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures" .BS .SH NAME Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions .SH SYNOPSIS .nf \fB#include \fR .sp void \fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR) .sp .VS 8.4 int \fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr, clientDataPtr\fR) .sp Tcl_Obj * \fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR) .VE .SH ARGUMENTS .AS Tcl_ValueType *clientDataPtr .AP Tcl_Interp *interp in Interpreter in which new function will be defined. .VS 8.4 .AP "CONST char" *name in .VE Name for new function. .AP int numArgs in Number of arguments to new function; also gives size of \fIargTypes\fR array. .AP Tcl_ValueType *argTypes in Points to an array giving the permissible types for each argument to function. .AP Tcl_MathProc *proc in Procedure that implements the function. .AP ClientData clientData in Arbitrary one-word value to pass to \fIproc\fR when it is invoked. .AP int *numArgsPtr out Points to a variable that will be set to contain the number of arguments to the function. .AP Tcl_ValueType **argTypesPtr out Points to a variable that will be set to contain a pointer to an array giving the permissible types for each argument to the function which will need to be freed up using \fITcl_Free\fR. .AP Tcl_MathProc **procPtr out Points to a variable that will be set to contain a pointer to the implementation code for the function (or NULL if the function is implemented directly in bytecode.) .AP ClientData *clientDataPtr out Points to a variable that will be set to contain the clientData argument passed to \fITcl_CreateMathFunc\fR when the function was created if the function is not implemented directly in bytecode. .AP "CONST char" *pattern in Pattern to match against function names so as to filter them (by passing to \fITcl_StringMatch\fR), or NULL to not apply any filter. .BE .SH DESCRIPTION .PP Tcl allows a number of mathematical functions to be used in expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR. \fBTcl_CreateMathFunc\fR allows applications to add additional functions to those already provided by Tcl or to replace existing functions. \fIName\fR is the name of the function as it will appear in expressions. If \fIname\fR doesn't already exist as a function then a new function is created. If it does exist, then the existing function is replaced. \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function. Each entry in the \fIargTypes\fR array must be .VS 8.4 one of TCL_INT, TCL_DOUBLE, TCL_WIDE_INT, or TCL_EITHER to indicate whether the corresponding argument must be an integer, a double-precision floating value, a wide (64-bit) integer, or any, respectively. .VE 8.4 .PP Whenever the function is invoked in an expression Tcl will invoke \fIproc\fR. \fIProc\fR should have arguments and result that match the type \fBTcl_MathProc\fR: .CS typedef int Tcl_MathProc( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, Tcl_Value *\fIargs\fR, Tcl_Value *\fIresultPtr\fR); .CE .PP When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR. \fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures, which describe the actual arguments to the function: .VS 8.4 .CS typedef struct Tcl_Value { Tcl_ValueType \fItype\fR; long \fIintValue\fR; double \fIdoubleValue\fR; Tcl_WideInt \fIwideValue\fR; } Tcl_Value; .CE .PP The \fItype\fR field indicates the type of the argument and is one of TCL_INT, TCL_DOUBLE or TCL_WIDE_INT. .VE 8.4 It will match the \fIargTypes\fR value specified for the function unless the \fIargTypes\fR value was TCL_EITHER. Tcl converts the argument supplied in the expression to the type requested in \fIargTypes\fR, if that is necessary. Depending on the value of the \fItype\fR field, the \fIintValue\fR, .VS 8.4 \fIdoubleValue\fR or \fIwideValue\fR .VE 8.4 field will contain the actual value of the argument. .PP \fIProc\fR should compute its result and store it either as an integer in \fIresultPtr->intValue\fR or as a floating value in \fIresultPtr->doubleValue\fR. It should set also \fIresultPtr->type\fR to one of .VS 8.4 TCL_INT, TCL_DOUBLE or TCL_WIDE_INT .VE 8.4 to indicate which value was set. Under normal circumstances \fIproc\fR should return TCL_OK. If an error occurs while executing the function, \fIproc\fR should return TCL_ERROR and leave an error message in the interpreter's result. .PP .VS 8.4 \fBTcl_GetMathFuncInfo\fR retrieves the values associated with function \fIname\fR that were passed to a preceding \fBTcl_CreateMathFunc\fR call. Normally, the return code is \fBTCL_OK\fR but if the named function does not exist, \fBTCL_ERROR\fR is returned and an error message is placed in the interpreter's result. .PP If an error did not occur, the array reference placed in the variable pointed to by \fIargTypesPtr\fR is newly allocated, and should be released by passing it to \fBTcl_Free\fR. Some functions (the standard set implemented in the core) are implemented directly at the bytecode level; attempting to retrieve values for them causes a NULL to be stored in the variable pointed to by \fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR will not be modified. .PP \fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all the math functions defined in the interpreter whose name matches \fIpattern\fR. In the case of an error, NULL is returned and an error message is left in the interpreter result, and otherwise the returned object will have a reference count of zero. .VE .SH KEYWORDS expression, mathematical function .SH "SEE ALSO" expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3)