### LOG10 Function Examples

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Calculates the base 10 logarithm of a given number. Use for base-10 logarithmic calculations.

```evalex
LOG10(100)
```

```evalex
LOG10(10)
```

```evalex
LOG10(2.12345)
```

--------------------------------

### MIN Function Examples

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns the minimum value from a list of numbers or array elements. Handles both single values and arrays.

```evalex
MIN(numbers)
```

```evalex
MIN(x, y)
```

```evalex
MIN(x, y, numbers)
```

--------------------------------

### Check if String Starts With Substring

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

STR_STARTS_WITH determines if a string begins with a specific substring. The comparison is case-sensitive.

```evalex
STR_STARTS_WITH(title, "Data")
```

```evalex
STR_STARTS_WITH(title, "data")
```

```evalex
STR_STARTS_WITH(code, "ERR")
```

--------------------------------

### RANDOM Function Examples

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Produces a random floating-point number between 0 (inclusive) and 1 (exclusive). Results vary with each call.

```evalex
RANDOM()
```

```evalex
RANDOM()
```

--------------------------------

### NOT Function Examples

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Performs a Boolean negation on a given value. Use for inverting logical states.

```evalex
NOT(flag)
```

```evalex
NOT(x < 5)
```

--------------------------------

### MAX Function Examples

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns the maximum value from a list of numbers or array elements. Handles both single values and arrays.

```evalex
MAX(numbers)
```

```evalex
MAX(x, y)
```

```evalex
MAX(x, y, numbers)
```

--------------------------------

### LOG Function Examples

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Calculates the natural logarithm (base e) of a given number. Use for logarithmic calculations.

```evalex
LOG(2.718)
```

```evalex
LOG(1)
```

```evalex
LOG(10)
```

--------------------------------

### Accessing array elements

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/datatypes.md

Shows how to access elements within a list of mixed data types using index notation. Array indices start at 0.

```java
List<Object> list = List.of(2.5, "Hello", true);

// prints "true" 
System.out.println(
    new Expression("list[2]").with("list", list).evaluate().getStringValue());
```

--------------------------------

### Get Today's Date at Midnight with Evalex

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

DT_TODAY() returns the current date with the time set to midnight (00:00:00). Optionally specify a time zone to get the date in that zone.

```evalex
DT_TODAY()
```

```evalex
DT_TODAY("Australia/Canberra")
```

--------------------------------

### Get String Length

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

STR_LENGTH returns the total number of characters in a string, including spaces and punctuation.

```evalex
STR_LENGTH("abc")
```

```evalex
STR_LENGTH("Hello, EvalEx!")
```

--------------------------------

### STR_SUBSTRING

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Extracts a portion of a string from a start index up to an optional end index.

```APIDOC
## STR_SUBSTRING

### Description
Returns a portion of the string from the specified start index up to the end index (or to the end of the string if not specified).

### Function Signature
STR_SUBSTRING(string, start_index, end_index)
```

--------------------------------

### Add Duration to Date-Time

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/date_time_duration.md

Adds a duration to a date-time instant. Ensure both 'start' and 'duration' are provided as variables.

```java
Instant start = Instant.parse("2023-12-03T23:15:30.00Z");
Duration duration = Duration.ofHours(3);

Expression expression = new Expression("start + duration");
EvaluationValue result =
    expression
        .with("start", start)
        .and("duration", duration)
        .evaluate();
System.out.println(result); // will print "EvaluationValue(value=2023-12-04T02:15:30Z, dataType=DATE_TIME)"
```

--------------------------------

### Get Current Date and Time with DT_NOW

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Retrieve the current date and time as a DATE_TIME value using the DT_NOW function. This is ideal for logging, time-based comparisons, or event triggering.

```evalex
DT_NOW()
```

--------------------------------

### Extract Substring with STR_SUBSTRING

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Use STR_SUBSTRING to extract a portion of a string. The start index is inclusive, and the end index is exclusive. If the end index is omitted, it defaults to the end of the string.

```evalex
STR_SUBSTRING(text, 0, 4)
```

```evalex
STR_SUBSTRING(text, 5)
```

```evalex
STR_SUBSTRING(id, 2, 6)
```

--------------------------------

### STR_SUBSTRING

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Extracts a portion of a string starting from a given index, optionally ending at another index. Available since version 3.4.0.

```APIDOC
## STR_SUBSTRING

### Description
The `STR_SUBSTRING` function extracts a portion of a string starting from a given index and optionally ending at another index. If the end is not specified, it returns the substring until the end of the string.

### Syntax
```
STR_SUBSTRING(string, start[, end])
```
```

--------------------------------

### Convert Duration to Milliseconds with DT_DURATION_TO_MILLIS

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Convert a DURATION value to its equivalent number of milliseconds using DT_DURATION_TO_MILLIS. This function is useful for serializing durations for storage or computation. Note that DT_DURATION_PARSE is used to create DURATION values for these examples.

```evalex
DT_DURATION_TO_MILLIS(DT_DURATION_PARSE("PT1S"))
```

