java.lang.Object
- com.udojava.evalex.Expression

public class Expression
extends Object

EvalEx - Java Expression Evaluator

Introduction

EvalEx is a handy expression evaluator for Java, that allows to evaluate simple mathematical and boolean expressions.
Key Features:

Uses BigDecimal for calculation and result
Single class implementation, very compact
No dependencies to external libraries
Precision and rounding mode can be set
Supports variables
Standard boolean and mathematical operators
Standard basic mathematical and boolean functions
Custom functions and operators can be added at runtime

Examples

  BigDecimal result = null;
  
  Expression expression = new Expression("1+1/3");
  result = expression.eval():
  expression.setPrecision(2);
  result = expression.eval():
  
  result = new Expression("(3.4 + -4.1)/2").eval();
  
  result = new Expression("SQRT(a^2 + b^2").with("a","2.4").and("b","9.253").eval();
  
  BigDecimal a = new BigDecimal("2.4");
  BigDecimal b = new BigDecimal("9.235");
  result = new Expression("SQRT(a^2 + b^2").with("a",a).and("b",b).eval();
  
  result = new Expression("2.4/PI").setPrecision(128).setRoundingMode(RoundingMode.UP).eval();
  
  result = new Expression("random() > 0.5").eval();
 
  result = new Expression("not(x<7 || sqrt(max(x,9)) <= 3))").with("x","22.9").eval();

Supported Operators

Mathematical Operators
Operator	Description
+	Additive operator
-	Subtraction operator
*	Multiplication operator
/	Division operator
%	Remainder operator (Modulo)
^	Power operator

Boolean Operators^*
Operator	Description
=	Equals
==	Equals
!=	Not equals
<>	Not equals
<	Less than
<=	Less than or equal to
>	Greater than
>=	Greater than or equal to
&&	Boolean and
\|\|	Boolean or

*Boolean operators result always in a BigDecimal value of 1 or 0 (zero). Any non-zero value is treated as a _true_ value. Boolean _not_ is implemented by a function.

Supported Functions

Function^*	Description
NOT(expression)	Boolean negation, 1 (means true) if the expression is not zero
IF(condition,value_if_true,value_if_false)	Returns one value if the condition evaluates to true or the other if it evaluates to false
RANDOM()	Produces a random number between 0 and 1
MIN(e1,e2, ...)	Returns the smallest of the given expressions
MAX(e1,e2, ...)	Returns the biggest of the given expressions
ABS(expression)	Returns the absolute (non-negative) value of the expression
ROUND(expression,precision)	Rounds a value to a certain number of digits, uses the current rounding mode
FLOOR(expression)	Rounds the value down to the nearest integer
CEILING(expression)	Rounds the value up to the nearest integer
LOG(expression)	Returns the natural logarithm (base e) of an expression
LOG10(expression)	Returns the common logarithm (base 10) of an expression
SQRT(expression)	Returns the square root of an expression
SIN(expression)	Returns the trigonometric sine of an angle (in degrees)
COS(expression)	Returns the trigonometric cosine of an angle (in degrees)
TAN(expression)	Returns the trigonometric tangens of an angle (in degrees)
ASIN(expression)	Returns the angle of asin (in degrees)
ACOS(expression)	Returns the angle of acos (in degrees)
ATAN(expression)	Returns the angle of atan (in degrees)
SINH(expression)	Returns the hyperbolic sine of a value
COSH(expression)	Returns the hyperbolic cosine of a value
TANH(expression)	Returns the hyperbolic tangens of a value
RAD(expression)	Converts an angle measured in degrees to an approximately equivalent angle measured in radians
DEG(expression)	Converts an angle measured in radians to an approximately equivalent angle measured in degrees

*Functions names are case insensitive.

Supported Constants

Constant	Description
e	The value of e, exact to 70 digits
PI	The value of PI, exact to 100 digits
TRUE	The value one
FALSE	The value zero

Add Custom Operators

Custom operators can be added easily, simply create an instance of `Expression.Operator` and add it to the expression. Parameters are the operator string, its precedence and if it is left associative. The operators `eval()` method will be called with the BigDecimal values of the operands. All existing operators can also be overridden.
For example, add an operator `x >> n`, that moves the decimal point of _x_ _n_ digits to the right:

 Expression e = new Expression("2.1234 >> 2");
 
 e.addOperator(e.new Operator(">>", 30, true) {
     @Override
     public BigDecimal eval(BigDecimal v1, BigDecimal v2) {
         return v1.movePointRight(v2.toBigInteger().intValue());
     }
 });
 
 e.eval(); // returns 212.34

