]> Shamusworld >> Repos - architektonas/blob - fparser/docs/fparser.html
Bugfixes related to removing Snapper class.
[architektonas] / fparser / docs / fparser.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html>
3 <head>
4  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5  <link href="style.css" rel="stylesheet" type="text/css" title="normal" media=screen>
6  <title>Function Parser for C++ v4.3    : Documentation</title>
7 </head>
8
9 <body>
10 <h1>Function Parser for C++ v4.3    </h1>
11
12 <p>Authors: Juha Nieminen
13 (<a href="http://iki.fi/warp/">http://iki.fi/warp/</a>),
14 Joel Yliluoma
15 (<a href="http://iki.fi/bisqwit/">http://iki.fi/bisqwit/</a>).
16
17 <p>The usage license of this library is located at the end of this file.
18
19 <h2>Table of contents:</h2>
20
21 <ul>
22  <li><a href="#whatsnew">What's new</a>
23  <li><a href="#preface">Preface</a>
24  <li><a href="#usage">Usage</a>
25      <ul>
26       <li><a href="#parsertypes">Parser types</a>
27       <li><a href="#configuring">Configuring the compilation</a>
28       <li><a href="#copyassignment">Copying and assignment</a>
29       <li><a href="#shortdesc">Short descriptions of FunctionParser methods</a>
30       <li><a href="#longdesc">Long descriptions of FunctionParser methods</a>
31         <ul>
32           <li><a href="#longdesc_Parse"><code>Parse()</code></a>
33           <li><a href="#longdesc_setDelimiterChar"><code>setDelimiterChar()</code></a>
34           <li><a href="#longdesc_ErrorMsg"><code>ErrorMsg()</code></a>
35           <li><a href="#longdesc_GetParseErrorType"><code>GetParseErrorType()</code></a>
36           <li><a href="#longdesc_Eval"><code>Eval()</code></a>
37           <li><a href="#longdesc_EvalError"><code>EvalError()</code></a>
38           <li><a href="#longdesc_Optimize"><code>Optimize()</code></a>
39           <li><a href="#longdesc_AddConstant"><code>AddConstant()</code></a>
40           <li><a href="#longdesc_AddUnit"><code>AddUnit()</code></a>
41           <li><a href="#longdesc_AddFunction1"><code>AddFunction()</code></a> (C++ function)
42           <li><a href="#longdesc_AddFunction2"><code>AddFunction()</code></a> (FunctionParser)
43           <li><a href="#longdesc_RemoveIdentifier"><code>RemoveIdentifier()</code></a>
44           <li><a href="#longdesc_ParseAndDeduceVariables"><code>ParseAndDeduceVariables()</code></a>
45         </ul>
46      </ul>
47  <li>Syntax
48    <ul>
49      <li><a href="#literals">Numeric literals</a>
50      <li><a href="#identifiers">Identifier names</a>
51      <li><a href="#functionsyntax">The function string syntax</a>
52      <li><a href="#inlinevars">Inline variables</a>
53      <li><a href="#whitespace">Whitespace</a>
54    </ul>
55  <li>Miscellaneous
56    <ul>
57      <li><a href="#evaluationchecks">About evaluation-time checks</a>
58      <li><a href="#threadsafety">About thread safety</a>
59      <li><a href="#tipsandtricks">Tips and tricks</a>
60      <li><a href="#contact">Contacting the author</a>
61    </ul>
62 <!-- <li><a href="#algorithm">The algorithm used in the library</a> -->
63  <li><a href="#license">Usage license</a>
64 </ul>
65
66 <a name="whatsnew"></a>
67 <h2>What's new</h2>
68
69 <p>What's new in v4.3
70   <ul>
71     <li>Function syntax enhancement: Added possibility of defining new
72       variables in the function string itself. (See documentation for details.)
73     <li>Fixed some bugs in the optimizer (among others,
74       <code>"atan2(-x,-y)"</code> was being wrongly optimized into
75       <code>"atan2(x,y)"</code>
76   </ul>
77
78 <p>What's new in v4.2
79   <ul>
80     <li>The <code>Optimize()</code> method now works also with the
81       <code>float</code> and <code>long double</code> versions of the library.
82     </li>
83     <li>Some new optimizations added.</li>
84     <li>There was a call to the C99/C++0x function <code>isinf()</code> in the
85       optimizer which made it not compile with some compilers. This call has
86       been removed.</li>
87   </ul>
88
89 <p>What's new in v4.1
90   <ul>
91     <li>Official support for hexadecimal literals (for all the parser types).
92       Previously there was support only if the <code>strto...()</code> C
93       library functions happened to support them (which is a non-standard
94       extension of those functions). See documentation for details.</li>
95     <li>Significant amount of new optimizations performed by
96       <code>Parse()</code>.</li>
97     <li>Minor bugfixes.</li>
98   </ul>
99
100
101 <!-- -------------------------------------------------------------------- -->
102 <a name="preface"></a>
103 <h2>Preface</h2>
104
105 <p>This C++ library offers a class which can be used to parse and evaluate a
106 mathematical function from a string (which might be eg. requested from the
107 user). The syntax of the function string is similar to mathematical expressions
108 written in C/C++ (the exact syntax is specified later in this document).
109 The function can then be evaluated with different values of variables.
110
111 <p>For example, a function like "<code>sin(sqrt(x*x+y*y))</code>" can be
112 parsed from a string (either <code>std::string</code> or a C-style string)
113 and then evaluated with different values of <code>x</code> and <code>y</code>.
114 This library can be useful for evaluating user-inputted functions, or in
115 some cases interpreting mathematical expressions in a scripting language.
116
117 <p>This library aims for maximum speed in both parsing and evaluation, while
118 keeping maximum portability. The library should compile and work with any
119 standard-conforming C++ compiler.
120
121 <p>Different numerical types are supported: <code>double</code>,
122   <code>float</code>, <code>long double</code>, <code>long int</code>,
123   multiple-precision floating point numbers using the MPFR library, and
124   arbitrary precision integers using the GMP library. (Note that it's
125   not necessary for these two libraries to exist in the system in order
126   to use the Function Parser library with the other numerical types. Support
127   for these libraries is optionally compiled in using preprocessor settings.)
128
129
130 <!-- -------------------------------------------------------------------- -->
131 <a name="usage"></a>
132 <h2>Usage</h2>
133
134 <p>To use the <code>FunctionParser</code> class, you have to include
135 <code>"fparser.hh"</code> in your source code files which use the
136 <code>FunctionParser</code> class.
137
138 <p>If you are going to use the MPFR version of the library, you need to
139 include <code>"fparser_mpfr.hh"</code>. If you are going to use the GMP
140 version of the library, you need to include <code>"fparser_gmpint.hh"</code>.
141 (Note that support for these special parser versions needs to be specified
142 with preprocessor macros. See the <a href="#parsertypes">documentation
143 below</a> for details.)
144
145 <p>When compiling, you have to compile <code>fparser.cc</code> and
146 <code>fpoptimizer.cc</code> and link them to the main program. In many
147 developement environments it's enough to add those two files to your
148 current project (usually header files don't have to be added to the
149 project for the compilation to work).
150
151 <p>If you are going to use the MPFR or the GMP versions of the library,
152 you also need to add <code>mpfr/MpfrFloat.cc</code> or
153 <code>mpfr/GmpInt.cc</code> files to your project, respectively. Otherwise
154 they should not be added to the project.
155
156 <p>Note that part of the library source code is inside several
157 <code>.inc</code> files (these files contain auto-generated C++ code),
158 provided in the library package. These files are used by
159 <code>fparser.cc</code> and don't need to be added explicitly to the
160 project in most IDEs (such as Visual Studio). Basically, you don't need
161 to do anything with these files, other than keep them in the same directory
162 as <code>fparser.cc</code>.
163
164 <p>Simple usage example of the library:
165
166 <pre>
167     FunctionParser fp;
168     fp.Parse("sqrt(x*x + y*y)", "x,y");
169     double variables[2] = { 1.5, 2.9 };
170     double result = fp.Eval(variables);
171 </pre>
172
173 <!-- -------------------------------------------------------------------- -->
174 <a name="parsertypes"></a>
175 <h3>Parser types</h3>
176
177 <p>Different versions of the function parser class are supported, using
178   different floating point or integral types for function evaluation.
179
180 <p>All the classes other than the default one, <code>FunctionParser</code>,
181   need to be enabled at compile time by defining a preprocessor macro
182   (specified below) either in the <code>fpconfig.hh</code> file or your
183   compiler settings. (The reason for this is that all the other parser types
184   use either C99 standard libraries not yet available in the official C++
185   standard or the third-party libraries GMP and MPFR. It also makes
186   compilation faster and the resulting binary smaller when unused classes
187   are not compiled in.).
188
189 <p>Note that if you try to use the other class types without enabling them
190   with the correspondent preprocessor macro, you will get a linker error
191   (rather than a compiler error) because those classes will not have been
192   instantiated when the library was compiled.
193
194 <p>Currently the <code>Optimize()</code> method works only for the
195   <code>FunctionParser</code>, <code>FunctionParser_f</code> and
196   <code>FunctionParser_ld</code> classes. For the other types it can be
197   called but it does nothing.
198
199 <p>
200 <dl>
201   <dt><p><code>FunctionParser</code></dt>
202   <dd>
203     <p>This is the default class, which uses <code>double</code> as its
204       numerical type. This is the only class enabled by default.
205     <p>If you use some other type than this one, and you don't want this
206       version of the class compiled into the library, you can define the
207       preprocessor macro <code>FP_DISABLE_DOUBLE_TYPE</code>.
208   </dd>
209
210   <dt><p><code>FunctionParser_f</code></dt>
211   <dd>
212     <p>This parser uses <code>float</code> as its numerical type.
213     <p>The <code>FP_SUPPORT_FLOAT_TYPE</code> preprocessor macro needs to be
214       defined for this class to be enabled.
215     <p>Note that this version of the class uses C99 standard math functions
216       not yet available in all C++ compilers. Also the <code>ld</code> version
217       of the class described below use such functions.
218   </dd>
219
220   <dt><p><code>FunctionParser_ld</code></dt>
221   <dd>
222     <p>This parser uses <code>long&nbsp;double</code> as its numerical type.
223     <p>The <code>FP_SUPPORT_LONG_DOUBLE_TYPE</code> preprocessor macro needs
224       to be defined for this class to be enabled.
225   </dd>
226
227   <dt><p><code>FunctionParser_li</code></dt>
228   <dd>
229     <p>This parser uses <code>long&nbsp;int</code> as its numerical type.
230     <p>The <code>FP_SUPPORT_LONG_INT_TYPE</code> preprocessor macro needs
231       to be defined for this class to be enabled.
232     <p>Note that this version of the class uses a reduced function syntax
233       with support only for functions which are feasible to be used with
234       integral types (namely <code>abs()</code>, <code>eval()</code>,
235       <code>if()</code>, <code>min()</code> and <code>max()</code>, besides
236       basic arithmetic operators, except for the power operator).
237   </dd>
238
239   <dt><p><code>FunctionParser_mpfr</code></dt>
240   <dd>
241     <p>This parser uses <code>MpfrFloat</code> as its numerical type.
242     <p>The <code>FP_SUPPORT_MPFR_FLOAT_TYPE</code> preprocessor macro needs
243       to be defined for this class to be enabled.
244     <p>Note that to use this version of the parser,
245       <code>"fparser_mpfr.hh"</code> needs to be included.
246     <p><code>MpfrFloat</code> is an auxiliary class which uses the MPFR
247       library for multiple-precision floating point numbers. The class
248       behaves largely like a floating point type, and is declared in the
249       <code>mpfr/MpfrFloat.hh</code> file (see that file for info about
250       the public interface of the class).
251     <p>If this class is enabled, <code>mpfr/MpfrFloat.cc</code>
252       needs to be compiled into the project, as well as the GMP and MPFR
253       libraries. (With the gcc compiler this means using the linker options
254       "<code>-lgmp -lmpfr</code>".)
255   </dd>
256
257   <dt><p><code>FunctionParser_gmpint</code></dt>
258   <dd>
259     <p>This parser uses <code>GmpInt</code> as its numerical type.
260     <p>The <code>FP_SUPPORT_GMP_INT_TYPE</code> preprocessor macro needs
261       to be defined for this class to be enabled.
262     <p>Note that to use this version of the parser,
263       <code>"fparser_gmpint.hh"</code> needs to be included.
264     <p><code>GmpInt</code> is an auxiliary class which uses the GMP
265       library for arbitrary-precision integer numbers. The class
266       behaves largely like an integer type, and is declared in the
267       <code>mpfr/GmpInt.hh</code> file (see that file for info about
268       the public interface of the class).
269     <p>If this class is enabled, <code>mpfr/GmpInt.cc</code>
270       needs to be compiled into the project, as well as the GMP library.
271     <p>This version of the class also uses a reduced version of the syntax,
272       like the <code>long int</code> version.
273     <p><b>Note:</b> Since there's no upper limit to the size of GMP
274       integers, this version of the class should be used with care in
275       situations where malicious users might be able to exploit it to
276       make the program run out of memory. An example of this would be
277       a server-side application usable through the WWW.
278   </dd>
279 </dl>
280
281 <p>Note that these different classes are completely independent and
282   instances of different classes cannot be given to each other using the
283   <code>AddFunction()</code> method. Only objects of the same type can
284   be given to that method.
285
286 <p>The rest of the documentation assumes that <code>FunctionParser</code>
287   (which uses the <code>double</code> type) is used. The usage of the other
288   classes is identical except that <code>double</code> is replaced with the
289   correspondent type used by that class. (In other words, whenever the
290   rest of this documentation uses the type keyword '<code>double</code>',
291   the correspondent type should be used instead, when using another version
292   of the class.)
293
294 <!-- -------------------------------------------------------------------- -->
295 <a name="configuring"></a>
296 <h3>Configuring the compilation</h3>
297
298 <p>There is a set of precompiler options in the <code>fpconfig.hh</code> file
299 which can be used for setting certain features on or off. All of these options
300 can also be specified from the outside, using precompiler settings (eg. the
301 <code>-D</code> option in gcc), and thus it's not necessary to modify this
302 file.
303
304 <dl>
305   <dt><p><code>FP_SUPPORT_TR1_MATH_FUNCS</code> : (Default off)</dt>
306   <dd><p>Define this precompiler constant to make the library use additional
307       math functions defined in the C99 standard and the C++ TR1 standard
308       proposal (but not yet in the official C++ standard). This can make
309       evaluation faster when these functions are involved.
310     <p>The C++ TR1 math functions in question are: <code>asinh()</code>,
311       <code>acosh()</code>, <code>atanh()</code>, <code>exp2()</code> and
312       <code>log2()</code>.
313   </dd>
314
315   <dt><p><code>FP_ENABLE_EVAL</code> : (Default off)</dt>
316   <dd><p>Even though the maximum recursion level of the <code>eval()</code>
317       function is limited, it is still possible to write functions which never
318       reach this maximum recursion level but take enormous amounts of
319       time to evaluate (this can be undesirable eg. in web server-side
320       applications). For this reason this function is disabled by default.
321       You can add support for the <code>eval()</code> function by
322       defining this precompiler constant.
323   </dd>
324
325   <dt><p><code>FP_EVAL_MAX_REC_LEVEL</code> : (Default 1000)</dt>
326   <dd><p>Sets the maximum recursion level allowed for <code>eval()</code>.
327   </dd>
328
329   <dt><p><code>FP_SUPPORT_OPTIMIZER</code> : (Default on)</dt>
330   <dd><p>If you are not going to use the <code>Optimize()</code> method, you
331       can comment this line out to speed-up the compilation a bit, as
332       well as making the binary a bit smaller. (<code>Optimize()</code> can
333       still be called, but it will not do anything.)
334
335     <p>You can also disable the optimizer by specifying the
336       <code>FP_NO_SUPPORT_OPTIMIZER</code> precompiler constant in your
337       compiler settings.
338   </dd>
339
340   <dt><p><code>FP_EPSILON</code> : (Default <code>1e-14</code>)</dt>
341   <dd><p>Epsilon value used in comparison operators.
342       If this line is commented out, then no epsilon will be used.
343   </dd>
344
345   <dt><p><code>FP_USE_THREAD_SAFE_EVAL</code> : (Default off)</dt>
346   <dd><p>Define this precompiler constant to make <code>Eval()</code>
347       thread-safe. Refer to the <a href="#threadsafety">thread safety
348         section</a> later in this document for more information.
349       Note that defining this may make <code>Eval()</code> slightly slower.
350     <p>Also note that the MPFR and GMP versions of the library cannot be
351       made thread-safe, and thus this setting has no effect on them.
352   </dd>
353
354   <dt><p><code>FP_USE_THREAD_SAFE_EVAL_WITH_ALLOCA</code> : (Default off)</dt>
355   <dd><p>This is like the previous, but makes <code>Eval()</code> use the
356       <code>alloca()</code> function (instead of <code>std::vector</code>).
357       This will make it faster, but the <code>alloca()</code>
358       function is not standard and thus not supported by all compilers.
359   </dd>
360
361   <dt><p><code>FP_NO_EVALUATION_CHECKS</code> : (Default off)</dt>
362   <dd><p>If this precompiler constant is defined, no evaluation-time checks
363       will be performed. This may give a slight boost in speed in certain
364       situations. Consult the <a href="#evaluationchecks">evaluation
365         checks section</a> below for more information on this subject.
366   </dd>
367 </dl>
368
369
370 <!-- -------------------------------------------------------------------- -->
371 <a name="copyassignment"></a>
372 <h3>Copying and assignment</h3>
373
374 <p>The class implements a safe copy constructor and assignment operator.
375
376 <p>It uses the copy-on-write technique for efficiency. This means that
377   when copying or assigning a FunctionParser instance, the internal data
378   (which in some cases can be quite lengthy) is not immediately copied
379   but only when the contents of the copy (or the original) are changed.
380
381 <p>This means that copying/assigning is a very fast operation, and if
382   the copies are never modified then actual data copying never happens
383   either.
384
385 <p>The <code>Eval()</code> and <code>EvalError()</code> methods of the
386 copy can be called without the internal data being copied.
387
388 <p>Calling <code>Parse()</code>, <code>Optimize()</code> or the user-defined
389 constant/function adding methods will cause a deep-copy.
390
391
392 <!-- -------------------------------------------------------------------- -->
393 <a name="shortdesc"></a>
394 <h3>Short descriptions of FunctionParser methods</h3>
395
396 <pre>
397 int Parse(const std::string&amp; Function, const std::string&amp; Vars,
398           bool useDegrees = false);
399
400 int Parse(const char* Function, const std::string&amp; Vars,
401           bool useDegrees = false);
402 </pre>
403
404 <p>Parses the given function and compiles it to internal format.
405     Return value is -1 if successful, else the index value to the location
406     of the error.
407
408 <hr>
409 <pre>
410 void setDelimiterChar(char);
411 </pre>
412
413 <p>Sets an ending delimiter character for the function string. (See the
414     long description for more details.)
415
416 <hr>
417 <pre>
418 const char* ErrorMsg(void) const;
419 </pre>
420
421 <p>Returns an error message corresponding to the error in
422 <code>Parse()</code>, or an empty string if no such error occurred.
423
424 <hr>
425 <pre>
426 ParseErrorType GetParseErrorType() const;
427 </pre>
428
429 <p>Returns the type of parsing error which occurred. Possible return types
430     are described in the long description.
431
432 <hr>
433 <pre>
434 double Eval(const double* Vars);
435 </pre>
436
437 <p>Evaluates the function given to <code>Parse()</code>.
438
439 <hr>
440 <pre>
441 int EvalError(void) const;
442 </pre>
443
444 <p>Returns <code>0</code> if no error happened in the previous call to
445 <code>Eval()</code>, else an error code <code>&gt;0</code>.
446
447 <hr>
448 <pre>
449 void Optimize();
450 </pre>
451
452 <p>Tries to optimize the bytecode for faster evaluation.
453
454 <hr>
455 <pre>
456 bool AddConstant(const std::string&amp; name, double value);
457 </pre>
458
459 <p>Add a constant to the parser. Returns <code>false</code> if the name of
460 the constant is invalid, else <code>true</code>.
461
462 <hr>
463 <pre>
464 bool AddUnit(const std::string&amp; name, double value);
465 </pre>
466
467 <p>Add a new unit to the parser. Returns <code>false</code> if the name of
468 the unit is invalid, else <code>true</code>.
469
470 <hr>
471 <pre>
472 bool AddFunction(const std::string&amp; name,
473                  double (*functionPtr)(const double*),
474                  unsigned paramsAmount);
475 </pre>
476
477 <p>Add a user-defined function to the parser (as a function pointer).
478 Returns <code>false</code> if the name of the function is invalid, else
479 <code>true</code>.
480
481 <hr>
482 <pre>
483 bool AddFunction(const std::string&amp; name, FunctionParser&amp;);
484 </pre>
485
486 <p>Add a user-defined function to the parser (as a <code>FunctionParser</code>
487 instance). Returns <code>false</code> if the name of the function is invalid,
488 else <code>true</code>.
489
490 <hr>
491 <pre>
492 bool RemoveIdentifier(const std::string&amp; name);
493 </pre>
494
495 <p>Removes the constant, unit or user-defined function with the specified
496 name from the parser.
497
498 <hr>
499 <pre>
500 int ParseAndDeduceVariables(const std::string&amp; function,
501                             int* amountOfVariablesFound = 0,
502                             bool useDegrees = false);
503 int ParseAndDeduceVariables(const std::string&amp; function,
504                             std::string&amp; resultVarString,
505                             int* amountOfVariablesFound = 0,
506                             bool useDegrees = false);
507 int ParseAndDeduceVariables(const std::string&amp; function,
508                             std::vector&lt;std::string&gt;&amp; resultVars,
509                             bool useDegrees = false);
510 </pre>
511
512 <p>Like <code>Parse()</code>, but the variables in the function are deduced
513 automatically. The amount of found variables and the variable names themselves
514 are returned by the different versions of the function.
515
516 <!-- -------------------------------------------------------------------- -->
517 <a name="longdesc"></a>
518 <h3>Long descriptions of FunctionParser methods</h3>
519
520 <hr>
521 <a name="longdesc_Parse"></a>
522 <pre>
523 int Parse(const std::string&amp; Function, const std::string&amp; Vars,
524           bool useDegrees = false);
525
526 int Parse(const char* Function, const std::string&amp; Vars,
527           bool useDegrees = false);
528 </pre>
529
530 <p>Parses the given function (and compiles it to internal format).
531 Destroys previous function. Following calls to <code>Eval()</code> will evaluate
532 the given function.
533
534 <p>The strings given as parameters are not needed anymore after parsing.
535
536 <p>Parameters:
537
538 <table border=2>
539  <tr>
540   <td><code>Function</code></td>
541   <td>String containing the function to parse.</td>
542  </tr><tr>
543   <td><code>Vars</code></td>
544   <td>String containing the variable names, separated by commas.<br>
545       Eg. <code>"x,y"</code>, <code>"VarX,VarY,VarZ,n"</code> or
546       <code>"x1,x2,x3,x4,__VAR__"</code>.
547  </tr><tr>
548   <td><code>useDegrees</code></td>
549   <td>(Optional.) Whether to use degrees or radians in
550         trigonometric functions. (Default: radians)</td>
551  </tr>
552 </table>
553
554 <p>If a <code>char*</code> is given as the <code>Function</code> parameter,
555 it must be a null-terminated string.
556
557 <p>Variables can have any size and they are case sensitive (ie.
558 <code>"var"</code>, <code>"VAR"</code> and <code>"Var"</code> are
559 <em>different</em> variable names). Letters, digits, underscores and
560 UTF8-encoded characters can be used in variable names, but the name of
561 a variable can't begin with a digit. Each variable name can appear only
562 once in the '<code>Vars</code>' string. Function names are not legal
563 variable names.
564
565 <p>Using longer variable names causes no overhead whatsoever to the
566 <code>Eval()</code> method, so it's completely safe to use variable names
567 of any size.
568
569 <p>The third, optional parameter specifies whether angles should be
570     interpreted as radians or degrees in trigonometrical functions.
571     If not specified, the default value is radians.
572
573 <p>Return values:
574
575 <ul>
576  <li>On success the function returns <code>-1</code>.
577  <li>On error the function returns an index to where the error was found
578      (<code>0</code> is the first character, <code>1</code> the second, etc).
579      If the error was not a parsing error returns an index to the end of the
580      string.
581 </ul>
582
583 <p>Example: <code>parser.Parse("3*x+y", "x,y");</code>
584
585
586 <hr>
587 <a name="longdesc_setDelimiterChar"></a>
588 <pre>
589 void setDelimiterChar(char);
590 </pre>
591
592 <p>By default the parser expects the entire function string to be valid
593 (ie. the entire contents of the given <code>std::string</code>, or a C string
594 ending in the null character <code>'\0'</code>).
595
596 <p>If a delimiter character is specified with this function, then if it's
597 encountered at the outermost parsing level by the <code>Parse()</code>
598 function, and the input function has been valid so far, <code>Parse()</code>
599 will return an index to this character inside the input string, but rather
600 than set an error code, <code>FP_NO_ERROR</code> will be set.
601
602 <p>The idea is that this can be used to more easily parse functions which
603 are embedded inside larger strings, containing surrounding data, without
604 having to explicitly extract the function to a separate string.
605
606 <p>For example, suppose you are writing an interpreter for a scripting
607     language, which can have commands like this:
608
609 <p><code>let MyFunction(x,y) = { sin(x*x+y*y) } // A 2-dimensional function</code>
610
611 <p>Normally when parsing such a line you would have to extract the part
612 inside the curly brackets into a separate string and parse it that way.
613 With this feature what you can do instead is to set <code>'}'</code> as
614 the delimiter character and then simply give a pointer to the character
615 which comes after the <code>'{'</code>. If all goes well, the
616 <code>Parse()</code> function will return an index to the <code>'}'</code>
617 character (from the given starting point) and <code>GetParseErrorType()</code>
618 will return <code>FP_NO_ERROR</code>. You can use the return
619 value (if it's not <code>-1</code>) to jump forward in the string to the
620 delimiter character.
621
622 <p>Note that a null character (<code>'\0'</code>) or the end of the
623 <code>std::string</code> (if one was given) will still be a valid end of
624 the function string even if a delimiter character was specified. (In this
625 case <code>Parse()</code> will return <code>-1</code> if there was no error,
626 as usual.)
627
628 <p>Also note that the delimiter character cannot be any valid operator
629 or alphanumeric (including the underscore) character, nor the other
630 characters defined in the function syntax. It must be a character not
631 supported by the function parser (such as <code>'}'</code>,
632 <code>'&quot;'</code>, <code>']'</code>, etc).
633
634
635 <hr>
636 <a name="longdesc_ErrorMsg"></a>
637 <pre>
638 const char* ErrorMsg(void) const;
639 </pre>
640
641 <p>Returns a pointer to an error message string corresponding to the error
642 caused by <code>Parse()</code> (you can use this to print the proper error
643 message to the user). If no such error has occurred, returns an empty string.
644
645
646 <hr>
647 <a name="longdesc_GetParseErrorType"></a>
648 <pre>
649 ParseErrorType GetParseErrorType() const;
650 </pre>
651
652 <p>Returns the type of parse error which occurred.
653
654 <p>This method can be used to get the error type if <code>ErrorMsg()</code>
655 is not enough for printing the error message. In other words, this can be
656 used for printing customized error messages (eg. in another language).
657 If the default error messages suffice, then this method doesn't need
658 to be called.
659
660 <code>FunctionParser::ParseErrorType</code> is an enumerated type inside
661 the class (ie. its values are accessed like
662 "<code>FunctionParser::SYNTAX_ERROR</code>").
663
664 <p>The possible values for FunctionParser::ParseErrorType are listed below,
665 along with their equivalent error message returned by the
666 <code>ErrorMsg()</code> method:
667
668 <p><table border=2>
669 <tr>
670  <td><code>FP_NO_ERROR</code></td>
671  <td>If no error occurred in the previous call to <code>Parse()</code>.</td>
672 </tr><tr>
673  <td><code>SYNTAX_ERROR</code></td>
674  <td>"Syntax error"</td>
675 </tr><tr>
676  <td><code>MISM_PARENTH</code></td>
677  <td>"Mismatched parenthesis"</td>
678 </tr><tr>
679  <td><code>MISSING_PARENTH</code></td>
680  <td>"Missing ')'"</td>
681 </tr><tr>
682  <td><code>EMPTY_PARENTH</code></td>
683  <td>"Empty parentheses"</td>
684 </tr><tr>
685  <td><code>EXPECT_OPERATOR</code></td>
686  <td>"Syntax error: Operator expected"</td>
687 </tr><tr>
688  <td><code>OUT_OF_MEMORY</code></td>
689  <td>"Not enough memory"</td>
690 </tr><tr>
691  <td><code>UNEXPECTED_ERROR</code></td>
692  <td>"An unexpected error occurred. Please make a full bug report to the
693       author"</td>
694 </tr><tr>
695  <td><code>INVALID_VARS</code></td>
696  <td>"Syntax error in parameter 'Vars' given to FunctionParser::Parse()"</td>
697 </tr><tr>
698  <td><code>ILL_PARAMS_AMOUNT</code></td>
699  <td>"Illegal number of parameters to function"</td>
700 </tr><tr>
701  <td><code>PREMATURE_EOS</code></td>
702  <td>"Syntax error: Premature end of string"</td>
703 </tr><tr>
704  <td><code>EXPECT_PARENTH_FUNC</code></td>
705  <td>"Syntax error: Expecting ( after function"</td>
706 </tr><tr>
707  <td><code>UNKNOWN_IDENTIFIER</code></td>
708  <td>"Syntax error: Unknown identifier"</td>
709 </tr><tr>
710  <td><code>NO_FUNCTION_PARSED_YET</code></td>
711  <td>"(No function has been parsed yet)"</td>
712 </tr>
713 </table>
714
715
716 <hr>
717 <a name="longdesc_Eval"></a>
718 <pre>
719 double Eval(const double* Vars);
720 </pre>
721
722 <p>Evaluates the function given to <code>Parse()</code>.
723 The array given as parameter must contain the same amount of values as
724 the amount of variables given to <code>Parse()</code>. Each value corresponds
725 to each variable, in the same order.
726
727 <p>Return values:
728 <ul>
729  <li>On success returns the evaluated value of the function given to
730      <code>Parse()</code>.
731  <li>On error (such as division by 0) the return value is unspecified,
732      probably 0.
733 </ul>
734
735 <p>Example:
736
737 <p><code>double Vars[] = {1, -2.5};</code><br>
738 <code>double result = parser.Eval(Vars);</code>
739
740
741 <hr>
742 <a name="longdesc_EvalError"></a>
743 <pre>
744 int EvalError(void) const;
745 </pre>
746
747 <p>Used to test if the call to <code>Eval()</code> succeeded.
748
749 <p>Return values:
750
751 <p>If there was no error in the previous call to <code>Eval()</code>,
752 returns <code>0</code>, else returns a positive value as follows:
753 <ul>
754  <li>1: division by zero
755  <li>2: sqrt error (sqrt of a negative value)
756  <li>3: log error (logarithm of a negative value)
757  <li>4: trigonometric error (asin or acos of illegal value)
758  <li>5: maximum recursion level in <code>eval()</code> reached
759 </ul>
760
761
762 <hr>
763 <a name="longdesc_Optimize"></a>
764 <pre>
765 void Optimize();
766 </pre>
767
768 <p>This method can be called after calling the <code>Parse()</code> method.
769 It will try to simplify the internal bytecode so that it will evaluate faster
770 (it tries to reduce the amount of opcodes in the bytecode).
771
772 <p>For example, the bytecode for the function <code>"5+x*y-25*4/8"</code> will
773 be reduced to a bytecode equivalent to the function <code>"x*y-7.5"</code> (the
774 original 11 opcodes will be reduced to 5). Besides calculating constant
775 expressions (like in the example), it also performs other types of
776 simplifications with variable and function expressions.
777
778 <p>This method is quite slow and the decision of whether to use it or
779 not should depend on the type of application. If a function is parsed
780 once and evaluated millions of times, then calling <code>Optimize()</code>
781 may speed-up noticeably. However, if there are tons of functions to parse
782 and each one is evaluated once or just a few times, then calling
783 <code>Optimize()</code> will only slow down the program.
784
785 <p>Also, if the original function is expected to be optimal, then calling
786 <code>Optimize()</code> would be useless.
787
788 <p>Note: Currently this method does not make any checks (like
789 <code>Eval()</code> does) and thus things like <code>"1/0"</code> will cause
790 undefined behaviour. (On the other hand, if such expression is given to the
791 parser, <code>Eval()</code> will always give an error code, no matter what
792 the parameters.) If caching this type of errors is important, a work-around
793 is to call <code>Eval()</code> once before calling <code>Optimize()</code>
794 and checking <code>EvalError()</code>.
795
796 <p>If the destination application is not going to use this method,
797 the compiler constant <code>FP_SUPPORT_OPTIMIZER</code> can be undefined in
798 <code>fpconfig.hh</code> to make the library smaller (<code>Optimize()</code>
799 can still be called, but it will not do anything).
800
801 <p>(If you are interested in seeing how this method optimizes the opcode,
802 you can call the <code>PrintByteCode()</code> method before and after the
803 call to <code>Optimize()</code> to see the difference.)
804
805
806 <hr>
807 <a name="longdesc_AddConstant"></a>
808 <pre>
809 bool AddConstant(const std::string&amp; name, double value);
810 </pre>
811
812 <p>This method can be used to add constants to the parser. Syntactically
813     constants are identical to variables (ie. they follow the same naming
814     rules and they can be used in the function string in the same way as
815     variables), but internally constants are directly replaced with their
816     value at parse time.
817
818 <p>Constants used by a function must be added before calling
819 <code>Parse()</code> for that function. Constants are preserved between
820 <code>Parse()</code> calls in the current FunctionParser instance, so
821 they don't need to be added but once. (If you use the same constant in
822 several instances of FunctionParser, you will need to add it to all the
823 instances separately.)
824
825 <p>Constants can be added at any time and the value of old constants can
826 be changed, but new additions and changes will only have effect the next
827 time <code>Parse()</code> is called. (That is, changing the value of a constant
828 after calling <code>Parse()</code> and before calling <code>Eval()</code>
829 will have no effect.)
830
831 <p>The return value will be <code>false</code> if the '<code>name</code>' of
832 the constant was illegal, else <code>true</code>. If the name was illegal,
833 the method does nothing.
834
835 <p>Example: <code>parser.AddConstant("pi", 3.1415926535897932);</code>
836
837 <p>Now for example <code>parser.Parse("x*pi", "x");</code> will be identical
838 to the call <code>parser.Parse("x*3.1415926535897932", "x");</code>
839
840
841 <hr>
842 <a name="longdesc_AddUnit"></a>
843 <pre>
844 bool AddUnit(const std::string&amp; name, double value);
845 </pre>
846
847 <p>In some applications it is desirable to have units of measurement.
848 A typical example is an application which creates a page layout to be
849 printed. When printing, distances are usually measured in points
850 (defined by the resolution of the printer). However, it is often more
851 useful for the user to be able to specify measurements in other units
852 such as centimeters or inches.
853
854 <p>A unit is simply a value by which the preceding element is multiplied.
855 For example, if the printing has been set up to 300 DPI, one inch is
856 then 300 points (dots). Thus saying eg. <code>"5in"</code> is the same as saying
857 <code>"5*300"</code> or <code>"1500"</code> (assuming <code>"in"</code> has
858 been added as a unit with the value 300).
859
860 <p>Note that units are slightly different from a multiplication in
861 that they have a higher precedence than any other operator (except
862 parentheses). Thus for example <code>"5/2in"</code> is parsed as
863 <code>"5/(2*300)"</code>.
864 (If 5/2 inches is what one wants, it has to be written <code>"(5/2)in"</code>.)
865
866 <p>You can use the <code>AddUnit()</code> method to add a new unit. The
867 unit can then be used after any element in the function (and will work as
868 a multiplier for that element). An element is a float literal, a constant,
869 a variable, a function or any expression in parentheses. When the element
870 is not a float literal nor an expression in parentheses, there has to naturally
871 be at least one whitespace between the element and the unit (eg.
872 <code>"x in"</code>). To change the value of a unit, call
873 <code>AddUnit()</code> again with the same unit name and the new value.
874
875 <p>Unit names share the same namespace as constants, functions and
876     variables, and thus should be distinct from those.
877
878 <p>Example: <code>parser.AddUnit("in", 300);</code>
879
880 <p>Now for example the function <code>"5in"</code> will be identical to
881 <code>"(5*300)"</code>. Other usage examples include <code>"x in"</code>,
882 <code>"3in+2"</code>, <code>"pow(x,2)in"</code>, <code>"(x+2)in"</code>.
883
884
885 <hr>
886 <a name="longdesc_AddFunction1"></a>
887 <pre>
888 bool AddFunction(const std::string&amp; name,
889                  double (*functionPtr)(const double*),
890                  unsigned paramsAmount);
891 </pre>
892
893 This method can be used to add new functions to the parser. For example,
894 if you would like to add a function "<code>sqr(A)</code>" which squares the
895 value of <code>A</code>, you can do it with this method (so that you don't
896 need to touch the source code of the parser).
897
898 <p>The method takes three parameters:
899
900 <ul>
901  <li>The name of the function. The name follows the same naming conventions
902       as variable names.
903
904  <li>A C++ function, which will be called when evaluating the function
905       string (if the user-given function is called there). The C++ function
906       must have the form:
907       <p><code>double functionName(const double* params);</code>
908
909  <li>The number of parameters the function takes. 0 is a valid value
910       in which case the function takes no parameters (such function
911       should simply ignore the <code>double*</code> it gets as a parameter).
912 </ul>
913
914 <p>The return value will be <code>false</code> if the given name was invalid
915 (either it did not follow the variable naming conventions, or the name was
916 already reserved), else <code>true</code>. If the return value is
917 <code>false</code>, nothing is added.
918
919 <p>Example: Suppose we have a C++ function like this:
920
921 <p><code>double Square(const double* p)</code><br>
922 <code>{</code><br>
923 <code>&nbsp;&nbsp;&nbsp;&nbsp;return p[0]*p[0];</code><br>
924 <code>}</code>
925
926 <p>Now we can add this function to the parser like this:
927
928 <p><code>parser.AddFunction("sqr", Square, 1);</code><br>
929 <code>parser.Parse("2*sqr(x)", "x");</code>
930
931 <p>An example of a useful function taking no parameters is a function
932     returning a random value. For example:
933
934 <p><code>double Rand(const double*)</code><br>
935 <code>{</code><br>
936 <code>&nbsp;&nbsp;&nbsp;&nbsp;return drand48();</code><br
937 <code>}</code>
938
939 <p><code>parser.AddFunction("rand", Rand, 0);</code>
940
941 <p><em>Important note</em>: If you use the <code>Optimize()</code> method,
942 it will assume that the user-given function has no side-effects, that is,
943 it always returns the same value for the same parameters. The optimizer will
944 optimize the function call away in some cases, making this assumption.
945 (The <code>Rand()</code> function given as example above is one such
946 problematic case.)
947
948
949 <hr>
950 <a name="longdesc_AddFunction2"></a>
951 <pre>
952 bool AddFunction(const std::string&amp; name, FunctionParser&amp;);
953 </pre>
954
955 <p>This method is almost identical to the previous <code>AddFunction()</code>,
956 but instead of taking a C++ function, it takes another FunctionParser
957 instance.
958
959 <p>There are some important restrictions on making a FunctionParser instance
960     call another:
961
962 <ul>
963  <li>The FunctionParser instance given as parameter must be initialized
964       with a <code>Parse()</code> call before giving it as parameter. That
965       is, if you want to use the parser <code>A</code> in the parser
966       <code>B</code>, you must call <code>A.Parse()</code> before you can
967       call <code>B.AddFunction("name", A)</code>.
968
969  <li>The amount of variables in the FunctionParser instance given as
970       parameter must not change after it has been given to the
971       <code>AddFunction()</code>
972       of another instance. Changing the number of variables will result in
973       malfunction.
974
975  <li><code>AddFunction()</code> will fail (ie. return <code>false</code>)
976       if a recursive loop is
977       formed. The method specifically checks that no such loop is built.
978
979  <li>The FunctionParser instance given as parameter will <em>not</em> be
980      copied internally, only referenced. Thus the FunctionParser instance
981      given as parameter must exist for as long as the other FunctionParser
982      instance uses it.
983 </ul>
984
985 <p>Example:
986
987 <p><code>FunctionParser f1, f2;</code><br>
988 <p><code>f1.Parse("x*x", "x");</code><br>
989 <p><code>f2.AddFunction("sqr", f1);</code>
990
991 <p>This version of the <code>AddFunction()</code> method can be useful to
992 eg. chain user-given functions. For example, ask the user for a function F1,
993     and then ask the user another function F2, but now the user can
994     call F1 in this second function if he wants (and so on with a third
995     function F3, where he can call F1 and F2, etc).
996
997 <hr>
998 <a name="longdesc_RemoveIdentifier"></a>
999 <pre>
1000 bool RemoveIdentifier(const std::string&amp; name);
1001 </pre>
1002
1003 <p>If a constant, unit or user-defined function with the specified name
1004 exists in the parser, it will be removed and the return value will be
1005 <code>true</code>, else nothing will be done and the return value will be
1006 <code>false</code>.
1007
1008 <p>(Note: If you want to remove <em>everything</em> from an existing
1009 FunctionParser instance, simply assign a fresh instance to it, ie. like
1010 "<code>parser&nbsp;=&nbsp;FunctionParser();</code>")
1011
1012 <hr>
1013 <a name="longdesc_ParseAndDeduceVariables"></a>
1014 <pre>
1015 int ParseAndDeduceVariables(const std::string&amp; function,
1016                             int* amountOfVariablesFound = 0,
1017                             bool useDegrees = false);
1018 int ParseAndDeduceVariables(const std::string&amp; function,
1019                             std::string&amp; resultVarString,
1020                             int* amountOfVariablesFound = 0,
1021                             bool useDegrees = false);
1022 int ParseAndDeduceVariables(const std::string&amp; function,
1023                             std::vector&lt;std::string&gt;&amp; resultVars,
1024                             bool useDegrees = false);
1025 </pre>
1026
1027 <p>These functions work in the same way as the <code>Parse()</code> function,
1028 but the variables in the input function string are deduced automatically. The
1029 parameters are:
1030
1031 <ul>
1032  <li><code>function</code>: The input function string, as with
1033    <code>Parse()</code>.
1034  <li><code>amountOfVariablesFound</code>: If non-null, the amount of found
1035    variables will be assigned here.
1036  <li><code>resultVarString</code>: The found variables will be written to
1037    this string, in the same format as accepted by the <code>Parse()</code>
1038    function. The variable names will be sorted using the <code>&lt;</code>
1039    operator of <code>std::string</code>.
1040  <li><code>resultVars</code>: The found variables will be written to this
1041    vector, each element being one variable name. They will be sorted using
1042    the <code>&lt;</code> operator of <code>std::string</code>. (The amount
1043    of found variables can be retrieved, rather obviously, with the
1044    <code>size()</code> method of the vector.)
1045  <li><code>useDegrees</code>: As with <code>Parse()</code>.
1046 </ul>
1047
1048 <p>As with <code>Parse()</code>, the return value will be <code>-1</code> if
1049 the parsing succeeded, else an index to the location of the error. None of
1050 the specified return values will be modified in case of error.
1051
1052
1053 <!-- -------------------------------------------------------------------- -->
1054 <h2>Syntax</h2>
1055
1056 <a name="literals"></a>
1057 <h3>Numeric literals</h3>
1058
1059 <p>A numeric literal is a fixed numerical value in the input function string
1060   (either a floating point value or an integer value, depending on the parser
1061   type).
1062
1063 <p>An integer literal can consist solely of numerical digits (possibly with
1064   a preceding unary minus). For example, "<code>12345</code>".
1065
1066 <p>If the literal is preceded by the characters "<code>0x</code>", it
1067   will be interpreted as a hexadecimal literal, where digits can also include
1068   the letters from '<code>A</code>' to '<code>F</code>' (in either uppercase
1069   or lowercase). For example, "<code>0x89ABC</code>" (which corresponds to the
1070   value 563900).
1071
1072 <p>A floating point literal (only supported by the floating point type parsers)
1073   may additionally include a decimal point followed by the decimal part of the
1074   value, such as for example "<code>12.34</code>", optionally followed by a
1075   decimal exponent.
1076
1077 <p>A decimal exponent consists of an '<code>E</code>' or '<code>e</code>',
1078   followed by an optional plus or minus sign, followed by decimal digits, and
1079   indicates multiplication by a power of 10. For example, "<code>1.2e5</code>"
1080   (which is equivalent to the value 120000).
1081
1082 <p>If a floating point literal is preceded by the characters "<code>0x</code>"
1083   it will be interpreted in hexadecimal. A hexadecimal floating point
1084   literal consists of a hexadecimal value, with an optional decimal point,
1085   followed optionally by a binary exponent in base 10 (in other words, the
1086   exponent is not in hexadecimal).
1087
1088 <p>A binary exponent has the same format as a decimal exponent, except that
1089   '<code>P</code>' or '<code>p</code>' is used. A binary exponent indicates
1090   multiplication by a power of 2. For example, "<code>0xA.Bp10</code>"
1091   (which is equivalent to the value 10944).
1092
1093 <a name="identifiers"></a>
1094 <h3>Identifier names</h3>
1095
1096 <p>An identifier is the name of a function (internal or user-defined),
1097   variable, constant or unit. New identifiers can be specified with the
1098   functions described in the earlier subsections in this document.
1099
1100 <p>The name of an identifier can use any alphanumeric characters, the
1101   underscore character and any UTF8-encoded unicode character, excluding
1102   those denoting whitespace.
1103   The first character of the name cannot be a numeric digit, though.
1104
1105 <p>All functions, variables, constants and units must use unique names.
1106   It's not possible to add two different identifiers with the same name.
1107
1108
1109 <!-- -------------------------------------------------------------------- -->
1110 <a name="functionsyntax"></a>
1111 <h3>The function string syntax</h3>
1112
1113 <p>The function string understood by the class is very similar (but not
1114 completely identical in all aspects) to mathematical expressions in the
1115 C/C++ languages.
1116 Arithmetic float expressions can be created from float literals, variables
1117 or functions using the following operators in this order of precedence:
1118
1119 <p><table border=2>
1120  <tr>
1121   <td><code>()</code></td>
1122   <td>expressions in parentheses first</td>
1123  </tr><tr>
1124   <td><code>A unit</code></td>
1125   <td>a unit multiplier (if one has been added)</td>
1126  </tr><tr>
1127   <td><code>A^B</code></td>
1128   <td>exponentiation (A raised to the power B)</td>
1129  </tr><tr>
1130   <td><code>-A</code></td>
1131   <td>unary minus</td>
1132  </tr><tr>
1133   <td><code>!A</code></td>
1134   <td>unary logical not (result is 1 if <code>int(A)</code> is 0, else 0)</td>
1135  </tr><tr>
1136   <td><code>A*B  A/B  A%B</code></td>
1137   <td>multiplication, division and modulo</td>
1138  </tr><tr>
1139   <td><code>A+B  A-B</code></td>
1140   <td>addition and subtraction</td>
1141  </tr><tr>
1142   <td><code>A=B  A&lt;B  A&lt;=B<br>A!=B  A&gt;B  A&gt;=B</code></td>
1143   <td>comparison between A and B (result is either 0 or 1)</td>
1144  </tr><tr>
1145   <td><code>A&amp;B</code></td>
1146   <td>result is 1 if <code>int(A)</code> and <code>int(B)</code> differ from
1147       0, else 0.<br>
1148       Note: Regardless of the values, both operands are always
1149       evaluated. However, if the expression is optimized, it may
1150       be changed such that only one of the operands is evaluated,
1151       according to standard shortcut logical operation semantics.</td>
1152  </tr><tr>
1153   <td><code>A|B</code></td>
1154   <td>result is 1 if <code>int(A)</code> or <code>int(B)</code> differ from 0,
1155       else 0.<br>
1156       Note: Regardless of the values, both operands are always
1157       evaluated. However, if the expression is optimized, it may
1158       be changed such that only one of the operands is evaluated,
1159       according to standard shortcut logical operation semantics.</td>
1160  </tr>
1161 </table>
1162
1163 <p>(Note that currently the exponentiation operator is not supported for
1164   <code>FunctionParser_li</code> nor <code>FunctionParser_gmpint</code>.
1165   With the former the result would very easily overflow, making its
1166   usefulness questionable. With the latter it could be easily abused to
1167   make the program run out of memory; think of a function like
1168   "10^10^10^100000".)
1169
1170 <p>Since the unary minus has higher precedence than any other operator, for
1171   example the following expression is valid: <code>x*-y</code>
1172
1173 <p>The comparison operators use an epsilon value, so expressions which may
1174 differ in very least-significant digits should work correctly. For example,
1175 <code>"0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1 = 1"</code> should always
1176 return 1, and the same comparison done with "<code>&gt;</code>" or
1177 "<code>&lt;</code>" should always return 0. (The epsilon value can be
1178 configured in the <code>fpconfig.hh</code> file.)
1179 Without epsilon this comparison probably returns the wrong value.
1180
1181 <p>The class supports these functions:
1182
1183 <p><table border=2>
1184 <tr>
1185  <td><code>abs(A)</code></td>
1186  <td>Absolute value of A. If A is negative, returns -A otherwise returns A.</td>
1187 </tr><tr>
1188   <td><code>acos(A)</code></td>
1189   <td>Arc-cosine of A. Returns the angle, measured in radians, whose cosine
1190       is A.</td>
1191 </tr><tr>
1192   <td><code>acosh(A)</code></td>
1193   <td>Same as acos() but for hyperbolic cosine.</td>
1194 </tr><tr>
1195   <td><code>asin(A)</code></td>
1196   <td>Arc-sine of A. Returns the angle, measured in radians, whose sine
1197       is A.</td>
1198 </tr><tr>
1199   <td><code>asinh(A)</code></td>
1200   <td>Same as asin() but for hyperbolic sine.</td>
1201 </tr><tr>
1202   <td><code>atan(A)</code></td>
1203   <td>Arc-tangent of (A). Returns the angle, measured in radians,
1204       whose tangent is (A).</td>
1205 </tr><tr>
1206   <td><code>atan2(A,B)</code></td>
1207   <td>Arc-tangent of A/B. The two main differences to atan() is
1208       that it will return the right angle depending on the signs of
1209       A and B (atan() can only return values betwen -pi/2 and pi/2),
1210       and that the return value of pi/2 and -pi/2 are possible.</td>
1211 </tr><tr>
1212   <td><code>atanh(A)</code></td>
1213   <td>Same as atan() but for hyperbolic tangent.</td>
1214 </tr><tr>
1215   <td><code>cbrt(A)</code></td>
1216   <td>Cube root of A. Returns the value whose cube is A.</td>
1217 </tr><tr>
1218   <td><code>ceil(A)</code></td>
1219   <td>Ceiling of A. Returns the smallest integer not smaller than A.
1220       Rounds up to the next higher integer. E.g. -2.9, -2.5 and -2.1 are
1221     rounded to -2.0, and 2.9, 2.5 and 2.1 are rounded to 3.0.</td>
1222 </tr><tr>
1223   <td><code>cos(A)</code></td>
1224   <td>Cosine of A. Returns the cosine of the angle A, where A is
1225       measured in radians.</td>
1226 </tr><tr>
1227   <td><code>cosh(A)</code></td>
1228   <td>Same as cos() but for hyperbolic cosine.</td>
1229 </tr><tr>
1230   <td><code>cot(A)</code></td>
1231   <td>Cotangent of A (equivalent to 1/tan(A)).</td>
1232 </tr><tr>
1233   <td><code>csc(A)</code></td>
1234   <td>Cosecant of A (equivalent to 1/sin(A)).</td>
1235 </tr><tr>
1236   <td><code>eval(...)</code></td>
1237   <td>This a recursive call to the function to be evaluated. The
1238       number of parameters must be the same as the number of parameters
1239       taken by the function. Must be called inside <code>if()</code> to avoid
1240       infinite recursion.</td>
1241 </tr><tr>
1242   <td><code>exp(A)</code></td>
1243   <td>Exponential of A. Returns the value of e raised to the power
1244       A where e is the base of the natural logarithm, i.e. the
1245       non-repeating value approximately equal to 2.71828182846.</td>
1246 </tr><tr>
1247   <td><code>floor(A)</code></td>
1248   <td>Floor of A. Returns the largest integer not greater than A. Rounds
1249       down to the next lower integer.
1250       E.g. -2.9, -2.5 and -2.1 are rounded to -3.0,
1251       and 2.9, 2.5 and 2.1 are rounded to 2.0.</td>
1252 </tr><tr>
1253   <td><code>if(A,B,C)</code></td>
1254   <td>If int(A) differs from 0, the return value of this function is B,
1255       else C. Only the parameter which needs to be evaluated is
1256       evaluated, the other parameter is skipped; this makes it safe to
1257       use <code>eval()</code> in them.</td>
1258 </tr><tr>
1259   <td><code>int(A)</code></td>
1260   <td>Rounds A to the closest integer. Equidistant values are rounded up.
1261     E.g. -2.9 is rounded to -3.0; -2.5 and -2.1 are rounded to -2.0,
1262     and 2.9 and 2.5 are rounded to 3.0; 2.1 is rounded to 2.0.</td>
1263 </tr><tr>
1264   <td><code>log(A)</code></td>
1265   <td>Natural (base e) logarithm of A.</td>
1266 </tr><tr>
1267   <td><code>log10(A)</code></td>
1268   <td>Base 10 logarithm of A.</td>
1269 </tr><tr>
1270   <td><code>max(A,B)</code></td>
1271   <td>If A&gt;B, the result is A, else B.</td>
1272 </tr><tr>
1273   <td><code>min(A,B)</code></td>
1274   <td>If A&lt;B, the result is A, else B.</td>
1275 </tr><tr>
1276   <td><code>pow(A,B)</code></td>
1277   <td>Exponentiation (A raised to the power B).</td>
1278 </tr><tr>
1279   <td><code>sec(A)</code></td>
1280   <td>Secant of A (equivalent to 1/cos(A)).</td>
1281 </tr><tr>
1282   <td><code>sin(A)</code></td>
1283   <td>Sine of A. Returns the sine of the angle A, where A is
1284       measured in radians.</td>
1285 </tr><tr>
1286   <td><code>sinh(A)</code></td>
1287   <td>Same as sin() but for hyperbolic sine.</td>
1288 </tr><tr>
1289   <td><code>sqrt(A)</code></td>
1290   <td>Square root of A. Returns the value whose square is A.</td>
1291 </tr><tr>
1292   <td><code>tan(A)</code></td>
1293   <td>Tangent of A. Returns the tangent of the angle A, where A
1294       is measured in radians.</td>
1295 </tr><tr>
1296   <td><code>tanh(A)</code></td>
1297   <td>Same as tan() but for hyperbolic tangent.</td>
1298 </tr><tr>
1299   <td><code>trunc(A)</code></td>
1300   <td>Truncated value of A. Returns an integer corresponding to the value
1301     of A without its fractional part.
1302     E.g. -2.9, -2.5 and -2.1 are rounded to -2.0,
1303     and 2.9, 2.5 and 2.1 are rounded to 2.0.</td>
1304 </tr>
1305 </table>
1306
1307 <p>(Note that for <code>FunctionParser_li</code> and
1308   <code>FunctionParser_gmpint</code> only the functions
1309   <code>abs()</code>, <code>eval()</code>, <code>if()</code>,
1310   <code>min()</code> and <code>max()</code> are supported.)
1311
1312 <p>Examples of function string understood by the class:
1313
1314 <p><code>"1+2"</code><br>
1315 <code>"x-1"</code><br>
1316 <code>"-sin(sqrt(x^2+y^2))"</code><br>
1317 <code>"sqrt(XCoord*XCoord + YCoord*YCoord)"</code><br>
1318
1319 <p>An example of a recursive function is the factorial function:
1320
1321 <code>"if(n>1, n*eval(n-1), 1)"</code>
1322
1323 <p>Note that a recursive call has some overhead, which makes it a bit slower
1324   than any other operation. It may be a good idea to avoid recursive functions
1325   in very time-critical applications. Recursion also takes some memory, so
1326   extremely deep recursions should be avoided (eg. millions of nested recursive
1327   calls).
1328
1329 <p>Also note that even though the maximum recursion level of
1330 <code>eval()</code> is limited, it is possible to write functions which
1331 never reach that level but still take enormous amounts of time to evaluate.
1332 This can sometimes be undesirable because it is prone to exploitation,
1333 which is why <code>eval()</code> is disabled by default. It can be enabled
1334 in the <code>fpconfig.hh</code> file.
1335
1336
1337 <!-- -------------------------------------------------------------------- -->
1338 <a name="inlinevars"></a>
1339 <h3>Inline variables</h3>
1340
1341 <p>The function syntax supports defining new variables inside the function
1342 string itself. This can be done with the following syntax:
1343
1344 <p><code>"&lt;variable name&gt; := &lt;expression&gt;; &lt;function&gt;"</code>
1345
1346 <p>For example:
1347
1348 <p><code>"length := sqrt(x*x+y*y); 2*length*sin(length)"</code>
1349
1350 <p>(Spaces around the '<code>:=</code>' operator are optional.)
1351
1352 <p>The obvious benefit of this is that if a long expression needs to be
1353 used in the function several times, this allows writing it only once and
1354 using a named variable from that point forward.
1355
1356 <p>The variable name must be an unused identifier (in other words, not an
1357 existing function, variable or unit name).
1358
1359 <p>The <code>&lt;function&gt;</code> part can have further inline variable
1360 definitions, and thus it's possible to have any amount of them, for example:
1361
1362 <p><code>"A := x^2; B := y^2; C := z^2; sqrt(A+B+C)"</code>
1363
1364 <p>The expressions in subsequent inline variable definitions can use any
1365 of the previous inline variables. It is also possible to redefine an inline
1366 variable. For example:
1367
1368 <p><code>"A := x^2; A := 2*A; sqrt(A)"</code>
1369
1370
1371 <!-- -------------------------------------------------------------------- -->
1372 <a name="whitespace"></a>
1373 <h3>Whitespace</h3>
1374
1375 <p>Arbitrary amounts of whitespace can optionally be included between
1376   elements in the function string.
1377   The following unicode characters are interpreted as whitespace:
1378 <table>
1379  <tr>
1380   <th>Character number</th>
1381   <th>Character name</th>
1382   <th>UTF-8 byte sequence</th>
1383  </tr>
1384  <tr><td>U+0009</td><td>HORIZONTAL TABULATION    </td><td>09</td></tr>
1385  <tr><td>U+000A</td><td>LINE FEED                </td><td>0A</td></tr>
1386  <tr><td>U+000B</td><td>VERTICAL TABULATION      </td><td>0B</td></tr>
1387  <tr><td>U+000D</td><td>CARRIAGE RETURN          </td><td>0D</td></tr>
1388  <tr><td>U+0020</td><td>SPACE                    </td><td>20</td></tr>
1389  <tr><td>U+00A0</td><td>NO-BREAK SPACE           </td><td>C2 A0</td></tr>
1390  <tr><td>U+2000</td><td>EN QUAD                  </td><td>E2 80 80</td></tr>
1391  <tr><td>U+2001</td><td>EM QUAD                  </td><td>E2 80 81</td></tr>
1392  <tr><td>U+2002</td><td>EN SPACE                 </td><td>E2 80 82</td></tr>
1393  <tr><td>U+2003</td><td>EM SPACE                 </td><td>E2 80 83</td></tr>
1394  <tr><td>U+2004</td><td>THREE-PER-EM SPACE       </td><td>E2 80 84</td></tr>
1395  <tr><td>U+2005</td><td>FOUR-PER-EM SPACE        </td><td>E2 80 85</td></tr>
1396  <tr><td>U+2006</td><td>SIX-PER-EM SPACE         </td><td>E2 80 86</td></tr>
1397  <tr><td>U+2007</td><td>FIGURE SPACE             </td><td>E2 80 87</td></tr>
1398  <tr><td>U+2008</td><td>PUNCTUATION SPACE        </td><td>E2 80 88</td></tr>
1399  <tr><td>U+2009</td><td>THIN SPACE               </td><td>E2 80 89</td></tr>
1400  <tr><td>U+200A</td><td>HAIR SPACE               </td><td>E2 80 8A</td></tr>
1401  <tr><td>U+200B</td><td>ZERO WIDTH SPACE         </td><td>E2 80 8B</td></tr>
1402  <tr><td>U+202F</td><td>NARROW NO-BREAK SPACE    </td><td>E2 80 AF</td></tr>
1403  <tr><td>U+205F</td><td>MEDIUM MATHEMATICAL SPACE</td><td>E2 81 9F</td></tr>
1404  <tr><td>U+3000</td><td>IDEOGRAPHIC SPACE        </td><td>E3 80 80</td></tr>
1405 </table>
1406
1407
1408 <!-- -------------------------------------------------------------------- -->
1409 <h2>Miscellaneous</h2>
1410
1411 <a name="evaluationchecks"></a>
1412 <h3>About evaluation-time checks</h3>
1413
1414 <p>By default <code>FunctionParser::Eval()</code> will perform certain sanity
1415 checks before performing certain operations. For example, before calling the
1416 <code>sqrt</code> function, it will check if the parameter is negative, and
1417 if so, it will set the proper error code instead of calling the function.
1418 These checks include:
1419
1420 <ul>
1421  <li>Division by (the exact value of) zero.
1422  <li>Square root of a negative value.
1423  <li>Logarithm of a non-positive value.
1424  <li>Arcsine or arccosine of a value not in the range [-1, 1]. (This includes
1425    hyperbolic versions of the functions.)
1426 </ul>
1427
1428 <p>However, the library <em>can not</em> guarantee that it will catch all
1429 possible floating point errors before performing them, because this is
1430 impossible to do with standard C++. For example, dividing a very large
1431 value by a value which is very close to zero, or calculating the logarithm
1432 of a very small value may overflow the result, as well as multiplying two
1433 very large values. Raising a negative number to a non-integral power may
1434 cause a <em>NaN</em> result, etc.
1435
1436 <p>As a rule of thumb, the library will (by default) detect invalid operations
1437 if they are invalid for a range of values. For example, square root is undefined
1438 for all negative values, and arc sine is undefined only values outside the range
1439 [-1, 1]. In general, operations which are invalid for only one single value
1440 (rather than a contiguous range of values) will not be detected (division by
1441 the exact value of zero is an exception to this rule) nor will
1442 overflow/underflow situations.
1443
1444 <p>The library cannot guarantee that floating point
1445 errors will never happen during evaluation. This can make the library to
1446 return the floating point values <em>inf</em> and <em>NaN</em>. Moreover,
1447 if floating point errors cause an interrupt in the target computer
1448 architecture and/or when using certain compiler settings, this library
1449 cannot guarantee that it will never happen.
1450
1451 <p>Since not all error situations can be caught, and since the sanity checks
1452 only slow down the evaluation (although only very slightly), the precompiler
1453 constant <code>FP_NO_EVALUATION_CHECKS</code> can be used to turn all the
1454 checks off. This might make the evaluation slightly faster in certain
1455 situations.
1456
1457 <p>Note that the optimizer never performs any sanity checks.
1458
1459
1460 <!-- -------------------------------------------------------------------- -->
1461 <a name="threadsafety"></a>
1462 <h3>About thread safety</h3>
1463
1464 <p>None of the member functions of the FunctionParser class are thread-safe.
1465 Most prominently, the <code>Eval()</code> function is not thread-safe.
1466 (In other words, the <code>Eval()</code> function of a single FunctionParser
1467 instance cannot be safely called simultaneously by two threads.)
1468
1469 <p>There are ways to use this library in a thread-safe way, though. If each
1470 thread uses its own FunctionParser instance, no problems will obviously
1471 happen. Note, however, that if these instances need to be a copy of a given
1472 FunctionParser instance (eg. one where the user has entered a function),
1473 a deep copy of this instance has to be performed for each thread. By
1474 default FunctionParser uses shallow-copying (copy-on-write), which means
1475 that a simple assignment of copy construction will not copy the data itself.
1476 To force a deep copy you can all the <code>ForceDeepCopy()</code> function on
1477 each of the instances of each thread after the assignment or copying has been
1478 done.
1479
1480 <p>Another possibility is to compile the FunctionParser library so that
1481 its <code>Eval()</code> function will be thread-safe. (This can be done by
1482 defining the <code>FP_USE_THREAD_SAFE_EVAL</code> or the
1483 <code>FP_USE_THREAD_SAFE_EVAL_WITH_ALLOCA</code>
1484 precompiler constant.) As long as only one thread calls the other functions
1485 of FunctionParser, the other threads can safely call the <code>Eval()</code>
1486 of this one instance.
1487
1488 <p>Note, however, that compiling the library like this can make
1489 <code>Eval()</code> slightly slower. (The <code>alloca</code> version, if
1490 supported by the compiler, will not be as slow.)
1491
1492 <p>Also note that the MPFR and GMP versions of the library cannot be
1493   made thread-safe, and thus this setting has no effect on them.
1494
1495
1496 <!-- -------------------------------------------------------------------- -->
1497 <a name="tipsandtricks"></a>
1498 <h3>Tips and tricks</h3>
1499
1500 <h4>Add constants automatically to all parser objects</h4>
1501
1502 <p>Often the same constants (such as <em>pi</em> and <em>e</em>) and other
1503 user-defined identifiers (such as units) are always used in all the
1504 <code>FunctionParser</code> objects throughout the program. It would be
1505 troublesome to always have to manually add these constants every time a
1506 new parser object is created.
1507
1508 <p>There is, however, a simple way to always add these user-defined identifiers
1509 to all instances. Write a class like this:
1510
1511 <pre>
1512     class ParserWithConsts: public FunctionParser
1513     {
1514      public:
1515         ParserWithConsts()
1516         {
1517             AddConstant("pi", 3.14159265358979323846);
1518             AddConstant("e", 2.71828182845904523536);
1519         }
1520     };
1521 </pre>
1522
1523 <p>Now instead of using <code>FunctionParser</code>, always use
1524 <code>ParserWithConsts</code>. It will behave identically except that the
1525 constants (and possibly other user-defined identifiers) will always be
1526 automatically defined. (Objects of this type even survive
1527 <a href="http://en.wikipedia.org/wiki/Object_slicing">slicing</a>, so
1528 they are completely safe to use anywhere.)
1529
1530
1531 <!-- -------------------------------------------------------------------- -->
1532 <a name="contact"></a>
1533 <h3>Contacting the author</h3>
1534
1535 <p>Any comments, bug reports, etc. should be sent to warp@iki.fi
1536
1537
1538 <!-- -------------------------------------------------------------------- -->
1539 <!--
1540 <a name="algorithm"></a>
1541 <h2>The algorithm used in the library</h2>
1542
1543 <p>The whole idea behind the algorithm is to convert the regular infix
1544 format (the regular syntax for mathematical operations in most languages,
1545 like C and the input of the library) to postfix format. The postfix format
1546 is also called stack arithmetic since an expression in postfix format
1547 can be evaluated using a stack and operating with the top of the stack.
1548
1549 <p>For example:
1550
1551 <p><table border=2>
1552 <tr><th>infix</th> <th>postfix</th></tr>
1553 <tr><td><code>2+3</code></td><td><code>2 3 +</code></td></tr>
1554 <tr><td><code>1+2+3</code></td><td><code>1 2 + 3 +</code></td></tr>
1555 <tr><td><code>5*2+8/2</code></td><td><code>5 2 * 8 2 / +</code></td></tr>
1556 <tr><td><code>(5+9)*3</code></td><td><code>5 9 + 3 *</code></td></tr>
1557 </table>
1558
1559 <p>The postfix notation should be read in this way:
1560
1561 <p>Let's take for example the expression: <code>5 2 * 8 2 / +</code>
1562 <ul>
1563  <li>Put 5 on the stack
1564  <li>Put 2 on the stack
1565  <li>Multiply the two values on the top of the stack and put the result on
1566     the stack (removing the two old values)
1567  <li>Put 8 on the stack
1568  <li>Put 2 on the stack
1569  <li>Divide the two values on the top of the stack
1570  <li>Add the two values on the top of the stack (which are in this case
1571     the result of 5*2 and 8/2, that is, 10 and 4).
1572 </ul>
1573
1574 <p>At the end there's only one value in the stack, and that value is the
1575 result of the expression.
1576
1577 <p>Why stack arithmetic?
1578
1579 <p>The last example above can give you a hint.
1580   In infix format operators have precedence and we have to use parentheses to
1581 group operations with lower precedence to be calculated before operations
1582 with higher precedence.
1583   This causes a problem when evaluating an infix expression, specially
1584 when converting it to byte code. For example in this kind of expression:
1585     <code>(x+1)/(y+2)</code>
1586 we have to calculate first the two additions before we can calculate the
1587 division. We have to also keep counting parentheses, since there can be
1588 a countless amount of nested parentheses. This usually means that you
1589 have to do some type of recursion.
1590
1591 <p>The simplest and mostefficient way of calculating this is to convert it
1592 to postfix notation.
1593   The postfix notation has the advantage that you can make all operations
1594 in a straightforward way. You just evaluate the expression from left to
1595 right, applying each operation directly and that's it. There are no
1596 parentheses to worry about. You don't need recursion anywhere.
1597   You have to keep a stack, of course, but that's extremely easily done.
1598 Also you just operate with the top of the stack, which makes it very easy.
1599 You never have to go deeper than 2 items in the stack.
1600   And even better: Evaluating an expression in postfix format is never
1601 slower than in infix format. All the contrary, in many cases it's a lot
1602 faster (eg. because all parentheses are optimized away).
1603   The above example could be expressed in postfix format:
1604     <code>x 1 + y 2 + /</code>
1605
1606 <p>The good thing about the postfix notation is also the fact that it can
1607 be extremely easily expressed in bytecode form.
1608   You only need a byte value for each operation, for each variable and
1609 to push a constant to the stack.
1610   Then you can interpret this bytecode straightforwardly. You just interpret
1611 it byte by byte, from the beginning to the end. You never have to go back,
1612 make loops or anything.
1613
1614 <p>This is what makes byte-coded stack arithmetic so fast.
1615 -->
1616
1617
1618 <!-- -------------------------------------------------------------------- -->
1619 <a name="license"></a>
1620 <h2>Usage license</h2>
1621
1622 <p>Copyright © 2003-2010 Juha Nieminen, Joel Yliluoma
1623
1624 <p>This Library is distributed under the
1625   <a href="http://www.gnu.org/copyleft/lesser.html">Lesser General Public
1626     License</a> (LGPL) version 3.
1627
1628 </body>
1629 </html>