```evalex
DT_DURATION_TO_MILLIS(DT_DURATION_PARSE("PT1M"))
```

--------------------------------

### Configure EvalEx Expression

Source: https://github.com/ezylang/evalex/blob/main/docs/configuration/configuration.md

Demonstrates how to build an ExpressionConfiguration object with all default values and then create an Expression using this configuration. This is useful for understanding the default settings and how to customize them.

```java
ExpressionConfiguration configuration=ExpressionConfiguration.builder()
        .allowOverwriteConstants(true)
        .arraysAllowed(true)
        .dateTimeFormatters(ExpressionConfiguration.DEFAULT_DATE_TIME_FORMATTERS)
        .dataAccessorSupplier(MapBasedDataAccessor::new)
        .decimalPlacesRounding(ExpressionConfiguration.DECIMAL_PLACES_ROUNDING_UNLIMITED)
        .defaultConstants(ExpressionConfiguration.StandardConstants)
        .functionDictionary(ExpressionConfiguration.StandardFunctionsDictionary)
        .implicitMultiplicationAllowed(true)
        .lenientMode(false)
        .locale(Locale.getDefault())
        .mathContext(ExpressionConfiguration.DEFAULT_MATH_CONTEXT)
        .operatorDictionary(ExpressionConfiguration.StandardOperatorsDictionary)
        .powerOfPrecedence(OperatorIfc.OPERATOR_PRECEDENCE_POWER)
        .stripTrailingZeros(true)
        .structuresAllowed(true)
        .binaryAllowed(false)
        .singleQuoteStringLiteralsAllowed(false)
        .zoneId(ZoneId.systemDefault())
        .build();

        Expression expression=new Expression("2.128 + a",configuration);
```

--------------------------------

### STR_STARTS_WITH

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Verifies if a string begins with a specific substring. The comparison is case-sensitive.

```APIDOC
## STR_STARTS_WITH

### Description
Returns true if the string starts with the substring (case-sensitive).

### Function Signature
STR_STARTS_WITH(string, prefix)
```

--------------------------------

### Include EvalEx with Gradle

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Add this dependency to your project's app build.gradle file if you are using Gradle.

```gradle
dependencies {
    compile 'com.ezylang:EvalEx:3.6.2'
}
```

--------------------------------

### Expression Evaluation with Variables

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Demonstrates how to substitute variables within an expression and provide their values for evaluation.

```java
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
```

--------------------------------

### Copying and Evaluating Expressions

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Shows how to create a copy of an expression to evaluate it with a different set of values, ensuring thread safety and avoiding re-parsing.

```java
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
```

--------------------------------

### Create Expression with Custom Configuration

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/parsing_evaluation.md

Create an expression object with a custom configuration, such as setting decimal places for rounding. The configuration is passed to the Expression constructor.

```java
ExpressionConfiguration configuration = ExpressionConfiguration.builder()
    .decimalPlacesRounding(2)
    .build();

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

--------------------------------

### Format String with Arguments

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

STR_FORMAT allows for string formatting using Java's Formatter syntax. Locale settings affect number and date presentation.

```evalex
STR_FORMAT("Hello, %s!", name)
```

```evalex
STR_FORMAT("%03.0f items", count)
```

```evalex
STR_FORMAT("Total: %.2f", price)
```

```evalex
STR_FORMAT("Total: %.2f", price)
```

--------------------------------

### Configure Custom Data Accessor (New Instance Per Expression)

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/data_access.md

Specify a custom data accessor by providing a supplier function that creates a new instance for each expression. This ensures isolated storage per expression.

```java
ExpressionConfiguration configuration = ExpressionConfiguration.builder()
    .dataAccessorSupplier(MyCustomDataAccessor::new)
    .build();

Expression expression = new Expression("2.128 + a", configuration);
```

--------------------------------

### Evaluate Nested Structures and Arrays

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/datatypes.md

Demonstrates how to use nested Maps and Lists as variables in an expression to represent complex data structures. Ensure all necessary imports are present.

```java
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
```

--------------------------------

### Calculate Duration Between Two Date-Times

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/date_time_duration.md

Calculates the duration between two date-time instants. The result is a DURATION type in ISO-8601 format. Ensure 'start' and 'end' are provided.

```java
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)"
```

--------------------------------

### Add Custom Functions via ExpressionConfiguration

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/custom_functions.md

Use `ExpressionConfiguration.defaultConfiguration().withAdditionalFunctions()` to register custom functions like MAX_VALUE and MIN_VALUE. This method accepts a map of function names to their respective implementations.

```java
ExpressionConfiguration configuration = 
    ExpressionConfiguration.defaultConfiguration()
        .withAdditionalFunctions(
            Map.entry("MAX_VALUE", new MaxFunction()),
            Map.entry("MIN_VALUE", new MinFunction()));
    
Expression expression = new Expression("MAX_VALUE(1,2,3) + MIN_VALUE(7,8,9)", configuration);
```

--------------------------------

### Include EvalEx with Maven

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Add this dependency to your Maven project's pom.xml to include EvalEx.

```xml
<dependencies>
    <dependency>
      <groupId>com.ezylang</groupId>
      <artifactId>EvalEx</artifactId>
      <version>3.6.2</version>
    </dependency>
