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