Provided by: tcl8.6-doc_8.6.13+dfsg-2_all bug

NAME

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

NOTICE OF EVENTUAL DEPRECATION

       The Tcl_CreateMathFunc and Tcl_GetMathFuncInfo functions are rendered somewhat obsolete by
       the  ability  to create functions for expressions by placing commands in the tcl::mathfunc
       namespace, as described in the mathfunc manual page; the API described on this page is not
       expected to be maintained indefinitely.

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 value containing a list of all the math functions defined
       in the interpreter whose name matches pattern.  The returned value 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