</dependencies>
```

--------------------------------

### Calculate the square root of a number

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

The SQRT function computes the square root of a non-negative number. It uses an implementation from Ronald Mak's 'The Java Programmers Guide To numerical Computing'.

```evalex
SQRT(16)
```

```evalex
SQRT(9)
```

--------------------------------

### STR_FORMAT

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Formats a string using a specified format string and arguments, respecting the configured locale.

```APIDOC
## STR_FORMAT

### Description
Returns a formatted string using the specified format string and arguments, using the configured locale.

### Function Signature
STR_FORMAT(format_string, arg1, arg2, ...)
```

--------------------------------

### Configure MathContext for Precision and Rounding

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/rounding.md

Set the precision and rounding mode for calculations using ExpressionConfiguration and java.math.MathContext. This is useful for controlling the exactness of intermediate and final results.

```java
ExpressionConfiguration configuration = 
    ExpressionConfiguration.builder()
        .mathContext(new MathContext(32, RoundingMode.HALF_UP))
        .build();
```

--------------------------------

### Define Custom Operator Dictionary Interface

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/operator_dictionary.md

Implement this interface to create your own operator dictionary. You must implement methods for adding and retrieving prefix, postfix, and infix operators.

```java
public interface OperatorDictionaryIfc {

  /**
   * Allows to add an operator to the dictionary. Implementation is optional, if you have a fixed
   * set of operators, this method can throw an exception.
   *
   * @param operatorString The operator name.
   * @param operator The operator implementation.
   */
  void addOperator(String operatorString, OperatorIfc operator);

  /**
   * Check if the dictionary has a prefix operator with that name.
   *
   * @param operatorString The operator name to look for.
   * @return <code>true</code> if an operator was found or <code>false</code> if not.
   */
  default boolean hasPrefixOperator(String operatorString) {
    return getPrefixOperator(operatorString) != null;
  }

  /**
   * Check if the dictionary has a postfix operator with that name.
   *
   * @param operatorString The operator name to look for.
   * @return <code>true</code> if an operator was found or <code>false</code> if not.
   */
  default boolean hasPostfixOperator(String operatorString) {
    return getPostfixOperator(operatorString) != null;
  }

  /**
   * Check if the dictionary has an infix operator with that name.
   *
   * @param operatorString The operator name to look for.
   * @return <code>true</code> if an operator was found or <code>false</code> if not.
   */
  default boolean hasInfixOperator(String operatorString) {
    return getInfixOperator(operatorString) != null;
  }

  /**
   * Get the operator definition for a prefix operator name.
   *
   * @param operatorString The name of the operator.
   * @return The operator definition or <code>null</code> if no operator was found.
   */
  OperatorIfc getPrefixOperator(String operatorString);

  /**
   * Get the operator definition for a postfix operator name.
   *
   * @param operatorString The name of the operator.
   * @return The operator definition or <code>null</code> if no operator was found.
   */
  OperatorIfc getPostfixOperator(String operatorString);

  /**
   * Get the operator definition for an infix operator name.
   *
   * @param operatorString The name of the operator.
   * @return The operator definition or <code>null</code> if no operator was found.
   */
  OperatorIfc getInfixOperator(String operatorString);
}
```

--------------------------------

### Configure Custom Function Dictionary

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/function_dictionary.md

Specify your custom function dictionary implementation when building the ExpressionConfiguration.

```java
ExpressionConfiguration configuration = ExpressionConfiguration.builder()
    .functionDictionary(new MyFunctionDirectory())
    .build();

```

--------------------------------

### Pass Variables to Expression using with() and and()

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/parsing_evaluation.md

Set variable values for an expression before evaluation using the chained with() and and() methods. This is useful for dynamic calculations.

```java
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
```

--------------------------------

### Create Duration with DT_DURATION_NEW

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Use DT_DURATION_NEW to construct duration values from days, hours, minutes, seconds, milliseconds, and nanoseconds. Provide either millis or nanos for sub-second precision, not both, to avoid double counting.

```evalex
DT_DURATION_NEW(5)
```

```evalex
DT_DURATION_NEW(0, 1, 15)
```

```evalex
DT_DURATION_NEW(1, 0, 0, 30)
```

```evalex
DT_DURATION_NEW(0, 0, 0, 0, 999)
```

```evalex
DT_DURATION_NEW(0, 0, 0, 0, 0, 999999999)
```

--------------------------------

### Create DATE_TIME from Date Components

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Use DT_DATE_NEW with year, month, and day to create a DATE_TIME value. Optional time, nanoseconds, and time zone can be provided.

```evalex
DT_DATE_NEW(2025, 6, 15)
```

```evalex
DT_DATE_NEW(2025, 6, 15, 9, 30)
```

```evalex
DT_DATE_NEW(2025, 6, 15, "Europe/Berlin")
```

```evalex
DT_DATE_NEW(2025, 6, 15, 9, 30, 0, 0, "Europe/Berlin")
```

--------------------------------

### Create Expression Object

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/parsing_evaluation.md

Instantiate an expression object with a given mathematical expression string. Parsing and validation occur upon evaluation or AST creation.

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

--------------------------------

### Configure Custom Data Accessor (Shared Instance)

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/data_access.md

Configure EvalEx to use a single, shared instance of your custom data accessor across all expressions. This is useful for global state or performance optimization.

```java
final MyCustomDataAccessor customAccessor = new MyCustomDataAccessor();
ExpressionConfiguration configuration = ExpressionConfiguration.builder()
    .dataAccessorSupplier(() -> customAccessor)
    .build();

