Add a ZonedDateTime type

[cromefire]

Add a type that aligns with the normal calendar and combines TimeZone information with a date.

[cromefire]

@dkhalanskyjb

The same argument can be made for date + time.

It can't because 1) waiting for an hour at 23:31 will start the next day 2) the set of valid times depends on the date.

1. It's just a PITA to have APIs using Pair.
2. How would you e.g. fix the offset (toOffsetDateTime()) or get an Instant from that pair?
3. How would you handle parsing and serialization?

Not true.

Well for everything else, just use OffsetDateTime.

[dkhalanskyjb]

It's just a PITA to have APIs using Pair.

True. However, there's a difference between introducing an OffsetDateTime or a ZonedDateTime with their whole semantics and behavior, and adding a small wrapper that's almost like a pair, but with a couple of helper functions. Therefore, we need to decide which path to take. A small wrapper seems like a good approach, but if there are other use cases for ZonedDateTime, we may just introduce it instead.

How would you e.g. fix the offset (toOffsetDateTime()) or get an Instant from that pair?

I'm not sure what "fixing an offset" means, but to get an Instant from a Pair<LocalDateTime, UtcOffset>, you can do the following:

    fun ldtAndOffsetToInstant(pair: Pair<LocalDateTime, UtcOffset>): Instant {
        val (ldt, offset) = pair
        return ldt.toInstant(offset)
    }

How would you handle parsing and serialization?

At the moment, we don't provide means to handle this.

[cromefire]

True. However, there's a difference between introducing an OffsetDateTime or a ZonedDateTime with their whole semantics and behavior, and adding a small wrapper that's almost like a pair, but with a couple of helper functions.

The helper functions definite the semantics of the class, so I don't see a difference here.

I'm not sure what "fixing an offset" means

Convert from a TimeZone (dynamic-ish offset) to a fixed offset.

At the moment, we don't provide means to handle this.

I'd define this as a goal though.

[dkhalanskyjb]

The helper functions definite the semantics of the class, so I don't see a difference here.

The difference is that there are fundamental classes that define the problem area—we've chosen Instant, LocalDateTime, TimeZone, etc. for this—and then there are just helper classes. One has to learn to use the fundamental classes, as they represent something that one has to know to use the library, but helper classes are just there for grouping functionality together.

Convert from a TimeZone (dynamic-ish offset) to a fixed offset.

Timezones have different offsets at different times. Daylight saving time is an example.

I'd define this as a goal though.

Sure, we are planning an API for parsing and formatting, I said this several times in the other thread.

[wkornewald]

Sorry, noticed too late, moving discussion here.

Do you have an example? My impression is that it adapts the Instant to ensure that the LocalDateTime+TimeZone is stable.

Yep, sure.

ZonedDateTime.of(LocalDateTime.parse("2021-03-27T02:16:20"), ZoneId.of("Europe/Berlin")).plusDays(1).plusDays(1).toString() ==
"2021-03-28T03:16:20+02:00[Europe/Berlin]"

Because an intermediate computation (plusDays(1)) fell into the gap, all future results get shifted by an hour in the LocalDateTime.

Wow. This looks more like a bug. Try going from summer to winter time:

val d2 = ZonedDateTime.parse("2021-10-31T02:16:20+02:00[Europe/Berlin]")
// => 2021-10-31T02:16:20+02:00[Europe/Berlin]

d2.plusDays(1)
// => 2021-11-01T02:16:20+01:00[Europe/Berlin]

d2.plusHours(24)
// => 2021-11-01T01:16:20+01:00[Europe/Berlin]

ZonedDateTime.ofInstant(d2.toInstant().plus(1, ChronoUnit.DAYS), ZoneId.of("Europe/Berlin"))
// => 2021-11-01T01:16:20+01:00[Europe/Berlin]

it's actually LocalDateTime+Offset or LocalDateTime+ZoneId depending on what input you provide

Not the case. I've shown before that, on deserialization, the LocalDateTime part gets changed to preserve the Instant, see above. Now I've shown also that the gap gets corrected.

Your first example just happened to auto-correct the invalid offset that is disallowed by the zone - and this is documented as an edge case. It just recomputed to a different offset, but that doesn't mean it stores an Instant.

The same argument can be made for date + time.

