EvalEx - Java Expression Evaluator

⚠️ Version 3 of EvalEx is a complete rewrite of the popular expression evaluator. See the new documentation area for an overview of the changes.

EvalEx is a handy expression evaluator for Java, that allows to parse and evaluate expression strings.

Key Features:

Supports numerical, boolean, string, array and structure expressions, operations and variables.
Array and structure support: Arrays and structures can be mixed, building arbitrary data structures.
Uses BigDecimal for numerical calculations.
MathContext and number of decimal places can be configured, with optional automatic rounding.
No dependencies to external libraries.
Easy integration into existing systems to access data.
Predefined boolean and mathematical operators.
Predefined mathematical, boolean and string functions.
Custom functions and operators can be added.
Functions can be defined with a variable number of arguments (see MIN, MAX and SUM functions).
Supports hexadecimal and scientific notations of numbers.
Supports implicit multiplication, e.g. 2x or (a+b)(a-b) or 2(x-y) which equals to (a+b)*(a-b) or 2*( x-y)
Lazy evaluation of function parameters (see the IF function) and support of sub-expressions.

Documentation

The full documentation for EvalEx can be found on GitHub Pages

Discussion

For announcements, questions and ideas visit the Discussions area.

Download / Including

You can download the binaries, source code and JavaDoc jars from Maven Central.
You will find there also copy/paste templates for including EvalEx in your project with build systems like Maven or Gradle.

Maven

To include it in your Maven project, add the dependency to your pom. For example:

<dependencies>
    <dependency>
      <groupId>com.ezylang</groupId>
      <artifactId>EvalEx</artifactId>
      <version>3.0.2</version>
    </dependency>
</dependencies>

Gradle

If you're using gradle add the dependencies to your project's app build.gradle:

dependencies {
    compile 'com.ezylang:EvalEx:3.0.2'
}

Examples

A simple example, that shows how it works in general:

Expression expression = new Expression("1 + 2 / (4 * SQRT(4))");

EvaluationValue result = expression.evaluate();

System.out.println(result.getNumberValue()); // prints 1.25

Variables can be specified in the expression and their values can be passed for evaluation:

Expression expression = new Expression("(a + b) * (a - b)");

EvaluationValue result = expression
    .with("a", 3.5)
    .and("b", 2.5)
    .evaluate();

System.out.println(result.getNumberValue()); // prints 6.00

Boolean expressions produce a boolean result:

Expression expression = new Expression("level > 2 || level <= 0");

EvaluationValue result = expression
    .with("level", 3.5)
    .evaluate();

System.out.println(result.getBooleanValue()); // prints true

Like in Java, strings and text can be mixed:

Expression expression = new Expression("\"Hello \" + name + \", you are \" + age")
    .with("name","Frank")
    .and("age",38);

System.out.println(expression.evaluate().getStringValue()); // prints Hello Frank, you are 38

Arrays (also multidimensional) are supported and can be passed as Java Lists.

See the Documentation for more details.

Expression expression = new Expression("values[i-1] * factors[i-1]");

EvaluationValue result = expression
    .with("values", List.of(2, 3, 4))
    .and("factors", List.of(2, 4, 6))
    .and("i", 1)
    .evaluate();

System.out.println(result.getNumberValue()); // prints 4

Structures are supported and can be passed as Java Maps.

Arrays and Structures can be combined to build arbitrary data structures. See the Documentation for more details.

Map<String, Object> order = new HashMap<>();
order.put("id", 12345);
order.put("name", "Mary");

Map<String, Object> position = new HashMap<>();
position.put("article", 3114);
position.put("amount", 3);
position.put("price", new BigDecimal("14.95"));

order.put("positions", List.of(position));

Expression expression = new Expression("order.positions[x].amount * order.positions[x].price")
    .with("order", order)
    .and("x", 0);

BigDecimal result = expression.evaluate().getNumberValue();

System.out.println(result); // prints 44.85

EvalEx-big-math

Big-math is a library by Eric Obermühlner. It provides advanced Java BigDecimal math functions using an arbitrary precision.

EvalEx-big-math adds the advanced math functions from big-math to EvalEx.

Author and License

Thanks to all who contributed to this project: Contributors

The software is licensed under the Apache License, Version 2.0 ( see LICENSE file).

The power of operator (^) implementation was copied from Stack Overflow Thanks to Gene Marin
The SQRT() function implementation was taken from the book The Java Programmers Guide To numerical Computing ( Ronald Mak, 2002)

xymelon / EvalEx