Expression expression = new Expression("2.128 + a", configuration);
```

--------------------------------

### Passing Values via Map

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Illustrates passing multiple variable values to an expression using a Map, with automatic data conversion.

```java
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"
```

--------------------------------

### Handle Null Values in Expressions

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/datatypes.md

Shows how to use the IF() function to gracefully handle null values passed as variables, preventing errors and providing a default output. Ensure the variable is correctly passed as null.

```java
Expression expression = new Expression("if(name == null, \"unknown\", name)");

EvaluationValue result = expression
    .with("name", null)
    .evaluate();

System.out.println(result); // prints unknown
```

--------------------------------

### Define a Custom Function with Variable Arguments

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/custom_functions.md

Create a function that accepts a variable number of arguments by setting isVarArg=true on the last parameter. Only one parameter can be a variable argument.

```java
@FunctionParameter(name = "value", isVarArg = true)
public class MaxFunction extends AbstractFunction {
  @Override
  public EvaluationValue evaluate(
      Expression expression, Token functionToken, EvaluationValue... parameterValues) {
    BigDecimal max = null;
    for (EvaluationValue parameter : parameterValues) {
      if (max == null || parameter.getNumberValue().compareTo(max) > 0) {
        max = parameter.getNumberValue();
      }
    }
    return new EvaluationValue(max);
  }
}
```

--------------------------------

### STR_TRIM

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Removes leading and trailing whitespace from a string.

```APIDOC
## STR_TRIM

### Description
Returns the given string with all leading and trailing spaces removed.

### Function Signature
STR_TRIM(string)
```

--------------------------------

### Calculate the sum of numbers or array elements

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

SUM can take multiple numbers or arrays as arguments. If an array is provided, its elements are summed individually before being added to the total.

```evalex
SUM(values)
```

```evalex
SUM(a, b)
```

```evalex
SUM(a, b, values)
```

--------------------------------

### Define a Custom Function with Parameters

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/custom_functions.md

Implement a custom function by extending AbstractFunction and defining parameters using @FunctionParameter annotations. The evaluate method contains the function's logic.

```java
@FunctionParameter(name = "value")
@FunctionParameter(name = "scale")
public class RoundFunction extends AbstractFunction {
  @Override
  public EvaluationValue evaluate(
      Expression expression, Token functionToken, EvaluationValue... parameterValues) {

    EvaluationValue value = parameterValues[0];
    EvaluationValue precision = parameterValues[1];

    return new EvaluationValue(
        value
            .getNumberValue()
            .setScale(
                precision.getNumberValue().intValue(),
                expression.getConfiguration().getMathContext().getRoundingMode()));
  }
}
```

--------------------------------

### DT_TODAY

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Produces a new DATE_TIME that represents the current date, at midnight (00:00). An optional time zone can be specified, e.g. "America/Sao_Paulo", or "GMT-03:00". If no zone ID is specified, the configured zone ID is used.

```APIDOC
## DT_TODAY

### Description
Produces a new _DATE_TIME_ that represents the current date, at midnight (00:00). An optional time zone can be specified, e.g. "America/Sao_Paulo", or "GMT-03:00". If no zone ID is specified, the configured zone ID is used.

### Parameters

#### Path Parameters
- **timezone** (string) - Optional - The time zone to use.

### Response

#### Success Response (DATE_TIME)
- A _DATE_TIME_ object representing the current date at midnight.
```

--------------------------------

### DT_NOW

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Produces a new DATE_TIME that represents the current moment in time.

```APIDOC
## DT_NOW

### Description
Produces a new _DATE_TIME_ that represents the current moment in time.

### Response

#### Success Response (DATE_TIME)
- A _DATE_TIME_ object representing the current moment.
```

--------------------------------

### IF

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Performs a logical test and returns one value if the test is true and another if it's false.

```APIDOC
## IF

The IF function performs a logical test and returns one value if the test is true and another one if it's false.

### Syntax

```
IF(condition, value_if_true, value_if_false)
```

### Parameters

| Name           | Description                                      |
|----------------|--------------------------------------------------|
| condition      | The logical test you want to evaluate.           |
| value_if_true  | The value returned if the logical test is true.  |
| value_if_false | The value returned if the logical test is false. |
```

--------------------------------

### Configure Expression with Custom Operator Dictionary

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/operator_dictionary.md

Specify your custom operator dictionary when building the ExpressionConfiguration. This allows EvalEx to use your defined operators.

```java
ExpressionConfiguration configuration = ExpressionConfiguration.builder()
    .operatorDictionary(new MyOperatorDictionary())
    .build();
