Working with Date-Times and Duration
Since version 3.1.0 of EvalEx, there are two additional data types DATE_TIME and DURATION.
DATE_TIME values are stored internally as java.time.Instant values, DURATION values are stored as java.time.Duration values.
A DATE_TIME instant is instantaneous point on the time-line, it holds no information about the time zone. Time zones come into play, when converting local dates-times to instants and vice versa. The same instant can have different local date-time values, depending on the destination time zone.
Functions and operations that require a time zone use either the configured time zone or a zone-id parameter. Time zones are specified using java.time.ZoneId.
The precision of a DATE_TIME is up to nanoseconds.
A DURATION is a certain amount of time, like e.g. “3 hours, 15 minutes and 6 seconds”. The textual representation of a DURATION value is the IS-8601 format, e.g. “P2DT3H4M” means 2 days, 3 hours and 4 minutes The smallest amount of a duration is 1 nanosecond.
Arithmetic operations with DATE_TIME and DURATION.
The infix plus and minus operators can be used to do calculations with DATE_TIME and DURATION values. The outcome of the operation depends on the operator types:
Addition
| Left Operand | Right Operand | Result |
|---|---|---|
| DATE_TIME | DURATION | A new DATE_TIME where the duration is added to the date. |
| DURATION | DURATION | A new duration, which is the sum of both durations. |
| DATE_TIME | NUMBER | A new DATE_TIME with the amount of a duration in milliseconds added. |
All other combinations of DATE_TIME and DURATION with other types will do a string concatenation.
Example: Adding a duration to a date-time:
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)"
Subtraction
| Left Operand | Right Operand | Result |
|---|---|---|
| DATE_TIME | DATE_TIME | A duration which reflects the difference between the two date-times. |
| DATE_TIME | DURATION | A new DATE_TIME where the duration is subtracted from the date. |
| DURATION | DURATION | A new duration, which is the difference of both durations. |
| DATE_TIME | NUMBER | A new DATE_TIME with the amount of a duration in milliseconds subtracted. |
All other combinations of DATE_TIME and DURATION with other types will throw an EvaluationException.
Example: Find out the duration between two date-times:
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)"
The string representation of a duration is here in ISO-8601 format, meaning 12 hours, 4 minutes and 30 seconds.
Passing other Date-Time Types as variables
Instead of passing java.time.Instant values for DATE_TIME values, you can pass also the following Java data types. They will be converted automatically to java.time.Instant values.
| Input type | Conversion note |
|---|---|
| ZonedDateTime | Directly converted. |
| OffsetDateTime | Directly converted. |
| LocalDate | Converted using the configured time zone. Defaults to the systems time zone. The time is set to beginning of the day. |
| LocalDateTime | Converted using the configured time zone. Defaults to the systems time zone. |
| Date | Directly converted. |
| Calendar | Directly converted. |
New Date-Time Functions
In addition to the possibility to add and subtract with DATE_TIME and DURATION values, there are also several new functions to work with date-times. Most of them allow to create, parse and format date-time and duration values.
See Chapter Date Time Functions
Configuration Changes
There are two new configuration parameters for date-time handling.
- Date time formatters: The formatters to use when parsing or formatting date-time values.
- Zone id: The time zone id. By default, the system default zone ID is used.
See Chapter configuration
New Constants
There are also some new constants for common formatter patterns.
See Chapter Standard Constants