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 #include <tcl.h>
13 void
15 Tcl_CreateMathFunc(interp, name, numArgs, argTypes, proc, clientData)
16 int │
18 Tcl_GetMathFuncInfo(interp, name, numArgsPtr, argTypesPtr, procPtr, clientDataPtr)│
19 Tcl_Obj * │
21 Tcl_ListMathFuncs(interp, pattern) │
22
24 Tcl_Interp *interp (in) Interpreter in which new
25 function will be defined. │
26 CONST char *name (in) │
28 Name for new function.
29 int numArgs (in) Number of arguments to new
31 function; also gives size
32 of argTypes array.
33 Tcl_ValueType *argTypes (in) Points to an array giving
35 the permissible types for
36 each argument to function.
37 Tcl_MathProc *proc (in) Procedure that implements
39 the function.
40 ClientData clientData (in) Arbitrary one-word value to
42 pass to proc when it is
43 invoked.
44 int *numArgsPtr (out) Points to a variable that
46 will be set to contain the
47 number of arguments to the
48 function.
49 Tcl_ValueType **argTypesPtr (out) Points to a variable that
51 will be set to contain a
52 pointer to an array giving
53 the permissible types for
54 each argument to the func‐
55 tion which will need to be
56 freed up using Tcl_Free.
57 Tcl_MathProc **procPtr (out) Points to a variable that
59 will be set to contain a
60 pointer to the implementa‐
61 tion code for the function
62 (or NULL if the function is
63 implemented directly in
64 bytecode.)
65 ClientData *clientDataPtr (out) Points to a variable that
67 will be set to contain the
68 clientData argument passed
69 to Tcl_CreateMathFunc when
70 the function was created if
71 the function is not imple‐
72 mented directly in bytecode.
73 CONST char *pattern (in) Pattern to match against
75 function names so as to fil‐
76 ter them (by passing to
77 Tcl_StringMatch), or NULL to
78 not apply any filter.
79_________________________________________________________________
80
83 Tcl allows a number of mathematical functions to be used in expres‐
84 sions, such as sin, cos, and hypot. Tcl_CreateMathFunc allows applica‐
85 tions to add additional functions to those already provided by Tcl or
86 to replace existing functions. Name is the name of the function as it
87 will appear in expressions. If name doesn't already exist as a func‐
88 tion then a new function is created. If it does exist, then the exist‐
89 ing function is replaced. NumArgs and argTypes describe the arguments
90 to the function. Each entry in the argTypes array must be one of │
91 TCL_INT, TCL_DOUBLE, TCL_WIDE_INT, or TCL_EITHER to indicate whether │
92 the corresponding argument must be an integer, a double-precision │
93 floating value, a wide (64-bit) integer, or any, respectively.
94 Whenever the function is invoked in an expression Tcl will invoke proc.
96 Proc should have arguments and result that match the type Tcl_MathProc:
97 typedef int Tcl_MathProc(
98 ClientData clientData,
99 Tcl_Interp *interp,
100 Tcl_Value *args,
101 Tcl_Value *resultPtr);
102 When proc is invoked the clientData and interp arguments will be the
104 same as those passed to Tcl_CreateMathFunc. Args will point to an
105 array of numArgs Tcl_Value structures, which describe the actual argu‐
106 ments to the function: │
107 typedef struct Tcl_Value { │
108 Tcl_ValueType type; │
109 long intValue; │
110 double doubleValue; │
111 Tcl_WideInt wideValue; │
112 } Tcl_Value; │
113 The type field indicates the type of the argument and is one of │
115 TCL_INT, TCL_DOUBLE or TCL_WIDE_INT. It will match the argTypes value
116 specified for the function unless the argTypes value was TCL_EITHER.
117 Tcl converts the argument supplied in the expression to the type
118 requested in argTypes, if that is necessary. Depending on the value of
119 the type field, the intValue, doubleValue or wideValue field will con‐ │
120 tain the actual value of the argument.
121 Proc should compute its result and store it either as an integer in
123 resultPtr->intValue or as a floating value in resultPtr->doubleValue.
124 It should set also resultPtr->type to one of TCL_INT, TCL_DOUBLE or │
125 TCL_WIDE_INT to indicate which value was set. Under normal circum‐
126 stances proc should return TCL_OK. If an error occurs while executing
127 the function, proc should return TCL_ERROR and leave an error message
128 in the interpreter's result.
129 Tcl_GetMathFuncInfo retrieves the values associated with function name │
131 that were passed to a preceding Tcl_CreateMathFunc call. Normally, the │
132 return code is TCL_OK but if the named function does not exist, │
133 TCL_ERROR is returned and an error message is placed in the inter‐ │
134 preter's result. │
135 If an error did not occur, the array reference placed in the variable │
137 pointed to by argTypesPtr is newly allocated, and should be released by │
138 passing it to Tcl_Free. Some functions (the standard set implemented │
139 in the core) are implemented directly at the bytecode level; attempting │
140 to retrieve values for them causes a NULL to be stored in the variable │
141 pointed to by procPtr and the variable pointed to by clientDataPtr will │
142 not be modified. │
143 Tcl_ListMathFuncs returns a Tcl object containing a list of all the │
145 math functions defined in the interpreter whose name matches pattern. │
146 In the case of an error, NULL is returned and an error message is left │
147 in the interpreter result, and otherwise the returned object will have │
148 a reference count of zero.
149
152 expression, mathematical function
153
156 expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3)
157Tcl 8.4 Tcl_CreateMathFunc(3)