It can't because 1) waiting for an hour at 23:31 will start the next day 2) the set of valid times depends on the date.

You're already suggesting to use Pair<LocalDateTime, TimeZone> then my counter-question is why not have Triple<Date, Time, TimeZone>? You could even define extension functions like plusDays over Triple, so isn't this "just as good"?

No Triple/Pair is not just as good. Apart from real types being more convenient they also improve the type safety and allow type hierarchies. A ZonedDateType could be a sealed class with child classes OffsetDateTime and RegionDateTime for cases where you have to ensure via types that only the expected format is used. You can't do that with Pair/Triple (which also just from a readability point of view is horrible) and since Pair/Triple use generics you can quickly run into ugly problems because of type erasure.

should stay unmodified in LocalDateTime and auto-correct the underlying Instant because people in that country keep going to work at the same LocalDateTime and even airports might adapt their active hours (some disallow flights after midnight for example). That's why Java's ZonedDateTime is not Instant+TimeZone, but LocalDateTime+TimeZone.

Your argument: "A is good, and ZonedDateTime is good, therefore ZonedDateTime is A", whereas my argument is "ZonedDateTime is not A, A is good, therefore ZonedDateTime is not good". It's easy to observe that ZonedDateTime is not A.

No my argument is: Humans often think in terms of LocalDateTime+TimeZone, so we need a solution for that. And ideally it also has a bug-free plusDays() implementation that takes DST and zone changes into account. 😄

It's pretty reliable at representing LocalDateTime and that's the intended use-case.

Not true.

Actually it is true, but you seem to have found a bug (or kind-of bad design). Let's imagine there was no bug. 😅

[cromefire]

The helper functions definite the semantics of the class, so I don't see a difference here.

The difference is that there are fundamental classes that define the problem area—we've chosen Instant, LocalDateTime, TimeZone, etc. for this—and then there are just helper classes. One has to learn to use the fundamental classes, as they represent something that one has to know to use the library, but helper classes are just there for grouping functionality together.

Well I guess in that would make it something in between. It's not a primitive/fundamental type, but it'll probably be a bit more than just a helper class I guess? Depends on if you still classify it as such. I've never argued for it to be a fundamentally brand new type, most functions would probably just be one liner and the biggest benefits would be documentation and clearer (and easier) code. Most things can already be done today if you where willing to handle both separately, but with the compound type it'll be a lot easier.

Convert from a TimeZone (dynamic-ish offset) to a fixed offset.

Timezones have different offsets at different times. Daylight saving time is an example.

Yes, that's why you can only convert it to an offset for a single point of time and even that may not be unambiguous.

I'd define this as a goal though.

Sure, we are planning an API for parsing and formatting, I said this several times in the other thread.

Yeah I'd probably add some default support though, if there is a common format being used for this.

[dkhalanskyjb]

Wow. This looks more like a bug.

This behavior is documented fairly well, and, I think, it's the only consistent way to implement this given the constraints of ZonedDateTime.

It just recomputed to a different offset, but that doesn't mean it stores an Instant.

LocalDateTime + UtcOffset uniquely identify an Instant, so it could as well just store an Instant.

You could even define extension functions like plusDays over Triple, so isn't this "just as good"?

Nope, it's not just as good: LocalDate and LocalTime are tightly connected and are constantly changed together. Pair represents disjoint data, where one component does not rely on the other.

Your first example just happened to auto-correct the invalid offset that is disallowed by the zone - and this is documented as an edge case.

It's only an edge case if you consider it an edge case if two machines have different timezone databases. If you attempt to send a ZonedDateTime to another machine, which considers it invalid, it will disregard the LocalDateTime part, not the Instant part. This should be a good giveaway of where the priorities lie for ZonedDateTime.

No my argument is: Humans often think in terms of LocalDateTime+TimeZone, so we need a solution for that.

Sure. Do we agree that ZonedDateTime, at least as defined in Java, is not that solution?

Actually it is true, but you seem to have found a bug (or kind-of bad design). Let's imagine there was no bug.

Imagining it requires implementing a whole new data structure, unfortunately, as this behavior is inherent in ZonedDateTime. Here we're discussing ZonedDateTime, however.

Yes, that's why you can only convert it to an offset for a single point of time and even that may not be unambiguous.