```

--------------------------------

### Check String Against Regex Pattern

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

STR_MATCHES verifies if a string conforms to a given regular expression. Ensure correct regex syntax for accurate matching.

```evalex
STR_MATCHES(message, ".*World")
```

```evalex
STR_MATCHES(email, "\\S+@\\S+\\.\\S+")
```

```evalex
STR_MATCHES(zip, "^\\d{5}-\\d{3}$")
```

```evalex
STR_MATCHES(zip, "^\\d{8}$")
```

--------------------------------

### Create DATE_TIME from Milliseconds Since Epoch

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Use DT_DATE_NEW with a millisecond value to create a DATE_TIME object representing time since the Unix epoch. Ensure the input is a positive NUMBER.

```evalex
DT_DATE_NEW(0)
```

```evalex
DT_DATE_NEW(1489227300000)
```

--------------------------------

### Implement FunctionDictionaryIfc Interface

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/function_dictionary.md

This interface defines the contract for custom function dictionaries. You need to implement addFunction and getFunction methods.

```java
public interface FunctionDictionaryIfc {

  /**
   * Allows to add a function to the dictionary. Implementation is optional, if you have a fixed set
   * of functions, this method can throw an exception.
   *
   * @param functionName The function name.
   * @param function The function implementation.
   */
  void addFunction(String functionName, FunctionIfc function);

  /**
   * Check if the dictionary has a function with that name.
   *
   * @param functionName The function name to look for.
   * @return <code>true</code> if a function was found or <code>false</code> if not.
   */
  default boolean hasFunction(String functionName) {
    return getFunction(functionName) != null;
  }

