Relative functions for DateTimeType #4276

clinique · 2024-06-18T13:00:57Z

As from one scripting language to the other, dealing with Dates is not always so easy, I propose to add these small functions that I use very often while scripting.

Here are the methods added to DateTimeType :

isBefore / isAfter another DateTimeType
sameDay compared to another DateTimeType or a ZonedDateTime
isToday / isTomorrow / isYesterday
toToday, toTomorrow, toYesterday changes day/month/year accordingly, preserving time part of the DateTimeType
isBeforeDate / isAfterDate compared to another DateTimeType or a ZonedDateTime ignoring the time component
isBeforeTime / isAfterTime compared to another DateTimeType or a ZonedDateTime ignoring the date component

Signed-off-by: Gaël L'hopital <[email protected]>

This reverts commit cdfceb1.

…sameDay) to DateTimeType Signed-off-by: Gaël L'hopital <[email protected]>

rkoshak · 2024-06-18T14:45:33Z

Given that some of the languages do not expose and have you work with the raw Java DateTimeType Objects adding these will not make them available to all rules languages.

Some of the stuff like this though has been added to JS Scripting already so I think this PR could be more ambitious if youi wanted to be. There you will find:

time.toZDT(): will convert just about anything to a ZonedDateTime that can be converted to a ZonedDateTime including DateTime Items, Number Items (state is treated as the number of milliseconds from now), Number:Time Items (state is treated as the amount of time from now), ISO8601 Strings, Java DateTime Strings, ISO8601 duration Strings (e.g. PT5M30S, treated as the amount of time from now), a String representing a time of day in 12hr or 24hr format, etc.
myZDT.toToday(): returns the ZDT with today's date, adjusting for DST changeovers as necessary
isBeforeTime(), isBeforeDate(), isBeforeDateTime(), the isAfter equivalents, and isBetweenTimes() isBetweenDates(), and isBetweenDateTimes() which lets you compare ZDTs to see where they fall compared to other ZDTs.
isClose() which is a fuzzy comparison to see if a ZDT is within a certain amount of time of another.

So you can do stuff like this:

// Is it currently between 8AM and 4PM
time.toZDT().isBetweenTimes('8:00AM', `4:00PM`);

// Is now between the times in two Items?
time.toZDT().isBetweenTimes(items.StartTime, items.EndTime); // dates are ignored

// is now between the start time in the Item and three hours after the start time?
time.toZDT().isBetweenTimes(items.StartTime, time.toZDT(items.StartTime).plusHours(3));

// Is the Item's state today? (there are others)
time.toZDT(items.MyDateTime).isBetweenDateTimes('00:00', '23:59:59');

// Move the Item's date time to today
time.toZDT(items.MyDateTime).toToday();

// Is the Item's state tomorrow?
time.toZDT(items.MyDateTime).toLocalDate().equals(time.toZDT('P1DT').toLocalDate());

// Move an Item's time to today
time.toZDT(items.MyDateTime).toToday();

Note that time.toZDT() returns now.

The real magic (IMO) with the JS Scripting approach is that in many of these conversion and comparison functions you can use anything that can be converted by time.toZDT(). It really gets interesting when stuff that usually takes a DateTime can accept anything that can be converted by toZDT(). For example, creating a Timer to go off in five minutes:

actions.ScriptExecution.createTimer(Quantity('5 M'), () => { do something }); // note this doesn't currently work because createTimer doesn't support this sort of conversion

In addition to toToday(), my OHRT also implements a toTomorrow() and toYesterday() method.

In JS you can monkeypatch these into the ZonedDateTime class but I'm pretty sure that's not an option on the Java side of things. But a series of utility functions on the DateTimeType to not only compare but also convert "stuff" to ZonedDateTimes.

There is also a lot of convenience stuff built into jRuby which might prove some inspiration as well.

Once I implemented a lot of the above (originally as part of OHRT and then I was able to get most of them accepted into the openhab-js library) all the complexities of working with DateTimes kind of just disappeared. time.toZDT() normalizes everything and once normalized comparisons and manipulation becomes standardized and simple. And because time.toZDT() treats anything that can be interpreted as a time duration and how much time to add to now, and the main comparison functions can accept one of these durations instead of a ZDT itself, I pretty much never have to do a string of plusSeconds().plusMinutes().plusHours() type stuff nor withHour().withMinute().withSecond() type stuff. The resultant code becomes much clearer and easier to read.

It's just an idea and may be more than you're willing to take on, but I can say this has greatly simplified JS Scripting rules.

jimtng

I think this is a handy addition, especially for rulesdsl. There is currently not a direct equivalent in jruby for what this adds, and when this is added, it will be automatically usable from within jruby without any modifications to the jruby helper library. However it's currently already quite easy to do this in jruby

# dt1 and dt2 are DateTimeType objects, e.g. A_DateTime_Item.state

# Checking for same day
dt1.to_date == dt2.to_date # to_date creates a Date object, stripping off the time data

# to check for today
dt1.to_date == Date.today

# to check for tomorrow
dt1.to_date == Date.today + 1 

# to check for yesterday
dt1.to_date == Date.today - 1

