util/X86LINUX64/man/man3/Tcl_CreateMathFunc.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tcl_CreateMathFunc 3 8.4 Tcl "Tcl Library Procedures"
   9 .\" The -*- nroff -*- definitions below are for supplemental macros used
  10 .\" in Tcl/Tk manual entries.
  11 .\"
  12 .\" .AP type name in/out ?indent?
  13 .\"     Start paragraph describing an argument to a library procedure.
  14 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 .\"     needed;  use .AS below instead)
  18 .\"
  19 .\" .AS ?type? ?name?
  20 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 .\"     name are examples of largest possible arguments that will be passed
  22 .\"     to .AP later.  If args are omitted, default tab stops are used.
  23 .\"
  24 .\" .BS
  25 .\"     Start box enclosure.  From here until next .BE, everything will be
  26 .\"     enclosed in one large box.
  27 .\"
  28 .\" .BE
  29 .\"     End of box enclosure.
  30 .\"
  31 .\" .CS
  32 .\"     Begin code excerpt.
  33 .\"
  34 .\" .CE
  35 .\"     End code excerpt.
  36 .\"
  37 .\" .VS ?version? ?br?
  38 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 .\"     of man pages.  The first argument is ignored and used for recording
  40 .\"     the version when the .VS was added, so that the sidebars can be
  41 .\"     found and removed when they reach a certain age.  If another argument
  42 .\"     is present, then a line break is forced before starting the sidebar.
  43 .\"
  44 .\" .VE
  45 .\"     End of vertical sidebar.
  46 .\"
  47 .\" .DS
  48 .\"     Begin an indented unfilled display.
  49 .\"
  50 .\" .DE
  51 .\"     End of indented unfilled display.
  52 .\"
  53 .\" .SO ?manpage?
  54 .\"     Start of list of standard options for a Tk widget. The manpage
  55 .\"     argument defines where to look up the standard options; if
  56 .\"     omitted, defaults to "options". The options follow on successive
  57 .\"     lines, in three columns separated by tabs.
  58 .\"
  59 .\" .SE
  60 .\"     End of list of standard options for a Tk widget.
  61 .\"
  62 .\" .OP cmdName dbName dbClass
  63 .\"     Start of description of a specific option.  cmdName gives the
  64 .\"     option's name as specified in the class command, dbName gives
  65 .\"     the option's name in the option database, and dbClass gives
  66 .\"     the option's class in the option database.
  67 .\"
  68 .\" .UL arg1 arg2
  69 .\"     Print arg1 underlined, then print arg2 normally.
  70 .\"
  71 .\" .QW arg1 ?arg2?
  72 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  73 .\"
  74 .\" .PQ arg1 ?arg2?
  75 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  76 .\"     (for trailing punctuation) and then a closing parenthesis.
  77 .\"
  78 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  79 .if t .wh -1.3i ^B
  80 .nr ^l \n(.l
  81 .ad b
  82 .\"     # Start an argument description
  83 .de AP
  84 .ie !"\\$4"" .TP \\$4
  85 .el \{\
  86 .   ie !"\\$2"" .TP \\n()Cu
  87 .   el          .TP 15
  88 .\}
  89 .ta \\n()Au \\n()Bu
  90 .ie !"\\$3"" \{\
  91 \&\\$1 \\fI\\$2\\fP (\\$3)
  92 .\".b
  93 .\}
  94 .el \{\
  95 .br
  96 .ie !"\\$2"" \{\
  97 \&\\$1  \\fI\\$2\\fP
  98 .\}
  99 .el \{\
 100 \&\\fI\\$1\\fP
 101 .\}
 102 .\}
 103 ..
 104 .\"     # define tabbing values for .AP
 105 .de AS
 106 .nr )A 10n
 107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 108 .nr )B \\n()Au+15n
 109 .\"
 110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 112 ..
 113 .AS Tcl_Interp Tcl_CreateInterp in/out
 114 .\"     # BS - start boxed text
 115 .\"     # ^y = starting y location
 116 .\"     # ^b = 1
 117 .de BS
 118 .br
 119 .mk ^y
 120 .nr ^b 1u
 121 .if n .nf
 122 .if n .ti 0
 123 .if n \l'\\n(.lu\(ul'
 124 .if n .fi
 125 ..
 126 .\"     # BE - end boxed text (draw box now)
 127 .de BE
 128 .nf
 129 .ti 0
 130 .mk ^t
 131 .ie n \l'\\n(^lu\(ul'
 132 .el \{\
 133 .\"     Draw four-sided box normally, but don't draw top of
 134 .\"     box if the box started on an earlier page.
 135 .ie !\\n(^b-1 \{\
 136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 137 .\}
 138 .el \}\
 139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 140 .\}
 141 .\}
 142 .fi
 143 .br
 144 .nr ^b 0
 145 ..
 146 .\"     # VS - start vertical sidebar
 147 .\"     # ^Y = starting y location
 148 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 149 .de VS
 150 .if !"\\$2"" .br
 151 .mk ^Y
 152 .ie n 'mc \s12\(br\s0
 153 .el .nr ^v 1u
 154 ..
 155 .\"     # VE - end of vertical sidebar
 156 .de VE
 157 .ie n 'mc
 158 .el \{\
 159 .ev 2
 160 .nf
 161 .ti 0
 162 .mk ^t
 163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 164 .sp -1
 165 .fi
 166 .ev
 167 .\}
 168 .nr ^v 0
 169 ..
 170 .\"     # Special macro to handle page bottom:  finish off current
 171 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 172 .\"     # page bottom macro.
 173 .de ^B
 174 .ev 2
 175 'ti 0
 176 'nf
 177 .mk ^t
 178 .if \\n(^b \{\
 179 .\"     Draw three-sided box if this is the box's first page,
 180 .\"     draw two sides but no top otherwise.
 181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .\}
 184 .if \\n(^v \{\
 185 .nr ^x \\n(^tu+1v-\\n(^Yu
 186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 187 .\}
 188 .bp
 189 'fi
 190 .ev
 191 .if \\n(^b \{\
 192 .mk ^y
 193 .nr ^b 2
 194 .\}
 195 .if \\n(^v \{\
 196 .mk ^Y
 197 .\}
 198 ..
 199 .\"     # DS - begin display
 200 .de DS
 201 .RS
 202 .nf
 203 .sp
 204 ..
 205 .\"     # DE - end display
 206 .de DE
 207 .fi
 208 .RE
 209 .sp
 210 ..
 211 .\"     # SO - start of list of standard options
 212 .de SO
 213 'ie '\\$1'' .ds So \\fBoptions\\fR
 214 'el .ds So \\fB\\$1\\fR
 215 .SH "STANDARD OPTIONS"
 216 .LP
 217 .nf
 218 .ta 5.5c 11c
 219 .ft B
 220 ..
 221 .\"     # SE - end of list of standard options
 222 .de SE
 223 .fi
 224 .ft R
 225 .LP
 226 See the \\*(So manual entry for details on the standard options.
 227 ..
 228 .\"     # OP - start of full description for a single option
 229 .de OP
 230 .LP
 231 .nf
 232 .ta 4c
 233 Command-Line Name:      \\fB\\$1\\fR
 234 Database Name:  \\fB\\$2\\fR
 235 Database Class: \\fB\\$3\\fR
 236 .fi
 237 .IP
 238 ..
 239 .\"     # CS - begin code excerpt
 240 .de CS
 241 .RS
 242 .nf
 243 .ta .25i .5i .75i 1i
 244 ..
 245 .\"     # CE - end code excerpt
 246 .de CE
 247 .fi
 248 .RE
 249 ..
 250 .\"     # UL - underline word
 251 .de UL
 252 \\$1\l'|0\(ul'\\$2
 253 ..
 254 .\"     # QW - apply quotation marks to word
 255 .de QW
 256 .ie '\\*(lq'"' ``\\$1''\\$2
 257 .\"" fix emacs highlighting
 258 .el \\*(lq\\$1\\*(rq\\$2
 259 ..
 260 .\"     # PQ - apply parens and quotation marks to word
 261 .de PQ
 262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 263 .\"" fix emacs highlighting
 264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 265 ..
 266 .\"     # QR - quoted range
 267 .de QR
 268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 269 .\"" fix emacs highlighting
 270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 271 ..
 272 .\"     # MT - "empty" string
 273 .de MT
 274 .QW ""
 275 ..
 276 .BS
 277 .SH NAME
 278 Tcl_CreateMathFunc, Tcl_GetMathFuncInfo, Tcl_ListMathFuncs \- Define, query and enumerate math functions for expressions
 279 .SH "NOTICE OF EVENTUAL DEPRECATION"
 280 .PP
 281 The \fBTcl_CreateMathFunc\fR and \fBTcl_GetMathFuncInfo\fR functions
 282 are rendered somewhat obsolete by the ability to create functions for
 283 expressions by placing commands in the \fBtcl::mathfunc\fR namespace,
 284 as described in the \fBmathfunc\fR manual page; the API described on
 285 this page is not expected to be maintained indefinitely.
 286 .SH SYNOPSIS
 287 .nf
 288 \fB#include <tcl.h>\fR
 289 .sp
 290 void
 291 \fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
 292 .sp
 293 int
 294 \fBTcl_GetMathFuncInfo\fR(\fIinterp, name, numArgsPtr, argTypesPtr, procPtr,
 295                     clientDataPtr\fR)
 296 .sp
 297 Tcl_Obj *
 298 \fBTcl_ListMathFuncs\fR(\fIinterp, pattern\fR)
 299 .SH ARGUMENTS
 300 .AS Tcl_ValueType *clientDataPtr out
 301 .AP Tcl_Interp *interp in
 302 Interpreter in which new function will be defined.
 303 .AP "const char" *name in
 304 Name for new function.
 305 .AP int numArgs in
 306 Number of arguments to new function;  also gives size of \fIargTypes\fR array.
 307 .AP Tcl_ValueType *argTypes in
 308 Points to an array giving the permissible types for each argument to
 309 function.
 310 .AP Tcl_MathProc *proc in
 311 Procedure that implements the function.
 312 .AP ClientData clientData in
 313 Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
 314 .AP int *numArgsPtr out
 315 Points to a variable that will be set to contain the number of
 316 arguments to the function.
 317 .AP Tcl_ValueType **argTypesPtr out
 318 Points to a variable that will be set to contain a pointer to an array
 319 giving the permissible types for each argument to the function which
 320 will need to be freed up using \fITcl_Free\fR.
 321 .AP Tcl_MathProc **procPtr out
 322 Points to a variable that will be set to contain a pointer to the
 323 implementation code for the function (or NULL if the function is
 324 implemented directly in bytecode).
 325 .AP ClientData *clientDataPtr out
 326 Points to a variable that will be set to contain the clientData
 327 argument passed to \fITcl_CreateMathFunc\fR when the function was
 328 created if the function is not implemented directly in bytecode.
 329 .AP "const char" *pattern in
 330 Pattern to match against function names so as to filter them (by
 331 passing to \fITcl_StringMatch\fR), or NULL to not apply any filter.
 332 .BE
 333 .SH DESCRIPTION
 334 .PP
 335 Tcl allows a number of mathematical functions to be used in
 336 expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
 337 These functions are represented by commands in the namespace,
 338 \fBtcl::mathfunc\fR.  The \fBTcl_CreateMathFunc\fR function is
 339 an obsolete way for applications to add additional functions
 340 to those already provided by Tcl or to replace existing functions.
 341 It should not be used by new applications, which should create
 342 math functions using \fBTcl_CreateObjCommand\fR to create a command
 343 in the \fBtcl::mathfunc\fR namespace.
 344 .PP
 345 In the \fBTcl_CreateMathFunc\fR interface,
 346 \fIName\fR is the name of the function as it will appear in expressions.
 347 If \fIname\fR does not already exist in the \fB::tcl::mathfunc\fR
 348 namespace, then a new command is created in that namespace.
 349 If \fIname\fR does exist, then the existing function is replaced.
 350 \fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
 351 Each entry in the \fIargTypes\fR array must be
 352 one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR, \fBTCL_WIDE_INT\fR,
 353 or \fBTCL_EITHER\fR to indicate whether the corresponding argument must be an
 354 integer, a double-precision floating value, a wide (64-bit) integer,
 355 or any, respectively.
 356 .PP
 357 Whenever the function is invoked in an expression Tcl will invoke
 358 \fIproc\fR.  \fIProc\fR should have arguments and result that match
 359 the type \fBTcl_MathProc\fR:
 360 .PP
 361 .CS
 362 typedef int \fBTcl_MathProc\fR(
 363         ClientData \fIclientData\fR,
 364         Tcl_Interp *\fIinterp\fR,
 365         Tcl_Value *\fIargs\fR,
 366         Tcl_Value *\fIresultPtr\fR);
 367 .CE
 368 .PP
 369 When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
 370 arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
 371 \fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
 372 which describe the actual arguments to the function:
 373 .PP
 374 .CS
 375 typedef struct Tcl_Value {
 376     Tcl_ValueType \fItype\fR;
 377     long \fIintValue\fR;
 378     double \fIdoubleValue\fR;
 379     Tcl_WideInt \fIwideValue\fR;
 380 } \fBTcl_Value\fR;
 381 .CE
 382 .PP
 383 The \fItype\fR field indicates the type of the argument and is
 384 one of \fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR.
 385 It will match the \fIargTypes\fR value specified for the function unless
 386 the \fIargTypes\fR value was \fBTCL_EITHER\fR. Tcl converts
 387 the argument supplied in the expression to the type requested in
 388 \fIargTypes\fR, if that is necessary.
 389 Depending on the value of the \fItype\fR field, the \fIintValue\fR,
 390 \fIdoubleValue\fR or \fIwideValue\fR
 391 field will contain the actual value of the argument.
 392 .PP
 393 \fIProc\fR should compute its result and store it either as an integer
 394 in \fIresultPtr->intValue\fR or as a floating value in
 395 \fIresultPtr->doubleValue\fR.
 396 It should set also \fIresultPtr->type\fR to one of
 397 \fBTCL_INT\fR, \fBTCL_DOUBLE\fR or \fBTCL_WIDE_INT\fR
 398 to indicate which value was set.
 399 Under normal circumstances \fIproc\fR should return \fBTCL_OK\fR.
 400 If an error occurs while executing the function, \fIproc\fR should
 401 return \fBTCL_ERROR\fR and leave an error message in the interpreter's result.
 402 .PP
 403 \fBTcl_GetMathFuncInfo\fR retrieves the values associated with
 404 function \fIname\fR that were passed to a preceding
 405 \fBTcl_CreateMathFunc\fR call.  Normally, the return code is
 406 \fBTCL_OK\fR but if the named function does not exist, \fBTCL_ERROR\fR
 407 is returned and an error message is placed in the interpreter's
 408 result.
 409 .PP
 410 If an error did not occur, the array reference placed in the variable
 411 pointed to by \fIargTypesPtr\fR is newly allocated, and should be
 412 released by passing it to \fBTcl_Free\fR.  Some functions (the
 413 standard set implemented in the core, and those defined by placing
 414 commands in the \fBtcl::mathfunc\fR namespace) do not have
 415 argument type information; attempting to retrieve values for
 416 them causes a NULL to be stored in the variable pointed to by
 417 \fIprocPtr\fR and the variable pointed to by \fIclientDataPtr\fR
 418 will not be modified.  The variable pointed to by \fInumArgsPointer\fR
 419 will contain -1, and no argument types will be stored in the variable
 420 pointed to by \fIargTypesPointer\fR.
 421 .PP
 422 \fBTcl_ListMathFuncs\fR returns a Tcl value containing a list of all
 423 the math functions defined in the interpreter whose name matches
 424 \fIpattern\fR.  The returned value has a reference count of zero.
 425 .SH "SEE ALSO"
 426 expr(n), info(n), Tcl_CreateObjCommand(3), Tcl_Free(3), Tcl_NewListObj(3)
 427 .SH KEYWORDS
 428 expression, mathematical function