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