  /**
   * Get the function definition for a function name.
   *
   * @param functionName The name of the function.
   * @return The function definition or <code>null</code> if no function was found.
   */
  FunctionIfc getFunction(String functionName);

```

--------------------------------

### Structure and Array Combination for Complex Data

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Demonstrates accessing nested data within a structure (Map) and arrays (List) to perform calculations.

```java
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
```

--------------------------------

### STR_LENGTH

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Calculates and returns the length of a given string.

```APIDOC
## STR_LENGTH

### Description
Returns the length of the string.

### Function Signature
STR_LENGTH(string)
```

--------------------------------

### Enable Automatic Rounding with Decimal Places

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/rounding.md

Configure EvalEx to automatically round all input variables, intermediate results, and the final output to a specified number of decimal places using the current rounding mode. This ensures consistent formatting and precision across all numerical values.

```java
ExpressionConfiguration configuration = 
    ExpressionConfiguration.builder()
        .decimalPlacesRounding(2)
        .build();

Expression expression = new Expression("2.128 + a", configuration);

// prints 3.26
System.out.println(
    expression
        .with("a", new BigDecimal("1.128"))
        .evaluate()
        .getNumberValue());
```

--------------------------------

### Pass Variables to Expression using withValues() Map

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/parsing_evaluation.md

Set multiple variable values for an expression at once by providing a Map to the withValues() method. This is an alternative to chaining with() and and().

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

Map<String, Double> values = new HashMap<>();
values.put("a", 3.5);
values.put("b", 2.5);

EvaluationValue result = expression.withValues(values).evaluate();

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

--------------------------------

### DT_DATE_NEW(year, month, day [, hour] [, minute] [, second] [, nanos] [, zoneId])

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Creates a new DATE_TIME value using specified date and optional time components. It supports nanosecond precision and time zone specification.

```APIDOC
## DT_DATE_NEW(year, month, day [, hour] [, minute] [, second] [, nanos] [, zoneId])

### Description
The `DT_DATE_NEW` function creates a new `DATE_TIME` value using the specified date components, with optional time, sub-second precision, and time zone. If no time zone is provided, the configured system default is used.

### Syntax
```
DT_DATE_NEW(year, month, day [, hour] [, minute] [, second] [, nanos] [, zoneId])
```

### Parameters
#### Path Parameters
- **year** (number) - Required - The year (e.g. 2025).
- **month** (number) - Required - The month number (1 = January, 12 = December).
- **day** (number) - Required - The day of the month.
- **hour** (number) - Optional - Hour of the day (0–23).
- **minute** (number) - Optional - Minute of the hour (0–59).
- **second** (number) - Optional - Second of the minute (0–59).
- **nanos** (number) - Optional - Nanoseconds (0–999,999,999).
- **zoneId** (string) - Optional - Time zone identifier as a string (e.g. `"Europe/Berlin"`, or `"GMT+02:00"`).

### Examples
These examples illustrate how different combinations of date, time, and zone components produce distinct `DATE_TIME` results.

| Expression                                                                 | Result (example)                           |
|----------------------------------------------------------------------------|--------------------------------------------|
| `DT_DATE_NEW(2025, 6, 15)`                                                 | `2025-06-15T00:00:00Z`*                    |
| `DT_DATE_NEW(2025, 6, 15, 9, 30)`                                          | `2025-06-15T09:30:00Z`*                    |
| `DT_DATE_NEW(2025, 6, 15, "Europe/Berlin")`                                | `2025-06-15T00:00:00+02:00[Europe/Berlin]` |
| `DT_DATE_NEW(2025, 6, 15, 9, 30, 0, 0, "Europe/Berlin")`                   | `2025-06-15T09:30:00+02:00[Europe/Berlin]` |

* Timezone and precision may vary depending on your system configuration.
```

--------------------------------

### FACT

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Calculates the factorial of a base value, which is the product of all positive integers from 1 up to that number.

```APIDOC
## FACT

The FACT function calculates the factorial of a base value, that is, the product of all positive integers from 1 up to that number.

### Syntax

```
FACT(base)
```

### Parameters

| Name | Description                                       |
|------|---------------------------------------------------|
| base | The number for which the factorial is calculated. |

### Examples

Consider the following expressions:

| Expression | Result |
|------------|--------|
| `FACT(5)`  | `120`  |
| `FACT(3)`  | `6`    |
```

--------------------------------

### STR_LOWER

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Converts the given string value to its lower case equivalent.

```APIDOC
## STR_LOWER

### Description
Converts the given value to lower case.

### Function Signature
STR_LOWER(string)
```

--------------------------------

### DT_DATE_NEW(millis)

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns a new DATE_TIME given the number of milliseconds from the Unix epoch (1970-01-01T00:00:00Z).

```APIDOC
## DT_DATE_NEW(millis)

### Description
Returns a new _DATE_TIME_ given the number of milliseconds from the Unix epoch (1970-01-01T00:00:00Z).

### Parameters

#### Path Parameters
- **millis** (number) - Required - The number of milliseconds from the Unix epoch.

### Response

#### Success Response (DATE_TIME)
- A _DATE_TIME_ object representing the specified date and time.
```

--------------------------------

### Basic Expression Evaluation

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Evaluates a simple arithmetic expression with standard operators and functions.

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

EvaluationValue result = expression.evaluate();

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

--------------------------------

### Evaluate Sub-Expressions using ASTNode

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/datatypes.md

Illustrates lazy evaluation by creating a sub-expression as an ASTNode and passing it as a variable. The sub-expression is evaluated only when its value is needed.

```java
Expression expression = new Expression("a*b");

ASTNode subExpression = expression.createExpressionNode("4+3");

EvaluationValue result = expression
    .with("a", 2)
    .and("b", subExpression)
    .evaluate();

System.out.println(result); // prints 14
```

--------------------------------

### DT_DATE_PARSE(value [, zoneId] [, format, ...])

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Converts a string into a DATE_TIME value by attempting to match it against provided or system default formats. An optional time zone can also be specified.

```APIDOC
## DT_DATE_PARSE(value [, zoneId] [, format, ...])

### Description
The `DT_DATE_PARSE` function converts a string into a `DATE_TIME` value by attempting to match it against one or more date-time formats until success. Optionally, a specific time zone may also be provided. If no format is supplied, the system's configured date/time formats will be used. If the zone is omitted or `NULL`, the system’s default zone and locale apply.

### Syntax
```
DT_DATE_PARSE(value [, zoneId] [, format, ...])
```

### Parameters
#### Path Parameters
- **value** (string) - Required - The string to parse into a date-time value.
- **zoneId** (string) - Optional - The time zone identifier (e.g. `"Europe/Berlin"`). If omitted or `NULL`, the system's default zone is used.
- **format** (string) - Optional - One or more format strings to attempt parsing the `value`. If none are provided, system default formats are used.
```

--------------------------------

### EvalEx DataAccessorInterface Definition

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/data_access.md

Implement this interface to create a custom data accessor for EvalEx. It requires methods for retrieving and setting variable values.

```java
public interface DataAccessorIfc {

  /**
   * Retrieves a data value.
   *
   * @param variable The variable name, e.g. a variable or constant name.
   * @return The data value, or <code>null</code> if not found.
   */
  EvaluationValue getData(String variable);

