1Tcl_CreateMathFunc(3) Tcl Library Procedures Tcl_CreateMathFunc(3)
2______________________________________________________________________________
6
8 Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs - Define,
9 query and enumerate math functions for expressions
10
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
19 #include <tcl.h>
20 void
22 Tcl_CreateMathFunc(interp, name, numArgs, argTypes, proc, clientData)
23 int
25 Tcl_GetMathFuncInfo(interp, name, numArgsPtr, argTypesPtr, procPtr,
26 clientDataPtr)
27 Tcl_Obj *
29 Tcl_ListMathFuncs(interp, pattern)
30
32 Tcl_Interp *interp (in) Interpreter in which new
33 function will be defined.
34 const char *name (in) Name for new function.
36 int numArgs (in) Number of arguments to new
38 function; also gives size
39 of argTypes array.
40 Tcl_ValueType *argTypes (in) Points to an array giving
42 the permissible types for
43 each argument to function.
44 Tcl_MathProc *proc (in) Procedure that implements
46 the function.
47 ClientData clientData (in) Arbitrary one-word value to
49 pass to proc when it is
50 invoked.
51 int *numArgsPtr (out) Points to a variable that
53 will be set to contain the
54 number of arguments to the
55 function.
56 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 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 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 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
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 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 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 typedef int Tcl_MathProc(
112 ClientData clientData,
113 Tcl_Interp *interp,
114 Tcl_Value *args,
115 Tcl_Value *resultPtr);
116 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 typedef struct Tcl_Value {
123 Tcl_ValueType type;
124 long intValue;
125 double doubleValue;
126 Tcl_WideInt wideValue;
127 } Tcl_Value;
128 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 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 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 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 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
167 expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewLis‐
168 tObj(3)
169
171 expression, mathematical function
172Tcl 8.4 Tcl_CreateMathFunc(3)