2020-07-27 19:25:59 +03:00
# MathExecutor [![Tests](https://github.com/neonxp/MathExecutor/workflows/Tests/badge.svg)](https://github.com/neonxp/MathExecutor/actions?query=workflow%3ATests)
2013-03-14 04:27:37 +04:00
2019-01-12 16:23:25 +03:00
# A simple and extensible math expressions calculator
2013-09-06 08:26:53 +04:00
2018-10-30 23:16:01 +03:00
## Features:
2018-11-26 18:06:26 +03:00
* Built in support for +, -, *, / and power (^) operators plus ()
2019-11-27 19:39:51 +03:00
* Logical operators (==, !=, < , < , >=, < =, && , ||)
* Built in support for most PHP math functions
* Conditional If logic
2018-10-30 23:16:01 +03:00
* Support for user defined operators
* Support for user defined functions
2020-07-27 05:14:51 +03:00
* Dynamic variable resolution (delayed computation)
2018-12-20 00:07:24 +03:00
* Unlimited variable name lengths
* String support, as function parameters or as evaluated as a number by PHP
2018-10-30 23:16:01 +03:00
* Exceptions on divide by zero, or treat as zero
2018-12-20 00:07:24 +03:00
* Unary Minus (e.g. -3)
2018-11-26 18:06:26 +03:00
* Pi ($pi) and Euler's number ($e) support to 11 decimal places
2019-01-12 16:23:25 +03:00
* Easily extensible
2013-03-14 04:36:17 +04:00
2018-10-30 23:16:01 +03:00
## Install via Composer:
2013-09-06 17:30:48 +04:00
```
2020-02-08 01:45:33 +03:00
composer require nxp/math-executor
2013-09-06 17:30:48 +04:00
```
2013-08-03 14:47:47 +04:00
## Sample usage:
```php
2020-05-15 22:04:57 +03:00
use NXP\MathExecutor;
2013-08-03 14:47:47 +04:00
2020-05-15 21:51:23 +03:00
$executor = new MathExecutor();
2013-08-03 14:47:47 +04:00
2019-11-27 19:39:51 +03:00
echo $executor->execute('1 + 2 * (2 - (4+10))^2 + sin(10)');
2013-08-03 14:47:47 +04:00
```
## Functions:
Default functions:
2019-11-27 19:39:51 +03:00
* abs
2020-10-20 01:48:30 +03:00
* acos (arccos)
2019-11-27 19:39:51 +03:00
* acosh
2020-10-20 01:48:30 +03:00
* arcctg (arccot, arccotan)
* arcsec
* arccsc (arccosec)
* asin (arcsin)
* atan (atn, arctan, arctg)
2019-11-27 19:39:51 +03:00
* atan2
* atanh
2013-09-06 05:42:09 +04:00
* avg
2019-11-27 19:39:51 +03:00
* bindec
* ceil
* cos
2020-10-20 01:48:30 +03:00
* cosec (csc)
2019-11-27 19:39:51 +03:00
* cosh
2020-10-20 01:48:30 +03:00
* ctg (cot, cotan, cotg, ctn)
2019-11-27 19:39:51 +03:00
* decbin
* dechex
* decoct
* deg2rad
* exp
* expm1
* floor
* fmod
* hexdec
* hypot
* if
* intdiv
2020-10-20 01:48:30 +03:00
* log (ln)
* log10 (lg)
2019-11-27 19:39:51 +03:00
* log1p
* max
* min
* octdec
* pi
* pow
* rad2deg
* round
2020-10-20 01:48:30 +03:00
* sec
2019-11-27 19:39:51 +03:00
* sin
* sinh
* sqrt
2020-10-20 01:48:30 +03:00
* tan (tn, tg)
2019-11-27 19:39:51 +03:00
* tanh
2013-08-03 14:47:47 +04:00
Add custom function to executor:
```php
2019-01-12 16:23:25 +03:00
$executor->addFunction('abs', function($arg) {return abs($arg);});
2013-08-03 14:47:47 +04:00
```
2019-01-12 16:23:25 +03:00
Function default parameters are not supported at this time.
2013-08-03 14:47:47 +04:00
## Operators:
Default operators: `+ - * / ^`
2013-09-06 05:42:09 +04:00
Add custom operator to executor:
2013-08-03 14:47:47 +04:00
```php
2020-05-15 22:04:57 +03:00
use NXP\Classes\Operator;
$executor->addOperator(new Operator(
2020-05-15 21:51:23 +03:00
'%', // Operator sign
false, // Is right associated operator
170, // Operator priority
function (& $stack)
2013-09-06 05:42:09 +04:00
{
2020-05-15 21:51:23 +03:00
$op2 = array_pop($stack);
$op1 = array_pop($stack);
$result = $op1->getValue() % $op2->getValue();
2020-05-20 05:37:16 +03:00
2020-05-15 21:51:23 +03:00
return $result;
2013-09-06 05:42:09 +04:00
}
2020-05-15 21:51:23 +03:00
));
2013-09-06 08:19:02 +04:00
```
2019-11-27 19:39:51 +03:00
## Logical operators:
Logical operators (==, !=, < , < , >=, < =, && , ||) are supported, but logically they can only return true (1) or false (0). In order to leverage them, use the built in **if** function:
```
if($a > $b, $a - $b, $b - $a)
```
You can think of the **if** function as prototyped like:
```
function if($condition, $returnIfTrue, $returnIfFalse)
```
2013-09-06 08:19:02 +04:00
## Variables:
2020-07-27 19:25:59 +03:00
Variables can be prefixed with the dollar sign ($) for PHP compatibility, but is not required.
2013-09-06 08:19:02 +04:00
Default variables:
2013-09-06 08:35:55 +04:00
```
2013-09-06 08:19:02 +04:00
$pi = 3.14159265359
2019-08-16 17:27:44 +03:00
$e = 2.71828182846
2013-09-06 08:35:55 +04:00
```
2013-09-06 08:19:02 +04:00
2018-12-20 00:07:24 +03:00
You can add your own variables to executor:
2013-09-06 08:19:02 +04:00
```php
2020-05-20 05:37:16 +03:00
$executor->setVar('var1', 0.15)->setVar('var2', 0.22);
2018-10-30 23:16:01 +03:00
2020-07-27 19:25:59 +03:00
echo $executor->execute("$var1 + var2");
2018-10-30 23:16:01 +03:00
```
2020-07-27 05:14:51 +03:00
You can dynamically define variables at run time. If a variable has a high computation cost, but might not be used, then you can define an undefined variable handler. It will only get called when the variable is used, rather than having to always set it initially.
```php
$calculator = new MathExecutor();
$calculator->setVarNotFoundHandler(
function ($varName) {
if ($varName == 'trans') {
return transmogrify();
}
return null;
}
);
```
2018-10-30 23:16:01 +03:00
## Division By Zero Support:
2020-05-20 05:37:16 +03:00
Division by zero throws a `\NXP\Exception\DivisionByZeroException` by default
2018-10-30 23:16:01 +03:00
```php
try {
echo $executor->execute('1/0');
2020-05-15 21:51:23 +03:00
} catch (DivisionByZeroException $e) {
2018-10-30 23:16:01 +03:00
echo $e->getMessage();
}
```
2020-05-20 05:37:16 +03:00
Or call setDivisionByZeroIsZero
```php
echo $executor->setDivisionByZeroIsZero()->execute('1/0');
```
If you want another behavior, you can override division operator:
2020-05-15 21:51:23 +03:00
```php
$executor->addOperator("/", false, 180, function($a, $b) {
if ($b == 0) {
2020-05-20 05:37:16 +03:00
return null;
2020-05-15 21:51:23 +03:00
}
return $a / $b;
});
echo $executor->execute('1/0');
```
2018-10-30 23:16:01 +03:00
## Unary Minus Operator:
2019-08-16 17:27:44 +03:00
Negative numbers are supported via the unary minus operator. Positive numbers are not explicitly supported as unsigned numbers are assumed positive.
2018-10-30 23:16:01 +03:00
## String Support:
2018-12-20 00:07:24 +03:00
Expressions can contain double or single quoted strings that are evaluated the same way as PHP evalutes strings as numbers. You can also pass strings to functions.
2018-10-30 23:16:01 +03:00
```php
echo $executor->execute("1 + '2.5' * '.5' + myFunction('category')");
```
2019-01-10 21:35:39 +03:00
## Extending MathExecutor
You can add operators, functions and variables with the public methods in MathExecutor, but if you need to do more serious modifications to base behaviours, the easiest way to extend MathExecutor is to redefine the following methods in your derived class:
* defaultOperators
* defaultFunctions
* defaultVars
This will allow you to remove functions and operators if needed, or implement different types more simply.
2019-01-10 21:53:34 +03:00
Also note that you can replace an existing default operator by adding a new operator with the same regular expression string. For example if you just need to redefine TokenPlus, you can just add a new operator with the same regex string, in this case '\\+'.
2019-08-16 17:27:44 +03:00
2020-04-11 03:40:21 +03:00
## Documentation
Full class documentation via [PHPFUI/InstaDoc ](http://phpfui.com/?n=NXP&c=MathExecutor )
2019-08-16 17:27:44 +03:00
## Future Enhancements
2020-04-11 03:40:21 +03:00
This package will continue to track currently supported versions of PHP. PHP 7.1 and earlier support will be dropped when PHP 8 is released.