After this PR, JRuby will be able to call:

dt1.today? #jruby automatically translates isToday to ruby method naming convention `today?`

dt1.yesterday?
dt1.tomorrow?
dt1.same_day(dt2) # The Ruby way would be dt1 === dt2

However, in jruby we can add these to ZonedDateTime directly, thus making it universally usable in many more places, including DateTimeType, because in jruby a DateTimeType delegates its methods to its ZonedDateTime value.

@ccutrer wdyt?

jimtng · 2024-06-19T01:47:40Z

bundles/org.openhab.core/src/test/java/org/openhab/core/library/types/DateTimeTypeTest.java

+ assertTrue(new DateTimeType().isToday());
+
+ DateTimeType now = new DateTimeType();
+ DateTimeType tomorrow = new DateTimeType(now.getZonedDateTime().plusHours(24));


Suggested change

DateTimeType tomorrow = new DateTimeType(now.getZonedDateTime().plusHours(24));

DateTimeType tomorrow = new DateTimeType(now.getZonedDateTime().plusDays(1));

I know this is an edge case, but the length of the day isn't always precisely 24h.

I wanted to avoid using the same method than what's used in the object itself.

jimtng · 2024-06-19T01:47:54Z

bundles/org.openhab.core/src/test/java/org/openhab/core/library/types/DateTimeTypeTest.java

+
+ DateTimeType now = new DateTimeType();
+ DateTimeType tomorrow = new DateTimeType(now.getZonedDateTime().plusHours(24));
+ DateTimeType yesterday = new DateTimeType(now.getZonedDateTime().minusHours(24));


Suggested change

DateTimeType yesterday = new DateTimeType(now.getZonedDateTime().minusHours(24));

DateTimeType yesterday = new DateTimeType(now.getZonedDateTime().minusdays(1));

jimtng · 2024-06-19T01:50:04Z

bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/DateTimeType.java

