NAME¶
Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs - Define, query and
enumerate math functions for expressions
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 function will be defined.
- const char *name (in)
- Name for new function.
- int numArgs (in)
- Number of arguments 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 arguments
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_CreateMathFunc when the function was created 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 passing
to Tcl_StringMatch), 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. These functions are represented by
commands in the namespace,
tcl::mathfunc. The
Tcl_CreateMathFunc
function is an obsolete way for applications to add additional functions to
those already provided by Tcl or to replace existing functions. It should not
be used by new applications, which should create math functions using
Tcl_CreateObjCommand to create a command in the
tcl::mathfunc
namespace.
In the
Tcl_CreateMathFunc interface,
Name is the name of the
function as it will appear in expressions. If
name does not already
exist in the
::tcl::mathfunc namespace, then a new command is created
in that namespace. If
name 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 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.
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 structures, which describe
the actual arguments to the function:
typedef struct Tcl_Value {
Tcl_ValueType type;
long intValue;
double doubleValue;
Tcl_WideInt wideValue;
} Tcl_Value;
The
type field indicates the type of the argument and is one of
TCL_INT,
TCL_DOUBLE or
TCL_WIDE_INT. 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,
doubleValue or
wideValue 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 one of
TCL_INT,
TCL_DOUBLE or
TCL_WIDE_INT to indicate
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_CreateMathFunc 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
interpreter'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,
and those defined by placing commands in the
tcl::mathfunc namespace)
do not have argument type information; 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. The
variable pointed to by
numArgsPointer will contain -1, and no argument
types will be stored in the variable pointed to by
argTypesPointer.
Tcl_ListMathFuncs returns a Tcl object containing a list of all the math
functions defined in the interpreter whose name matches
pattern. The
returned object has a reference count of zero.
SEE ALSO¶
expr(3tcl), info(3tcl), Tcl_CreateObjCommand(3tcl), Tcl_Free(3tcl),
Tcl_NewListObj(3tcl)
KEYWORDS¶
expression, mathematical function