  /**
   * Sets a data value.
   *
   * @param variable The variable name, e.g. a variable or constant name.
   * @param value The value to set.
   */
  void setData(String variable, EvaluationValue value);
}
```

--------------------------------

### DT_DATE_NEW

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns a new DATE_TIME value with the given parameters (year, month, day, etc.). An optional time zone (string) can be specified, e.g. "Europe/Berlin", or "GMT+02:00". If no zone ID is specified, the configured zone ID is used.

```APIDOC
## DT_DATE_NEW

### Description
Returns a new _DATE_TIME_ value with the given parameters (year, month, day, etc.). An optional time zone (string) can be specified, e.g. "Europe/Berlin", or "GMT+02:00". If no zone ID is specified, the configured zone ID is used.

### Parameters

#### Path Parameters
- **year** (number) - Required - The year.
- **month** (number) - Required - The month (1-12).
- **day** (number) - Required - The day of the month.
- **hour** (number) - Optional - The hour (0-23).
- **minute** (number) - Optional - The minute (0-59).
- **second** (number) - Optional - The second (0-59).
- **millisecond** (number) - Optional - The millisecond (0-999).
- **timezone** (string) - Optional - The time zone ID or offset.

### Response

#### Success Response (DATE_TIME)
- A _DATE_TIME_ object representing the specified date and time.
```

--------------------------------

### Boolean evaluation with mixed types

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/datatypes.md

Demonstrates how string and number values are evaluated in boolean expressions. Non-zero numbers are true, and 'true' (case-insensitive) strings are true.

```java
Expression expression = new Expression("stringValue && numberValue")
    .with("stringValue", "True")
    .and("numberValue", 42);
```

--------------------------------

### STR_MATCHES

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Checks if a string matches a given regular expression pattern.

```APIDOC
## STR_MATCHES

### Description
Returns true if the string matches the RegEx pattern.

### Function Signature
STR_MATCHES(string, pattern)
```

--------------------------------

### STR_UPPER

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Converts the given string value to its upper case equivalent.

```APIDOC
## STR_UPPER

### Description
Converts the given value to upper case.

### Function Signature
STR_UPPER(string)
```

--------------------------------

### Create Duration with DT_DURATION_NEW

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Constructs a DURATION value using the specified number of days, with optional time-based components such as hours, minutes, seconds, and nanoseconds.

```evalex
DT_DURATION_NEW(days [, hours] [, minutes] [, seconds] [, millis] [, nanos])
```

--------------------------------

### Calculate Date-Time Difference with EvalEx

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Subtract two Instant objects to calculate the duration between them using EvalEx. Ensure the Instant objects are properly parsed before use.

```java
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)"
```

--------------------------------

### Define a Custom Function with Lazy Parameter Evaluation

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/custom_functions.md

Implement lazy parameter evaluation for functions where parameters should not be evaluated until needed, such as conditional logic in an IF function. Use isLazy=true for such parameters.

```java
@FunctionParameter(name = "condition")
@FunctionParameter(name = "resultIfTrue", isLazy = true)
@FunctionParameter(name = "resultIfFalse", isLazy = true)
public class IfFunction extends AbstractFunction {
  @Override
  public EvaluationValue evaluate(
      Expression expression, Token functionToken, EvaluationValue... parameterValues)
      throws EvaluationException {
    if (parameterValues[0].getBooleanValue()) {
      return expression.evaluateSubtree(parameterValues[1].getExpressionNode());
    } else {
      return expression.evaluateSubtree(parameterValues[2].getExpressionNode());
    }
  }
}
```

--------------------------------

### Split String by Separator

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

STR_SPLIT divides a string into an array of substrings using a specified delimiter. Useful for parsing delimited data.

```evalex
STR_SPLIT(colors, ",")
```

```evalex
STR_SPLIT(path, "/")
```

--------------------------------

### Evaluate Expressions with Undefined Variables (Lenient Mode)

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/datatypes.md

Demonstrates the use of the logical OR operator (||) with an undefined variable in lenient mode. The expression evaluates gracefully, returning the defined variable's value.

```java
Expression expression = new Expression("a || b");

EvaluationValue result = expression
    .with("a", false)
    .evaluate();

System.out.println(result); // returns false
```

--------------------------------

### SIN(value)

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns the sine of an angle in degrees.

```APIDOC
## SIN(value)

### Description
Returns the sine of an angle in degrees.

### Parameters
#### Path Parameters
- **value** (number) - Required - The angle in degrees.

### Response
#### Success Response (number)
- The sine of the angle.
```

--------------------------------

### LOG10 Function

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Calculates the base 10 logarithm of a given number.

```APIDOC
## LOG10(value)

### Description
The LOG10 function returns the base 10 logarithm of a given value.

### Parameters
- **value** (number) - The number for which to calculate the base 10 logarithm.

### Examples
```
LOG10(100) = 2
LOG10(10) = 1
LOG10(2.12345) = 0.3270420392943239
```
```

--------------------------------

### Add Custom Operators to Expression Configuration

Source: https://github.com/ezylang/evalex/blob/main/docs/customization/custom_operators.md

Add custom operators to the expression configuration using withAdditionalOperators. This method accepts Map.Entry objects for operator strings and their corresponding implementations.

```java
import com.ezylang.evalex.Expression;
import com.ezylang.evalex.config.ExpressionConfiguration;
import java.util.Map;

ExpressionConfiguration configuration = 
    ExpressionConfiguration.defaultConfiguration()
        .withAdditionalOperators(
            Map.entry("AND", new InfixAndOperator()),
            Map.entry("OR", new InfixOrOperator()));
    
Expression expression = new Expression("(a > 5 AND x < 10) OR (y < 0)", configuration);
expression.evaluate();
```

--------------------------------

### Round a number to a specified decimal place

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Use ROUND to round a number to a given number of decimal places. The rounding mode is determined by the current configuration.

```evalex
ROUND(num, 1)
```

```evalex
ROUND(num, 2)
```

--------------------------------

### CEILING

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Rounds a given number up to the nearest integer using the CEILING rounding mode.

```APIDOC
## CEILING