+
+ public boolean sameDay(ZonedDateTime other) {
+ return zonedDateTime.truncatedTo(ChronoUnit.DAYS)
+ .isEqual(other.withZoneSameLocal(zonedDateTime.getZone()).truncatedTo(ChronoUnit.DAYS));


Shouldn't this use witZoneSameInstant ?

jimtng · 2024-06-19T02:00:58Z

bundles/org.openhab.core/src/test/java/org/openhab/core/library/types/DateTimeTypeTest.java

+ @Test
+ public void relativeTest() {
+ DateTimeType dt1 = new DateTimeType("2019-06-12T17:30:00Z");
+ DateTimeType dt2 = new DateTimeType("2019-06-12T00:00:00+0000");


To ensure that this checks for the same instant:

dt1 = "2019-06-13T01:10:00+02"
dt2 = "2019-06-12T23:00:00Z"

Signed-off-by: Gaël L'hopital <[email protected]>

jimtng · 2024-06-29T17:43:31Z

bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/DateTimeType.java

+ return zonedDateTime.truncatedTo(ChronoUnit.DAYS)
+ .isEqual(other.withZoneSameInstant(zonedDateTime.getZone()).truncatedTo(ChronoUnit.DAYS));


Suggested change

return zonedDateTime.truncatedTo(ChronoUnit.DAYS)

.isEqual(other.withZoneSameInstant(zonedDateTime.getZone()).truncatedTo(ChronoUnit.DAYS));

return zonedDateTime.truncatedTo(ChronoUnit.DAYS).isEqual(other.truncatedTo(ChronoUnit.DAYS));

isEqual already compares the instant so it's not necessary to equalise the timezone prior to comparison.

jshell> var d1 = java.time.ZonedDateTime.parse("2024-01-01T00:00:00Z") d1 ==> 2024-01-01T00:00Z jshell> var d2 = java.time.ZonedDateTime.parse("2024-01-01T10:00:00+10:00") d2 ==> 2024-01-01T10:00+10:00 jshell> d1.isEqual(d2) $17 ==> true jshell> d1.getZone() $18 ==> Z jshell> d2.getZone() $19 ==> +10:00

With the truncation to ChronoUnit.DAYS, the comparison is false if they are not moved in the same time zone.

jimtng · 2024-06-29T17:46:21Z

bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/DateTimeType.java

+ public boolean isAfter(DateTimeType other) {
+ return zonedDateTime.isAfter(other.zonedDateTime);
+ }
+


We might also need the versions of isBefore and isAfter that accept a ZonedDateTime

These already exists, reason why I thought it wasn't needed.

Basically it's for convenience, so you can do DateTimeItem.state.isBefore(zdt) instead of DateTimeItem.state.getZonedDateTime().isBefore(zdt), and also for uniformity since you are adding the ability to do
DateTimeItem.state.isBefore(anotherDateTimeItem), but, I'll leave the decision whether to have it to the maintainers.

jimtng · 2024-06-29T17:54:05Z

bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/DateTimeType.java

+ public boolean isBeforeDate(ZonedDateTime other) {
+ return zonedDateTime.truncatedTo(ChronoUnit.DAYS).isBefore(other.truncatedTo(ChronoUnit.DAYS));
+ }
+


I am against the introduction of isBeforeDate, isBeforeTime, etc. because their meaning is ambiguous depending on the time zones of the two objects involved.

Take two zdt objects containing the same date but within two different time zones. They would fail the given comparison.

jshell> var d1 = java.time.ZonedDateTime.parse("2024-01-01T00:00:00-11:00") d1 ==> 2024-01-01T00:00-11:00 jshell> var d2 = java.time.ZonedDateTime.parse("2024-01-01T10:00:00+11:00") d2 ==> 2024-01-01T10:00+11:00 jshell> d2.withZoneSameInstant(d1.getZone()) $22 ==> 2023-12-31T12:00-11:00 jshell> d1.truncatedTo(java.time.temporal.ChronoUnit.DAYS).isBefore(d2.truncatedTo(java.time.temporal.ChronoUnit.DAYS)) $23 ==> false

So do you recommend I should align Timezones before comparison, rename the methods or drop them ?

I would prefer to drop them, but that's just an opinion. Again, I defer to the maintainers to decide.

jimtng · 2024-06-29T18:22:34Z

bundles/org.openhab.core/src/main/java/org/openhab/core/library/types/DateTimeType.java

+ return new DateTimeType(zonedDateTime.withYear(now.getYear()).withMonth(now.getMonthValue())
+ .withDayOfMonth(now.getDayOfMonth()));
+ }
+


This also has the same ambiguity issue related to differences in time zones between what's in zonedDateTime vs the system time zone.

jshell> var d1 = java.time.ZonedDateTime.parse("2024-01-01T00:00:00+11:00") d1 ==> 2024-01-01T00:00+11:00 jshell> var now = java.time.ZonedDateTime.parse("2025-05-01T00:00:00-11:00") now ==> 2025-05-01T00:00-11:00 jshell> d1.withYear(now.getYear()).withMonth(now.getMonthValue()) ...> .withDayOfMonth(now.getDayOfMonth()).withZoneSameInstant(now.getZone()) $38 ==> 2025-04-30T02:00-11:00

Made it relative to zonedDateTime zone's.

clinique added 3 commits June 18, 2024 14:53

Added some convenient methods for DateTimeType

cdfceb1

Signed-off-by: Gaël L'hopital <[email protected]>

Revert "Added some convenient methods for DateTimeType"

5d4ed15

This reverts commit cdfceb1.

Adding some relative functions (isToday, isTomorrow, isYesterday and …

8f5bff9

…sameDay) to DateTimeType Signed-off-by: Gaël L'hopital <[email protected]>

clinique requested a review from a team as a code owner June 18, 2024 13:00

clinique changed the title ~~Date time type relative functions~~ Relative functions for DateTimeType Jun 18, 2024

jimtng reviewed Jun 19, 2024

View reviewed changes

clinique added 2 commits June 19, 2024 10:36

Adding some more functions according Richard's comments

a866b07

Signed-off-by: Gaël L'hopital <[email protected]>

Correcting spotless

8394e4a

Signed-off-by: Gaël L'hopital <[email protected]>

jimtng suggested changes Jun 29, 2024

View reviewed changes

jimtng reviewed Jun 29, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Relative functions for DateTimeType #4276

Relative functions for DateTimeType #4276

clinique commented Jun 18, 2024 •

edited

Loading

rkoshak commented Jun 18, 2024

jimtng left a comment •

edited

Loading

jimtng Jun 19, 2024

clinique Jun 19, 2024

clinique Jun 19, 2024

jimtng Jun 19, 2024

clinique Jun 19, 2024

jimtng Jun 19, 2024

clinique Jun 19, 2024

jimtng Jun 19, 2024 •

edited

Loading

clinique Jun 19, 2024

jimtng Jun 29, 2024

clinique Jul 1, 2024 •

edited

Loading

jimtng Jun 29, 2024

clinique Jun 30, 2024

jimtng Jun 30, 2024

clinique Jul 1, 2024

jimtng Jun 29, 2024

clinique Jun 30, 2024

jimtng Jun 30, 2024

jimtng Jun 29, 2024

clinique Jul 1, 2024

	DateTimeType tomorrow = new DateTimeType(now.getZonedDateTime().plusHours(24));
	DateTimeType tomorrow = new DateTimeType(now.getZonedDateTime().plusDays(1));

	DateTimeType yesterday = new DateTimeType(now.getZonedDateTime().minusHours(24));
	DateTimeType yesterday = new DateTimeType(now.getZonedDateTime().minusdays(1));

		return zonedDateTime.truncatedTo(ChronoUnit.DAYS)
		.isEqual(other.withZoneSameInstant(zonedDateTime.getZone()).truncatedTo(ChronoUnit.DAYS));

Relative functions for DateTimeType #4276

Are you sure you want to change the base?

Relative functions for DateTimeType #4276

Conversation

clinique commented Jun 18, 2024 • edited Loading

rkoshak commented Jun 18, 2024

jimtng left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jimtng Jun 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

clinique Jul 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

clinique commented Jun 18, 2024 •

edited

Loading

jimtng left a comment •

edited

Loading

jimtng Jun 19, 2024 •

edited

Loading

clinique Jul 1, 2024 •

edited

Loading