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

SYNOPSIS

12       #include <tcl.h>
13
14       void
15       Tcl_CreateMathFunc(interp, name, numArgs, argTypes, proc, clientData)
16
17       int
18       Tcl_GetMathFuncInfo(interp, name, numArgsPtr, argTypesPtr, procPtr,
19                           clientDataPtr)
20
21       Tcl_Obj *
22       Tcl_ListMathFuncs(interp, pattern)
23

ARGUMENTS

25       Tcl_Interp *interp (in)                    Interpreter  in  which   new
26                                                  function will be defined.
27
28       const char *name (in)                      Name for new function.
29
30       int numArgs (in)                           Number  of  arguments to new
31                                                  function;  also  gives  size
32                                                  of argTypes array.
33
34       Tcl_ValueType *argTypes (in)               Points  to  an  array giving
35                                                  the  permissible  types  for
36                                                  each argument to function.
37
38       Tcl_MathProc *proc (in)                    Procedure   that  implements
39                                                  the function.
40
41       ClientData clientData (in)                 Arbitrary one-word value  to
42                                                  pass  to  proc  when  it  is
43                                                  invoked.
44
45       int *numArgsPtr (out)                      Points to  a  variable  that
46                                                  will  be  set to contain the
47                                                  number of arguments  to  the
48                                                  function.
49
50       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
58       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
66       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
74       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
81

DESCRIPTION

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
92       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
102       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
110       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
121       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
129       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
137       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
143       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
154       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
158

SEE ALSO

160       expr(n),  info(n),  Tcl_CreateObjCommand(3),  Tcl_Free(3),  Tcl_NewLis‐
161       tObj(3)
162
163

KEYWORDS

165       expression, mathematical function
166
167
168
169Tcl                                   8.4                Tcl_CreateMathFunc(3)
Impressum