For a complete documentation, see the documentation site. |
---|
EvalEx is a handy expression evaluator for Java, that allows to parse and evaluate expression strings.
- Supports numerical, boolean, string, date time, duration, array and structure expressions, operations and variables.
- Array and structure support: Arrays and structures can be mixed, building arbitrary data structures.
- Supports the NULL datatype.
- 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.
- Requires minimum Java version 11.
The full documentation for EvalEx can be found on GitHub Pages
For announcements, questions and ideas visit the Discussions area.
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.
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.3.0</version>
</dependency>
</dependencies>
If you're using gradle add the dependencies to your project's app build.gradle:
dependencies {
compile 'com.ezylang:EvalEx:3.3.0'
}
Expression expression = new Expression("1 + 2 / (4 * SQRT(4))");
EvaluationValue result = expression.evaluate();
System.out.println(result.getNumberValue()); // prints 1.25
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
Using a copy of the expression allows a thread-safe evaluation of that copy, without parsing the expression again. The copy uses the same expression string, configuration and syntax tree. The existing expression will be parsed to populate the syntax tree.
Make sure each thread has its own copy of the original expression.
Expression expression = new Expression("a + b").with("a", 1).and("b", 2);
Expression copiedExpression = expression.copy().with("a", 3).and("b", 4);
EvaluationValue result = expression.evaluate();
EvaluationValue copiedResult = copiedExpression.evaluate();
System.out.println(result.getNumberValue()); // prints 3
System.out.println(copiedResult.getNumberValue()); // prints 7
Instead of specifying the variable values one by one, they can be set by defining a map with names and values and then passing it to the withValues() method:
The data conversion of the passed values will automatically be performed through a customizable converter.
It is also possible to configure a custom data accessor to read and write values.
Expression expression = new Expression("a+b+c");
Map<String, Object> values = new HashMap<>();
values.put("a", true);
values.put("b", " : ");
values.put("c", 24.7);
EvaluationValue result = expression.withValues(values).evaluate();
System.out.println(result.getStringValue()); // prints "true : 24.7"
See chapter Data Types for details on the conversion.
Another option to have EvalEx use your data is to define a custom data accessor.
See chapter Data Access for details.
Expression expression = new Expression("level > 2 || level <= 0");
EvaluationValue result = expression
.with("level", 3.5)
.evaluate();
System.out.println(result.getBooleanValue()); // prints true
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 or instances of Java arrays.
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", new Object[] {2, 4, 6})
.and("i", 1)
.evaluate();
System.out.println(result.getNumberValue()); // prints 4
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
Date-tme and duration values are supported. There are functions to create, parse and format these values. Additionally, the plus and minus operators can be used to e.g. add or subtract durations, or to calculate the difference between two dates:
Instant start = Instant.parse("2023-12-05T11:20:00.00Z");
Instant end = Instant.parse("2023-12-04T23:15:30.00Z");
Expression expression = new Expression("start - end");
EvaluationValue result = expression
.with("start", start)
.and("end", end)
.evaluate();
System.out.println(result); // will print "EvaluationValue(value=PT12H4M30S, dataType=DURATION)"
See the Documentation for more details.
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.
Copyright 2012-2023 by Udo Klimaschewski
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)