tcl_createmathfunc(3)

NAME

Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs
- Define, query and enumerate math functions for expres
sions

SYNOPSIS

#include <tcl.h>
void
Tcl_CreateMathFunc(interp, name, numArgs, argTypes,  proc,
clientData)
int
Tcl_GetMathFuncInfo(interp, name, numArgsPtr, argTypesPtr,
procPtr, clientDataPtr)
Tcl_Obj *
Tcl_ListMathFuncs(interp, pattern)

ARGUMENTS

Tcl_Interp *interp (in) Interpreter in

which new func
tion will be
defined.

CONST
char *name (in)

Name for new
function.

int numArgs (in) Number of argu

ments to new
function; also
gives size of
argTypes array.

Tcl_ValueType *argTypes (in) Points to an

array giving
the permissible
types for each
argument to
function.

Tcl_MathProc *proc (in) Procedure that

implements the
function.

ClientData clientData (in) Arbitrary one

word value to
pass to proc
when it is
invoked.

int *numArgsPtr (out) Points to a

variable that
will be set to
contain the
number of argu
ments to the
function.

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
Tcl_Free.

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.)

ClientData *clientDataPtr (out) Points to a

variable that
will be set to
contain the
clientData
argument passed
to Tcl_Cre_ ateMathFunc when the func
tion was cre
ated if the
function is not
implemented
directly in
bytecode.

CONST char *pattern (in) Pattern to

match against
function names
so as to filter
them (by pass
ing to
Tcl_String_ Match), or NULL
to not apply
any filter.

DESCRIPTION

Tcl allows a number of mathematical functions to be used
in expressions, such as sin, cos, and hypot. Tcl_Cre ateMathFunc allows applications to add additional func tions to those already provided by Tcl or to replace
existing functions. Name is the name of the function as
it will appear in expressions. If name doesn't already
exist as a function then a new function is created. If it
does exist, then the existing function is replaced.
NumArgs and argTypes describe the arguments to the function. Each entry in the argTypes array must be either TCL_INT, TCL_DOUBLE, or TCL_EITHER to indicate whether the
corresponding argument must be an integer, a double-preci
sion floating value, or either, respectively.

Whenever the function is invoked in an expression Tcl will
invoke proc. Proc should have arguments and result that match the type Tcl_MathProc:

typedef int Tcl_MathProc(

ClientData clientData,
Tcl_Interp *interp,
Tcl_Value *args,
Tcl_Value *resultPtr);

When proc is invoked the clientData and interp arguments will be the same as those passed to Tcl_CreateMathFunc. Args will point to an array of numArgs Tcl_Value struc tures, which describe the actual arguments to the func
tion:

typedef struct Tcl_Value {

Tcl_ValueType type;
long intValue;
double doubleValue;

} Tcl_Value;

The type field indicates the type of the argument and is
either TCL_INT or TCL_DOUBLE. It will match the argTypes value specified for the function unless the argTypes value was TCL_EITHER. Tcl converts the argument supplied in the
expression to the type requested in argTypes, if that is necessary. Depending on the value of the type field, the
intValue or doubleValue field will contain the actual value of the argument.

Proc should compute its result and store it either as an
integer in resultPtr->intValue or as a floating value in resultPtr->doubleValue. It should set also resultPtr->type to either TCL_INT or TCL_DOUBLE to indi cate which value was set. Under normal circumstances proc
should return TCL_OK. If an error occurs while executing
the function, proc should return TCL_ERROR and leave an
error message in the interpreter's result.

Tcl_GetMathFuncInfo retrieves the values associated with function name that were passed to a preceding Tcl_Cre ateMathFunc call. Normally, the return code is TCL_OK but if the named function does not exist, TCL_ERROR is returned and an error message is placed in the inter
preter's result.

If an error did not occur, the array reference placed in
the variable pointed to by argTypesPtr is newly allocated, and should be released by passing it to Tcl_Free. 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 procPtr and the variable pointed to by clientDataPtr will not be modified.

Tcl_ListMathFuncs returns a Tcl object containing a list of all the math functions defined in the interpreter whose
name matches pattern. 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 ref
erence count of zero.

KEYWORDS

expression, mathematical function

SEE ALSO

expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3)

Tcl 8.4 Tcl_CreateMathFunc(3)