diff options
Diffstat (limited to 'doc/CrtMathFnc.3')
| -rw-r--r-- | doc/CrtMathFnc.3 | 91 |
1 files changed, 44 insertions, 47 deletions
diff --git a/doc/CrtMathFnc.3 b/doc/CrtMathFnc.3 index 43ba8fd..9629912 100644 --- a/doc/CrtMathFnc.3 +++ b/doc/CrtMathFnc.3 @@ -17,20 +17,17 @@ Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and void \fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR) .sp -.VS 8.4 int -\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr, clientDataPtr\fR) +\fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr, + clientDataPtr\fR) .sp Tcl_Obj * \fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR) -.VE .SH ARGUMENTS -.AS Tcl_ValueType *clientDataPtr +.AS Tcl_ValueType *clientDataPtr out .AP Tcl_Interp *interp in Interpreter in which new function will be defined. -.VS 8.4 -.AP "CONST char" *name in -.VE +.AP "const char" *name in Name for new function. .AP int numArgs in Number of arguments to new function; also gives size of \fIargTypes\fR array. @@ -51,12 +48,12 @@ will need to be freed up using \fITcl_Free\fR. .AP Tcl_MathProc **procPtr out Points to a variable that will be set to contain a pointer to the implementation code for the function (or NULL if the function is -implemented directly in bytecode.) +implemented directly in bytecode). .AP ClientData *clientDataPtr out Points to a variable that will be set to contain the clientData argument passed to \fITcl_CreateMathFunc\fR when the function was created if the function is not implemented directly in bytecode. -.AP "CONST char" *pattern in +.AP "const char" *pattern in Pattern to match against function names so as to filter them (by passing to \fITcl_StringMatch\fR), or NULL to not apply any filter. .BE @@ -65,71 +62,70 @@ passing to \fITcl_StringMatch\fR), or NULL to not apply any filter. .PP Tcl allows a number of mathematical functions to be used in expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR. -\fBTcl_CreateMathFunc\fR allows applications to add additional functions +These functions are represented by commands in the namespace, +\fBtcl::mathfunc\fR. The \fBTcl_CreateMathFunc\fR function is +an obsolete way for applications to add additional functions to those already provided by Tcl or to replace existing functions. +It should not be used by new applications, which should create +math functions using \fBTcl_CreateObjCommand\fR to create a command +in the \fBtcl::mathfunc\fR namespace. +.PP +In the \fBTcl_CreateMathFunc\fR interface, \fIName\fR is the name of the function as it will appear in expressions. -If \fIname\fR doesn't already exist as a function then a new function -is created. If it does exist, then the existing function is replaced. +If \fIname\fR does not already exist in the \fB::tcl::mathfunc\fR +namespace, then a new command is created in that namespace. +If \fIname\fR does exist, then the existing function is replaced. \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function. Each entry in the \fIargTypes\fR array must be -.VS 8.4 -one of TCL_INT, TCL_DOUBLE, TCL_WIDE_INT, -or TCL_EITHER to indicate whether the corresponding argument must be an +one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR, \fBTCL_WIDE_INT\fR, +or \fBTCL_EITHER\fR to indicate whether the corresponding argument must be an integer, a double-precision floating value, a wide (64-bit) integer, or any, respectively. -.VE 8.4 .PP Whenever the function is invoked in an expression Tcl will invoke \fIproc\fR. \fIProc\fR should have arguments and result that match the type \fBTcl_MathProc\fR: .CS typedef int Tcl_MathProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - Tcl_Value *\fIargs\fR, - Tcl_Value *\fIresultPtr\fR); + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + Tcl_Value *\fIargs\fR, + Tcl_Value *\fIresultPtr\fR); .CE .PP When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR. \fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures, which describe the actual arguments to the function: -.VS 8.4 .CS typedef struct Tcl_Value { - Tcl_ValueType \fItype\fR; - long \fIintValue\fR; - double \fIdoubleValue\fR; - Tcl_WideInt \fIwideValue\fR; + Tcl_ValueType \fItype\fR; + long \fIintValue\fR; + double \fIdoubleValue\fR; + Tcl_WideInt \fIwideValue\fR; } Tcl_Value; .CE .PP The \fItype\fR field indicates the type of the argument and is -one of TCL_INT, TCL_DOUBLE or TCL_WIDE_INT. -.VE 8.4 +one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR. It will match the \fIargTypes\fR value specified for the function unless -the \fIargTypes\fR value was TCL_EITHER. Tcl converts +the \fIargTypes\fR value was \fBTCL_EITHER\fR. Tcl converts the argument supplied in the expression to the type requested in \fIargTypes\fR, if that is necessary. Depending on the value of the \fItype\fR field, the \fIintValue\fR, -.VS 8.4 \fIdoubleValue\fR or \fIwideValue\fR -.VE 8.4 field will contain the actual value of the argument. .PP \fIProc\fR should compute its result and store it either as an integer in \fIresultPtr->intValue\fR or as a floating value in \fIresultPtr->doubleValue\fR. It should set also \fIresultPtr->type\fR to one of -.VS 8.4 -TCL_INT, TCL_DOUBLE or TCL_WIDE_INT -.VE 8.4 +\fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR to indicate which value was set. -Under normal circumstances \fIproc\fR should return TCL_OK. +Under normal circumstances \fIproc\fR should return \fBTCL_OK\fR. If an error occurs while executing the function, \fIproc\fR should -return TCL_ERROR and leave an error message in the interpreter's result. +return \fBTCL_ERROR\fR and leave an error message in the interpreter's result. .PP -.VS 8.4 \fBTcl_GetMathFuncInfo\fR retrieves the values associated with function \fIname\fR that were passed to a preceding \fBTcl_CreateMathFunc\fR call. Normally, the return code is @@ -140,20 +136,21 @@ result. If an error did not occur, the array reference placed in the variable pointed to by \fIargTypesPtr\fR is newly allocated, and should be released by passing it to \fBTcl_Free\fR. Some functions (the -standard set implemented in the core) are implemented directly at the -bytecode level; attempting to retrieve values for them causes a NULL -to be stored in the variable pointed to by \fIprocPtr\fR and the -variable pointed to by \fIclientDataPtr\fR will not be modified. +standard set implemented in the core, and those defined by placing +commands in the \fBtcl::mathfunc\fR namespace) do not have +argument type information; attempting to retrieve values for +them causes a NULL to be stored in the variable pointed to by +\fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR +will not be modified. The variable pointed to by \fInumArgsPointer\fR +will contain -1, and no argument types will be stored in the variable +pointed to by \fIargTypesPointer\fR. .PP \fBTcl_ListMathFuncs\fR returns a Tcl object containing a list of all the math functions defined in the interpreter whose name matches -\fIpattern\fR. In the case of an error, NULL is returned and an error -message is left in the interpreter result, and otherwise the returned -object will have a reference count of zero. -.VE +\fIpattern\fR. The returned object has a reference count of zero. + +.SH "SEE ALSO" +expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3) .SH KEYWORDS expression, mathematical function - -.SH "SEE ALSO" -expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3) |