For each moment in time, there's an unambiguous offset for each TimeZone, unless the rules change. Ambiguity can happen with LocalDateTime + TimeZone.

[cromefire]

LocalDateTime + UtcOffset

Well yes for that case, the same is not true for LocalDateTime + ZoneId. What you are describing is OffsetDateTime, which indeed can(/should?) be stored as Instant with an offset.

Sure. Do we agree that ZonedDateTime, at least as defined in Java, is not that solution?

It was pretty fine last time I used it. We can probably get something more lightweight going, but the basic principles seemed fine.

Ambiguity can happen with LocalDateTime + TimeZone.

Yes that is the point. Because it should not represent a moment in time.

[dkhalanskyjb]

Well yes for that case, the same is not true for LocalDateTime + ZoneId.

ZonedDateTime also stores ZoneOffset.

It was pretty fine last time I used it.

It could be fine if you used it as Instant + TimeZone, which it is.

Yes that is the point. Because it should not represent a moment in time.

I was answering these words:

you can only convert it to an offset for a single point of time and even that may not be unambiguous.

Nope, for a single point in time (that is, Instant), the offset is unambiguous.

[wkornewald]

Wow. This looks more like a bug.

This behavior is documented fairly well, and, I think, it's the only consistent way to implement this given the constraints of ZonedDateTime.

It just recomputed to a different offset, but that doesn't mean it stores an Instant.

LocalDateTime + UtcOffset uniquely identify an Instant, so it could as well just store an Instant.

Not quite.

Future zone changes have different results depending on whether you pick LocalDateTime or Instant because the meaning of a future ZonedDateTime changes. In the LocalDateTime case the local time is stable and the serialization is stable (because you exactly reproduce the formatted string). In the Instant case the UTC time is stable, but the serialization is unstable and even incorrect from a typical end-user point of view because the formatted time suddenly changes, but users want only the offset to change.

Human-friendly calendar-like computations (plusDays etc.) must be based on the LocalDateTime.

Though, maybe java.time.ZonedDateTime doesn't treat all of this as well as I'd like to have, so maybe we should shift the discussion a little bit.

You could even define extension functions like plusDays over Triple, so isn't this "just as good"?

Nope, it's not just as good: LocalDate and LocalTime are tightly connected and are constantly changed together. Pair represents disjoint data, where one component does not rely on the other.

When adding durations to LocalDateTime+TimeZone you also can't treat them as disjoint data. The dependency stems from what you want to do with the data.

Your first example just happened to auto-correct the invalid offset that is disallowed by the zone - and this is documented as an edge case.

It's only an edge case if you consider it an edge case if two machines have different timezone databases. If you attempt to send a ZonedDateTime to another machine, which considers it invalid, it will disregard the LocalDateTime part, not the Instant part. This should be a good giveaway of where the priorities lie for ZonedDateTime.

I'd consider your example a much more extreme edge case than the actual intention of LocalDateTime+TimeZone: Correcting zone changes for events in the future. That's a much more likely issue.

No my argument is: Humans often think in terms of LocalDateTime+TimeZone, so we need a solution for that.

Sure. Do we agree that ZonedDateTime, at least as defined in Java, is not that solution?

Yes we surely agree that Java's implementation is not ideal. In my mind the ZonedDateTime should better match how humans think.

Actually it is true, but you seem to have found a bug (or kind-of bad design). Let's imagine there was no bug.

Imagining it requires implementing a whole new data structure, unfortunately, as this behavior is inherent in ZonedDateTime. Here we're discussing ZonedDateTime, however.

For zoneddatetime + duration arithmetic and compareTo/equals we could need some custom logic. And then I'd rather discuss how things should be instead of java.time.

[cromefire]

ZonedDateTime should better match how humans think

That is the central point I think. This type should be used for user facing stuff and therefore work how a normal person would expect it to.

[wkornewald]

Just FYI, in the JavaScript ecosystem the proposed Temporal API also could provide some interesting insights: https://tc39.es/proposal-temporal/docs/ambiguity.html

[wkornewald]

I've created an initial PR #175 with a sketch of what the API could look like.

@dkhalanskyjb @cromefire Would be nice to have your feedback and possibly counter-PRs or PRs on top of my PR. :)