The CEILING function rounds a given number up to the nearest integer using the rounding mode CEILING.

> See [Rounding Modes](../concepts/rounding.html#rounding-mode) for more information.

### Syntax

```
CEILING(value)
```

### Parameters

| Name  | Description                                         |
|-------|-----------------------------------------------------|
| value | The number to be rounded up to the nearest integer. |

### Examples

Consider the following expressions:

| Expression     | Result |
|----------------|--------|
| `CEILING(4.3)` | `5`    |
| `CEILING(2.7)` | `-2`   |
```

--------------------------------

### ASIN(value)

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns the arc-sine of a value in degrees.

```APIDOC
## ASIN(value)

### Description
Returns the arc-sine of a value in degrees.

### Parameters
#### Path Parameters
- **value** (number) - Required - The input value for which to calculate the arc-sine.

### Response
#### Success Response (number)
- The arc-sine of the input value in degrees.
```

--------------------------------

### SEC(value)

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns the secant of an angle in degrees.

```APIDOC
## SEC(value)

### Description
Returns the secant of an angle in degrees.

### Parameters
#### Path Parameters
- **value** (number) - Required - The angle in degrees.

### Response
#### Success Response (number)
- The secant of the angle.
```

--------------------------------

### Pass Mixed Data Types as Variables

Source: https://github.com/ezylang/evalex/blob/main/docs/concepts/parsing_evaluation.md

Use a Map with Object values to pass variables of different data types to an expression. EvalEx will attempt to convert them as needed during evaluation.

```java
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"
```

--------------------------------

### ASINH(value)

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns the hyperbolic arc-sine of a value.

```APIDOC
## ASINH(value)

### Description
Returns the hyperbolic arc-sine of a value.

### Parameters
#### Path Parameters
- **value** (number) - Required - The input value for which to calculate the hyperbolic arc-sine.

### Response
#### Success Response (number)
- The hyperbolic arc-sine of the input value.
```

--------------------------------

### STR_SPLIT

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Splits a string into an array of substrings based on a specified separator.

```APIDOC
## STR_SPLIT

### Description
Splits the given string into an array, given a separator.

### Function Signature
STR_SPLIT(string, separator)
```

--------------------------------

### LOG Function

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Calculates the natural logarithm (base e) of a given number.

```APIDOC
## LOG(value)

### Description
The LOG function returns the natural logarithm (base e) of a given value.

### Parameters
- **value** (number) - The number for which to calculate the natural logarithm.

### Examples
```
LOG(2.718) = 1
LOG(1) = 0
LOG(10) = 2.302585092994046
```
```

--------------------------------

### Array Element Access and Calculation

Source: https://github.com/ezylang/evalex/blob/main/docs/index.md

Performs calculations using elements from Java Lists and arrays accessed by index within the expression.

```java
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
```

--------------------------------

### COALESCE

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns the first non-null parameter from a list of arguments, or NULL if all parameters are null.

```APIDOC
## COALESCE

The COALESCE function returns the first non-null parameter from a list of arguments, or `NULL` if all parameters are null.

### Syntax

```
COALESCE(value, [...])
```

### Parameters

| Name       | Description                                              |
|------------|----------------------------------------------------------|
| value, ... | One or more values or arrays from which to be evaluated. |

### Examples

Consider the following variables:

| Name       | Value         |
|------------|---------------|
| `a`        | `null`        |
| `b`        | `"hello"`     |
| `c`        | `42`          |
| `numbers`  | `[null, 8, 5]`|

And the following expressions:

| Expression                | Result    |
|---------------------------|-----------|
| `COALESCE(a, b, c)`       | `"hello"` |
| `COALESCE(a, null, c)`    | `42`      |
| `COALESCE(a, null)`       | `null`    |
| `COALESCE(numbers)`       | `8`       |
| `COALESCE(a, numbers, b)` | `8`       |
```

--------------------------------

### ASINR(value)

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Returns the arc-sine of a value in radians.

```APIDOC
## ASINR(value)

### Description
Returns the arc-sine of a value in radians.

### Parameters
#### Path Parameters
- **value** (number) - Required - The input value for which to calculate the arc-sine.

### Response
#### Success Response (number)
- The arc-sine of the input value in radians.
```

--------------------------------

### STR_ENDS_WITH

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Verifies if a string ends with a specific substring. The comparison is case-sensitive.

```APIDOC
## STR_ENDS_WITH

### Description
Returns true if the string ends with the substring (case-sensitive).

### Function Signature
STR_ENDS_WITH(string, suffix)
```

--------------------------------

### RANDOM Function

Source: https://github.com/ezylang/evalex/blob/main/docs/references/functions.md

Produces a random floating-point number between 0 (inclusive) and 1 (exclusive).

```APIDOC
## RANDOM()

### Description
The RANDOM function produces a random value between 0 and 1.

### Examples
```
RANDOM() = 0.372 (example)
RANDOM() = 0.847 (example)
```
```