Add Custom Functions

Adding custom functions is as easy as adding custom operators. Create an instance of `Expression.Function`and add it to the expression. Parameters are the function name and the count of required parameters. The functions `eval()` method will be called with a list of the BigDecimal parameters. All existing functions can also be overridden.
A -1 as the number of parameters denotes a variable number of arguments.
For example, add a function `average(a,b,c)`, that will calculate the average value of a, b and c:

 Expression e = new Expression("2 * average(12,4,8)");
 
 e.addFunction(e.new Function("average", 3) {
     @Override
     public BigDecimal eval(List parameters) {
         BigDecimal sum = parameters.get(0).add(parameters.get(1)).add(parameters.get(2));
         return sum.divide(new BigDecimal(3));
     }
 });
 
 e.eval(); // returns 16

The software is licensed under the MIT Open Source license (see LICENSE file).

The *power of* operator (^) implementation was copied from [Stack Overflow ](http://stackoverflow.com/questions/3579779/how-to-do-a-fractional-power -on-bigdecimal-in-java) Thanks to Gene Marin
The SQRT() function implementation was taken from the book [The Java Programmers Guide To numerical Computing](http://www.amazon.de/Java-Number-Cruncher -Programmers-Numerical/dp/0130460419) (Ronald Mak, 2002)

Author:: Udo Klimaschewski (http://about.me/udo.klimaschewski)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Expression.ExpressionException` The expression evaluators exception class.
`class`	`Expression.Function` Abstract definition of a supported expression function.
`class`	`Expression.LazyFunction`
`class`	`Expression.Operator` Abstract definition of a supported operator.

Field Summary

Fields
Modifier and Type	Field and Description
`static BigDecimal`	`e` Definition of e: "Euler's number" as a constant, can be used in expressions as variable.
`static BigDecimal`	`PI` Definition of PI as a constant, can be used in expressions as variable.

Constructor Summary

Constructors
Constructor and Description
`Expression(String expression)` Creates a new expression instance from an expression string with a given default match context of `MathContext.DECIMAL32`.
`Expression(String expression, MathContext defaultMathContext)` Creates a new expression instance from an expression string with a given default match context.

Method Summary

Methods
Modifier and Type	Method and Description
`Expression.Function`	`addFunction(Expression.Function function)` Adds a function to the list of supported functions
`Expression.LazyFunction`	`addLazyFunction(Expression.LazyFunction function)` Adds a lazy function function to the list of supported functions
`Expression.Operator`	`addOperator(Expression.Operator operator)` Adds an operator to the list of supported operators.
`Expression`	`and(String variable, BigDecimal value)` Sets a variable value.
`Expression`	`and(String variable, String value)` Sets a variable value.
`BigDecimal`	`eval()` Evaluates the expression.
`Set<String>`	`getDeclaredFunctions()` Exposing declared functions.
`Set<String>`	`getDeclaredOperators()` Exposing declared operators in the expression.
`Set<String>`	`getDeclaredVariables()` Exposing declared variables in the expression.
`String`	`getExpression()`
`Iterator<String>`	`getExpressionTokenizer()` Get an iterator for this expression, allows iterating over an expression token by token.
`Expression`	`setPrecision(int precision)` Sets the precision for expression evaluation.
`Expression`	`setRoundingMode(RoundingMode roundingMode)` Sets the rounding mode for expression evaluation.
`Expression`	`setVariable(String variable, BigDecimal value)` Sets a variable value.
`Expression`	`setVariable(String variable, String value)` Sets a variable value.
`String`	`toRPN()` Get a string representation of the RPN (Reverse Polish Notation) for this expression.
`Expression`	`with(String variable, BigDecimal value)` Sets a variable value.
`Expression`	`with(String variable, String value)` Sets a variable value.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - PI
```
public static final BigDecimal PI
```
    Definition of PI as a constant, can be used in expressions as variable.
  - e
```
public static final BigDecimal e
```
    Definition of e: "Euler's number" as a constant, can be used in expressions as variable.
- Constructor Detail
  - Expression
```
public Expression(String expression)
```
    Creates a new expression instance from an expression string with a given default match context of MathContext.DECIMAL32.
    
    Parameters:
    expression - The expression. E.g. "2.4*sin(3)/(2-4)" or "sin(y)>0 & max(z, 3)>3"
  - Expression
```
public Expression(String expression,
          MathContext defaultMathContext)
```
    Creates a new expression instance from an expression string with a given default match context.
    
    Parameters:
    expression - The expression. E.g. "2.4*sin(3)/(2-4)" or "sin(y)>0 & max(z, 3)>3"
    defaultMathContext - The MathContext to use by default.
- Method Detail
  - eval
```
public BigDecimal eval()
```
    Evaluates the expression.
    
    Returns:
    The result of the expression.
  - setPrecision
```
public Expression setPrecision(int precision)
```
    Sets the precision for expression evaluation.
    
    Parameters:
    precision - The new precision.
    
    Returns:
    The expression, allows to chain methods.
  - setRoundingMode
```
public Expression setRoundingMode(RoundingMode roundingMode)
```
    Sets the rounding mode for expression evaluation.
    
    Parameters:
    roundingMode - The new rounding mode.
    
    Returns:
    The expression, allows to chain methods.
  - addOperator
```
public Expression.Operator addOperator(Expression.Operator operator)
```
    Adds an operator to the list of supported operators.
    
    Parameters:
    operator - The operator to add.
    
    Returns:
    The previous operator with that name, or null if there was none.
  - addFunction
```
public Expression.Function addFunction(Expression.Function function)
```
    Adds a function to the list of supported functions
    
    Parameters:
    function - The function to add.
    
    Returns:
    The previous operator with that name, or null if there was none.
  - addLazyFunction
```
public Expression.LazyFunction addLazyFunction(Expression.LazyFunction function)
```
    Adds a lazy function function to the list of supported functions
    
    Parameters:
    function - The function to add.
    
    Returns:
    The previous operator with that name, or null if there was none.
  - setVariable
```
public Expression setVariable(String variable,
                     BigDecimal value)
```
    Sets a variable value.
    
    Parameters:
    variable - The variable name.
    value - The variable value.
    
    Returns:
    The expression, allows to chain methods.
  - setVariable
```
public Expression setVariable(String variable,
                     String value)
```
    Sets a variable value.
    
    Parameters:
    variable - The variable to set.
    value - The variable value.
    
    Returns:
    The expression, allows to chain methods.
  - with
```
public Expression with(String variable,
              BigDecimal value)
```
    Sets a variable value.
    
    Parameters:
    variable - The variable to set.
    value - The variable value.
    
    Returns:
    The expression, allows to chain methods.
  - and
```
public Expression and(String variable,
             String value)
```
    Sets a variable value.
    
    Parameters:
    variable - The variable to set.
    value - The variable value.
    
    Returns:
    The expression, allows to chain methods.
  - and
```
public Expression and(String variable,
             BigDecimal value)
```
    Sets a variable value.
    
    Parameters:
    variable - The variable to set.
    value - The variable value.
    
    Returns:
    The expression, allows to chain methods.
  - with
```
public Expression with(String variable,
              String value)
```
    Sets a variable value.
    
    Parameters:
    variable - The variable to set.
    value - The variable value.
    
    Returns:
    The expression, allows to chain methods.
  - getExpressionTokenizer
```
public Iterator<String> getExpressionTokenizer()
```
    Get an iterator for this expression, allows iterating over an expression token by token.
    
    Returns:
    A new iterator instance for this expression.
  - toRPN
```
public String toRPN()
```
    Get a string representation of the RPN (Reverse Polish Notation) for this expression.
    
    Returns:
    A string with the RPN representation for this expression.
  - getDeclaredVariables
```
public Set<String> getDeclaredVariables()
```
    Exposing declared variables in the expression.
    
    Returns:
    All declared variables.
  - getDeclaredOperators
```
public Set<String> getDeclaredOperators()
```
    Exposing declared operators in the expression.
    
    Returns:
    All declared operators.
  - getDeclaredFunctions
```
public Set<String> getDeclaredFunctions()
```
    Exposing declared functions.
    
    Returns:
    All declared functions.
  - getExpression
```
public String getExpression()
```
    Returns:
    The original expression string

Class Expression

EvalEx - Java Expression Evaluator

Introduction

Examples

Supported Operators

Supported Functions

Supported Constants

Add Custom Operators

Add Custom Functions

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PI

e

Constructor Detail

Expression

Expression

Method Detail

eval

setPrecision

setRoundingMode

addOperator

addFunction

addLazyFunction

setVariable

setVariable

with

and

and

with

getExpressionTokenizer

toRPN

getDeclaredVariables

getDeclaredOperators

getDeclaredFunctions

getExpression