1Tcl_CreateMathFunc(3)       Tcl Library Procedures       Tcl_CreateMathFunc(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

NOTICE OF EVENTUAL DEPRECATION

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

SYNOPSIS

19       #include <tcl.h>
20
21       void
22       Tcl_CreateMathFunc(interp, name, numArgs, argTypes, proc, clientData)
23
24       int
25       Tcl_GetMathFuncInfo(interp, name, numArgsPtr, argTypesPtr, procPtr,
26                           clientDataPtr)
27
28       Tcl_Obj *
29       Tcl_ListMathFuncs(interp, pattern)
30

ARGUMENTS

32       Tcl_Interp *interp (in)                    Interpreter  in  which   new
33                                                  function will be defined.
34
35       const char *name (in)                      Name for new function.
36
37       int numArgs (in)                           Number  of  arguments to new
38                                                  function;  also  gives  size
39                                                  of argTypes array.
40
41       Tcl_ValueType *argTypes (in)               Points  to  an  array giving
42                                                  the  permissible  types  for
43                                                  each argument to function.
44
45       Tcl_MathProc *proc (in)                    Procedure   that  implements
46                                                  the function.
47
48       ClientData clientData (in)                 Arbitrary one-word value  to
49                                                  pass  to  proc  when  it  is
50                                                  invoked.
51
52       int *numArgsPtr (out)                      Points to  a  variable  that
53                                                  will  be  set to contain the
54                                                  number of arguments  to  the
55                                                  function.
56
57       Tcl_ValueType **argTypesPtr (out)          Points  to  a  variable that
58                                                  will be  set  to  contain  a
59                                                  pointer  to  an array giving
60                                                  the  permissible  types  for
61                                                  each  argument  to the func‐
62                                                  tion which will need  to  be
63                                                  freed up using Tcl_Free.
64
65       Tcl_MathProc **procPtr (out)               Points  to  a  variable that
66                                                  will be  set  to  contain  a
67                                                  pointer  to  the implementa‐
68                                                  tion code for  the  function
69                                                  (or  NULL if the function is
70                                                  implemented   directly    in
71                                                  bytecode).
72
73       ClientData *clientDataPtr (out)            Points  to  a  variable that
74                                                  will be set to  contain  the
75                                                  clientData  argument  passed
76                                                  to  Tcl_CreateMathFunc  when
77                                                  the  function was created if
78                                                  the function is  not  imple‐
79                                                  mented directly in bytecode.
80
81       const char *pattern (in)                   Pattern   to  match  against
82                                                  function names so as to fil‐
83                                                  ter   them  (by  passing  to
84                                                  Tcl_StringMatch), or NULL to
85                                                  not apply any filter.
86______________________________________________________________________________
87

DESCRIPTION

89       Tcl  allows  a  number  of mathematical functions to be used in expres‐
90       sions, such as sin, cos, and hypot.  These functions are represented by
91       commands in the namespace, tcl::mathfunc.  The Tcl_CreateMathFunc func‐
92       tion is an obsolete way for applications to add additional functions to
93       those  already  provided  by  Tcl or to replace existing functions.  It
94       should not be used by new applications, which should create math  func‐
95       tions  using Tcl_CreateObjCommand to create a command in the tcl::math‐
96       func namespace.
97
98       In the Tcl_CreateMathFunc interface, Name is the name of  the  function
99       as  it  will  appear in expressions.  If name does not already exist in
100       the ::tcl::mathfunc namespace, then a new command is  created  in  that
101       namespace.  If name does exist, then the existing function is replaced.
102       NumArgs and argTypes describe the  arguments  to  the  function.   Each
103       entry  in  the  argTypes  array  must  be  one  of TCL_INT, TCL_DOUBLE,
104       TCL_WIDE_INT, or TCL_EITHER to indicate whether the corresponding argu‐
105       ment  must  be  an  integer,  a double-precision floating value, a wide
106       (64-bit) integer, or any, respectively.
107
108       Whenever the function is invoked in an expression Tcl will invoke proc.
109       Proc should have arguments and result that match the type Tcl_MathProc:
110
111              typedef int Tcl_MathProc(
112                      ClientData clientData,
113                      Tcl_Interp *interp,
114                      Tcl_Value *args,
115                      Tcl_Value *resultPtr);
116
117       When  proc  is  invoked the clientData and interp arguments will be the
118       same as those passed to Tcl_CreateMathFunc.   Args  will  point  to  an
119       array  of numArgs Tcl_Value structures, which describe the actual argu‐
120       ments to the function:
121
122              typedef struct Tcl_Value {
123                  Tcl_ValueType type;
124                  long intValue;
125                  double doubleValue;
126                  Tcl_WideInt wideValue;
127              } Tcl_Value;
128
129       The type field indicates the  type  of  the  argument  and  is  one  of
130       TCL_INT,  TCL_DOUBLE or TCL_WIDE_INT.  It will match the argTypes value
131       specified for the function unless the argTypes  value  was  TCL_EITHER.
132       Tcl  converts  the  argument  supplied  in  the  expression to the type
133       requested in argTypes, if that is necessary.  Depending on the value of
134       the  type field, the intValue, doubleValue or wideValue field will con‐
135       tain the actual value of the argument.
136
137       Proc should compute its result and store it either  as  an  integer  in
138       resultPtr->intValue  or  as a floating value in resultPtr->doubleValue.
139       It should set also resultPtr->type to one  of  TCL_INT,  TCL_DOUBLE  or
140       TCL_WIDE_INT  to  indicate  which  value was set.  Under normal circum‐
141       stances proc should return TCL_OK.  If an error occurs while  executing
142       the  function,  proc should return TCL_ERROR and leave an error message
143       in the interpreter's result.
144
145       Tcl_GetMathFuncInfo retrieves the values associated with function  name
146       that were passed to a preceding Tcl_CreateMathFunc call.  Normally, the
147       return code is TCL_OK  but  if  the  named  function  does  not  exist,
148       TCL_ERROR  is  returned  and  an  error message is placed in the inter‐
149       preter's result.
150
151       If an error did not occur, the array reference placed in  the  variable
152       pointed to by argTypesPtr is newly allocated, and should be released by
153       passing it to Tcl_Free.  Some functions (the standard  set  implemented
154       in the core, and those defined by placing commands in the tcl::mathfunc
155       namespace)  do  not  have  argument  type  information;  attempting  to
156       retrieve  values  for  them  causes a NULL to be stored in the variable
157       pointed to by procPtr and the variable pointed to by clientDataPtr will
158       not  be  modified.  The variable pointed to by numArgsPointer will con‐
159       tain -1, and no argument types will be stored in the  variable  pointed
160       to by argTypesPointer.
161
162       Tcl_ListMathFuncs returns a Tcl value containing a list of all the math
163       functions defined in the interpreter whose name matches  pattern.   The
164       returned value has a reference count of zero.
165

SEE ALSO

167       expr(n),  info(n),  Tcl_CreateObjCommand(3),  Tcl_Free(3),  Tcl_NewLis‐
168       tObj(3)
169

KEYWORDS

171       expression, mathematical function
172
173
174
175Tcl                                   8.4                Tcl_CreateMathFunc(3)
Impressum