LocalDateTime + TimeZone

[dkhalanskyjb]

We received several requests for a combination of LocalDateTime and TimeZone. This is a proposal that is up for discussion and may end up being implemented.

Use cases

• Storing user-visible data. For example, let's say that one day, at 8:13, a user wakes up in Moscow and adds an entry that they took a pill. Then, a month later, they fly to New York. Opening their diary, they expect that entry to be at 8:13, not at whatever representation that moment had in New York. However, the specific moment when they took a pill may still be important.
  • Let's say the device used to record the entry had an outdated time zone database. In this case, the user probably manually set the device to have the displayed clock be the same as the wall clock, so the hardware clock is, say, an hour off the mark. Then, 8:13 is still the true time when an entry was made, and if we store that entry as an Instant, after the time zone database does update, the reading may become incorrect.
• Scheduling future events. Let's say that there's a conference on July 20th, 2023, in New York, and the keynote is at 10:00.
  • Imagine that suddenly the USA decides not to do the daylight saving time switch in 2023. The instant that used to be 10:00 will be represented as 09:00 in New York now. However, the actual schedule still says that the keynote is at 10:00. Clearly, Instant is a wrong representation here and LocalDateTime is what we should be storing. The same goes for scheduling plane flights, school lessons, or anything else that's user-visible.

Lots of thanks to @wkornewald for raising them!

ZonedDateTime

A data structure that is called ZonedDateTime in Java is typically used to represent these. However, it's actually unsuitable for that. Previous discussions: #90, #163.

Internal model

ZonedDateTime a combination of Instant + TimeZone, despite it being possible to create it from LocalDateTime and TimeZone. In most cases, this is the same as LocalDateTime + TimeZone, because there's typically exactly one local date-time corresponding to an instant, except in two cases: when clocks are set forward and the times in-between don't exist (a gap occurs), and when clocks are set backward and the times repeat (an overlap occurs). For further information, see https://stackoverflow.com/tags/dst/info.

Creation

There are several ways to create a ZonedDateTime

• Normal: if the combination of LocalDateTime and TimeZone is in a gap, LocalDateTime will be adjusted (moved forward) to be correct, and if there's an overlap, it's possible to configure which of the two instants corresponding to this combination is correct, but by default, the earlier one is used.
• Strict: requires passing the UtcOffset along with LocalDateTime and TimeZone and validates that the combination is correct and unambiguous, throwing otherwise.
• Constructing from Instant and TimeZone, or parsing:

java.time.ZonedDateTime.parse("2021-12-15T10:38:25.793402647+10:00[Europe/Moscow]").toString() ==
    "2021-12-15T03:38:25.793402647+03:00[Europe/Moscow]"

Evidently, ZonedDateTime attempts to construct an Instant in any case, sometimes guessing it from the passed LocalDateTime, and does not treat LocalDateTime as the source of truth.

Updates

It's possible to add date-time units (plusYears, plusHours) or try to set specific fields (withHour). Adding time-based units works on the underlying Instant directly, whereas adding units or setting fields modifies LocalDateTime and creates a new ZonedDateTime based on that.

This leads to addition being non-associative:

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.

Actual prior art

Didn't manage to find any.

Proposal

A new data structure

An outline of the class, conveying the general idea, without any of the niceties and with subpar naming:

class DateTimeInZone(
  /**
  * The ground truth.
  */
  val nonAdjustedDateTime: LocalDateTime,
  /**
  * The implied time zone of [nonAdjustedDateTime]
  */
  val timeZone: TimeZone,
  /**
  * The mechanism of adjusting a [LocalDateTime] in cases of time gaps and overlaps.
  * By default, it may have the same behavior as `ZonedDateTime`:
  * on gap, move the time forward, on overlap, choose the earlier offset.
  */
  val resolver: LocalDateTimeResolver = LocalDateTimeResolver.DEFAULT
) {
  /**
  * The corrected value of [LocalDateTime].
  */
  val localDateTime: LocalDateTime
    get() = resolver.adjustLocalDateTime(nonAdjustedDateTime, timeZone)

  val instant: Instant
    get() = localDateTime.toInstant(nonAdjustedDateTime, timeZone, resolver)

  /**
  * Add the given amount of [unit] to this [DateTimeInZone].
  * Only date-based units are supported.
  * The operation will be performed directly on [nonAdjustedDateTime], ignoring the time zone.
  */
  fun plus(value: Int, unit: DateTimeUnit.DateBased): DateTimeInZone =
      nonAdjustedDateTime
          .toInstant(TimeZone.UTC)
          .plus(value, unit)
          .toLocalDateTime(TimeZone.UTC)
          .let { newDateTime ->
            DateTimeInZone(newDateTime,
                timeZone,
                resolver,
            )
          }
}

Properties:

• Even if intermediate results of arithmetic operations (or the initial value itself) happen to fall into a time gap, the result of a series of operations will be the same as with plain LocalDateTime arithmetic unless the final result happens to be in a time gap as well.
  • This makes the plus operation associative, which corresponds to the everyday understanding: waiting for a day and then waiting for a day is the same as waiting for two days.
• DateTimeInZone(localDateTime, timeZone).plus(n, unit).localDateTime == ZonedDateTime(localDateTime, timeZone).plus(n, unit).toLocalDateTime() for all valid localDateTime + timeZone combinations.

Modifications to existing data structures

Internally, Instant.plus on date-based units works by converting to a ZonedDateTime. Instead, we can move this functionality to DateTimeInZone. This would make DateTimeInZone the way to do date-based arithmetic operations, and Instant.plus accepting DateTimeUnit.DateBased would just be a convenience. Potentially, we can even deprecate Instant.plus(DateTimeUnit.DateBased).

Unclear details

• When the local date-time is in a time overlap, the corresponding Instant value is ambiguous. ZonedDateTime stores an Instant, so the offset is always known. However, DateTimeInZone data structure considers the local date-time and the time zone to be ground truth, and the offset may be out of sync with them, and so, can only be treated as a recommendation, not as part of the knowledge about the date-time. However, it would still be nice to be able to represent Instant values as DateTimeInZone unambiguously when we know them for sure.
  • Potential solution: allow the resolver to be parameterized with the offset that will be preferred in case of ambiguity.
• Resolvers would need to be serializable in order for this data structure to be serializable.
  • Or maybe we can crash when attempting to serialize a non-predefined resolvers and it's enough to support serialization of just a limited set of resolvers.
• It's unclear whether there's demand for adding time-based units to such a thing, we haven't received such requests yet. If so, by the semantics of time-based units, we would need to resolve the corresponding Instant, add the unit, and then convert back to DateTimeInZone.
  • It looks like associativity doesn't break anyway, great news.
  • This way, both Instant and DateTimeInZone would allow adding arbitrary DateTimeUnits, with Instant being time-centric and DateTimeInZone being date-centric, with only subtle differences between them. Maybe it would be a good idea to deprecate Instant.plus(DateTimeUnit.DateBased) altogether and only allow arbitrary DateTimeUnits to be added to DateTimeInZone?

[dkhalanskyjb]

What do you think would be a good name for this data structure, instead of DateTimeInZone? We're looking for something succinct, but also for something that doesn't lead to wrong mental models. For example, we wouldn't want to call this a ZonedDateTime, because this name is already used by something that behaves differently in important ways.

[wkornewald]

How will we then represent summer vs. winter time if a LocalDateTime + ZoneId alone is ambiguous?

[dkhalanskyjb]

see the first entry in the "Unclear details" section

Supposedly, as part of the resolver.

[joffrey-bion]

First, this discussion is slightly orthogonal to the name discussion that this thread should represent, but since it informs the decision about whether or not ZonedDateTime is an acceptable name, I'll carry on here. If you feel we should move it, we can move our comments - just let me know.

We can't support this format with the proposed data structure, because the offset there is not directly a part of it

@dkhalanskyjb I don't quite understand why you consider parsing 1996-02-04T23:59:59+01:00[Europe/Berlin] to be impossible if we don't store/remember the given offset. This data is basically local datetime + offset + timezone. Now, from this point, we have all we need to create a DateTimeInZone instance (let's use this name for clarity). The fact that we remember that offset or not is determined by which type we store the data into. We can parse this as an Instant if we care about the exact moment in time, or we can parse this as a DateTimeInZone if we care about a local date that match the provided instant in the given timezone.

More precisely, I believe this could be parsed this way: resolve 1996-02-04T23:59:59+01:00 (ignoring time zone) to an Instant, then use the provided time zone [Europe/Berlin] to determine what the local date in that time zone is (currently, with its current rules), and remember just the resulting local datetime + zone as a DateTimeInZone. Of course we lose the offset information, but I believe it cannot even be used to determine the DST ambiguity resolver because the offset could be completely unrelated to the timezone, like using +08:00 in Europe/Berlin, and technically say nothing about handling DST.

Do you refuse to do that because you consider this to be too implicit and possibly error prone to the unexpecting junior dev? We could consider that this requires an explicit multi-step parsing, but this kind of format doesn't seem reasonable to parse as "just an Instant", and we don't have a representation for Instant+timezone (and I believe the idea is that we don't want to). This is why I think the parsing I described above would be a reasonable expectation to have.

I guess accepting this is a bit equivalent to accepting creating a DateTimeInZone from an Instant + timezone. I don't know if we want this or not, but it doesn't sound too unreasonable.

[dkhalanskyjb]

Yes, please let's move the comments if there are further questions regarding this.

don't quite understand why you consider parsing 1996-02-04T23:59:59+01:00[Europe/Berlin] to be impossible

I don't! Parsing this would be just juggling some characters in strings and then calling something like

fun DateTimeInZone(localDateTime: LocalDateTime, timeZone: TimeZone, preferredOffset: UtcOffset) =
  DateTimeInZone(localDateTime, timeZone, LocalDateTimeResolver.withPreferredOffset(preferredOffset))

The point is, the string representation should reflect the object's contents. The proposed data structure typically doesn't store an offset, and when it does, it's a "recommended", "preferred" offset, not something that deserves the prominent role it has in ZonedDateTime. On the other hand, the proposed data structure stores a resolver, which is important to the behavior of the object. There's no mention of the resolver in 1996-02-04T23:59:59+01:00[Europe/Berlin], so such a string doesn't have all the information we need.

[OliverO2]

I concur with @joffrey-bion and others that a Local prefix is misleading as there is no information about locality.

I'd prefer to accept a deprecation cycle, emancipate from legacy naming, and wipe the slate clean like the TC39 suggestion does, so

• name this proposal's class ZonedDateTime, and
• rename LocalDateTime to PlainDateTime, LocalDate to PlainDate and LocalTime to PlainTime.

[dkhalanskyjb]

Which operations would you expect this data structure to have and how would you use them? Examples of possible operations:

• Add a given number of months,
• Add a given number of hours,
• Set the time of the day to 14:00,
• Find the difference in days between two instances,
• Set the day to be the last day in the given month, preserving the time of the day.

[ilya-g]

Note that finding the difference between two instances in months may give different result depending on the time zone in which operation is performed. And when we have two instances, they can have two different time zones, so it's unclear which one to use for the operation. ZonedDateTime uses the time zone of the first operand in this case, but this looks rather arbitrary.

[alghe-global]

Definitely the possibility to convert to epochTimeMilliseconds()

[dkhalanskyjb]

@alghe-global, this is supported by Instant.

[ilya-g]

Considering the serializability and persistent storage of the proposed data structure, it might be not a good idea to store a time zone reference for future events for a long time. The reason is that if a future event is scheduled to a local time in some geographic location, it's not guaranteed that the time zone identifier (not the rules of the time zone) of that location won't change later due to further administrative decisions.

Usually no one cares about this aspect, but providing such a shortcut for representing and storing future events could make one care even less.

[joffrey-bion]

What alternative would you suggest in that case? Storing the location separately and lazily resolving the time zone?

[joffrey-bion]

I'd be interested in knowing the relative probability of a given location changing timezones, compared to a timezone changing its rules. Maybe this case is enough of an edge case to be ignored during the design 🤷

[ilya-g]

Usually the regions that observe the same DST transitions since 1970 have the same TZ identifiers. If these regions are located in different countries, there's always a chance for example that they decide to abolish DST each on a different schedule. This would require splitting that same TZ into several ones. And consequently it would mean that some locations in these regions would change their TZ identifiers.

[wkornewald]

While this is indeed an issue and it would be nice to provide a solution, this is quite an edge case compared to normal DST/offset changes. Most calendar apps will probably leave this problem to the user. We might use location information to (semi-)auto-correct the events, but maybe we're going too far now. As the simplest solution, a calendar app could check all its events for ambiguity and suggest to the user that some future events don't look right anymore due to time zone changes and the user could manually check. I.e. we don't need to provide the full solution. Just making it possible to detect these cases could be enough and the location-based auto-correct could be implemented on top of that detection. Usually we'll want to update the persistent representation and not just the in-memory time.

[rocketraman]

Consider another possible useful resolver (naming TBD of course) -- maybe even the default one:

LocalDateTimeResolver.UNAMBIGUOUS

The purpose of this resolver would be to not allow a time specification that falls into an overlap. Rather than shifting into the first or second hour in this case, it would throw or otherwise error.

For the purposes of scheduling human activity this is pretty useful, as no one sane schedules anything in overlap hours -- there is no easy way for a person to know which hour is referred to.

[OliverO2]

For the use cases provided, we don't trust timezone databases

If – at creation time – we don't trust the time zone data on the device where a zoned datetime is created, what would be our point of reference? Just the name of the time zone? What if that is outdated ("Asia/Calcutta" -> "Asia/Kolkata")? If a zoned datetime travels from clients to servers and beyond, would every system interpret it according to its own rules?

If creation-time accuracy is paramount on (unreliable) end-user devices, an application's trusted server could provide authoritative time zone data. The zoned date time could provide an API to use such trusted information instead of the system's default data.

One could construct a new DateTimeInZone with the appropriate resolver.

Yes, though that could become pretty inconvenient and error-prone at scale.

[dkhalanskyjb]

What if that is outdated ("Asia/Calcutta" -> "Asia/Kolkata")?

Yes, this can happen, but are there any realistic ways of dealing with it? The existing systems use the IANA timezone database identifiers. See #237 (comment) I think, in this case, perfect is the enemy of good.

In any case, this is not really an argument against not trusting timezone databases, but an argument for it. Even if the data is internally consistent, it's not always consistent with the real world, which is what matters here.

If creation-time accuracy is paramount on (unreliable) end-user devices, an application's trusted server could provide authoritative time zone data.

You're right in that this helps to make the whole multi-device system internally consistent, but the problem goes further than that. Not only do we need consistency between devices, but we also need consistency on the same device at different times. See the motivating example about the conference: if one device thinks that the conference is at 2020-05-26T09:00+08:00, but then the timezone rules change and, on 2020-05-26, the UTC offset for that timezone becomes +07:30, the conference is still at 09:00. So, the offset was deemed correct, but as the time went on, the offset became invalidated by the external factors. The LocalDateTime stayed.

If a zoned datetime travels from clients to servers and beyond, would every system interpret it according to its own rules?

Yes, and that's the point: to preserve LocalDateTime if at all possible, while still interpreting it in a given timezone.

[OliverO2]

What if that is outdated ("Asia/Calcutta" -> "Asia/Kolkata")?

Yes, this can happen, but are there any realistic ways of dealing with it? The existing systems use the IANA timezone database identifiers.

In tzdata, former/alternative timezone names are linked to their most recent canonical form ("Phnom_Penh" -> "Bangkok"). So even with an outdated identifier we can still find the latest representation. What we need to rely on at least is, that the creating system provides an identifier that was correct at one point in time.

Even if the data is internally consistent, it's not always consistent with the real world, which is what matters here.

It's not about the creation-time data being internally consistent. It is about "what information did the user rely on" at creation time, in other words, what was presented to them by the device which created the zoned datetime.

Let's consider the following scenario:

• At booking time, a conference is scheduled in Paris at 2023-05-16T09:00+02:00.
• A flight is booked, to depart in Madrid at 2023-05-16T06:00+02:00, to arrive in Paris at 2023-05-16T08:00+02:00.
• France decides to change from UTC+02:00 to UTC+01:00, with the conference remaining at 09:00 Paris local time.
• The flight would now arrive in Paris at 2023-05-16T09:00+01:00, which would be too late for the conference now also at 2023-05-16T09:00+01:00.

Now compare the cases of a zoned datetime with (a) and without (b) additional creation-time utcOffset information when new timezone data arrives:

• (a) The calendar application can detect that the creation-time utcOffset (+02) is inconsistent with new timezone data (+01). It could then inform the user to check for possible conflicts.
• (b) Without a creation-time utcOffset, the calendar application would have no way to flag possible inconsistencies.

Note that in both cases, the zoned datetime will always be interpreted according to the current timezone data's UTC offset. The utcOffset property in the zoned datetime would just record the state at creation time in order to detect inconsistencies.

If the above booking was done on a device with outdated time zone data, displaying an inaccurate schedule, the result would be the same: As soon as new time zone data arrives (or another system detects it), the application could alert the user, discrepancies would not go unnoticed.

If such a creation-time utcOffset were also used to disambiguate times in the DST overlap period, we might not even need to store a (creation-time) resolver and just employ a use-site resolver.

[dkhalanskyjb]

In the scenario you provided, the time of arrival should be encoded as an Instant, because it's a local-time-independent moment in time.

The calendar application can detect that the creation-time utcOffset (+02) is inconsistent with new timezone data (+01). It could then inform the user to check for possible conflicts.

That's a separate question entirely. You're talking about constructing a DateTimeInZone when an offset is known and should be either checked or preferred, depending on the strictness that you need. Yes, I can't think of a reason not to provide such functionality.

What we need to rely on at least is, that the creating system provides an identifier that was correct at one point in time.

I think this discussion is better suited for #237 (comment)

[OliverO2]

In the scenario you provided, the time of arrival should be encoded as an Instant, because it's a local-time-independent moment in time.

Yes, while I did not explicitly mention that, I agree. I was focusing on the conference time (a zoned datetime according to this proposal).

That's a separate question entirely.

I should probably have been more explicit initially, at least that was on my mind from the start.

when an offset is known

The assumption is: If we need to have a correct zone identifier from tzdata, we can also expect to have its accompanying offset.

and should be either checked or preferred

I don't know if I would ever let a system automatically decide to prefer a creation-time offset over a more current (accurate) one. In the use case above all I'd like the system to do is to make me aware of the situation.

[rocketraman]

I think the use cases need some work. Lets take the two given in turn:

1. Storing user-visible data. For example, let's say that one day, at 8:13, a user wakes up in Moscow and adds an entry that they took a pill. Then, a month later, they fly to New York. Opening their diary, they expect that entry to be at 8:13, not at whatever representation that moment had in New York. However, the specific moment when they took a pill may still be important.

Let's say the device used to record the entry had an outdated time zone database. In this case, the user probably manually set the device to have the displayed clock be the same as the wall clock, so the hardware clock is, say, an hour off the mark. Then, 8:13 is still the true time when an entry was made, and if we store that entry as an Instant, after the time zone database does update, the reading may become incorrect.

This is an interesting case because the specific instant at which the pill was taken is relevant, but so is the local time at which it was taken.

Just storing Instant isn't enough, because without knowing where I was at that instant, I can't obtain the LocalDateTime.

Just storing LocalDateTime isn't enough, because it doesn't specify a precise instant.

So DateTimeInZone seems like the correct representation here, but is it really? Or is the zone in DateTimeInZone really just a shortcut for the app to specify where the user was (Moscow) at the time the pill was taken?

Does the zone in and of itself add anything here to the data model over storing LocalDateTime and location = Moscow?

One case I can think of for the zone as a shortcut for location is that my calendar will generally know my zone, but not my location. Therefore, zone may be the only information available to the system. But even in this case, I think we still need to explain why we would need DateTimeInZone over just storing LocalDateTime and TimeZone separately.

Scheduling future events. Let's say that there's a conference on July 20th, 2023, in New York, and the keynote is at 10:00.

Imagine that suddenly the USA decides not to do the daylight saving time switch in 2023. The instant that used to be 10:00 will be represented as 09:00 in New York now. However, the actual schedule still says that the keynote is at 10:00. Clearly, Instant is a wrong representation here and LocalDateTime is what we should be storing.

What is the advantage here to using DateTimeInZone over just LocalDateTime directly? LocalDateTime handles the DST switch just as well.

Lets take another case -- the conference spans over a DST switch. In this case, LocalDateTime is still appropriate for the schedule.

Lets take another case -- the location of the conference switches from New York to Los Angeles. Would it be correct for the keynote speech to now be given at 12:00 instead of 09:00? No, its likely the schedule would stay exactly the same and LocalDateTime is still the correct representation.

There may be a valid case here, but I don't think the example given is it. Please clarify the use case for DateTimeInZone WRT scheduling future events.

[joffrey-bion]

the location of the conference switches from New York to Los Angeles. Would it be correct for the keynote speech to now be given at 12:00 instead of 09:00? No, its likely the schedule would stay exactly the same and LocalDateTime is still the correct representation.

While I get the point, I guess we could update the schedule with the new time zone in that case, just like the location itself is updated in the data somewhere. Also if the location is different, the new venue's availability may be different too and the schedule may change overall. So I'm not sure this point really invalidates the example.

There may be a valid case here, but I don't think the example given is it. Please clarify the use case for DateTimeInZone WRT scheduling future events.

One example for actually being able to (lazily) resolve the instant of the conference (and thus the need for the time zone in addition to the local time) is that people may be interested in the schedule from different places if they are attending the live stream remotely.

[rocketraman]

Both good points. But like in the first use case, isn't the zone here really a shortcut for the location? In other words, its easier to update the conference location/zone in one place (an attribute of the conference) rather than updating the zone in each and every scheduled item?

An edge case here I suppose is that different events at the conference are actually in different zones. In that case, the zone might be better stored along with each event. Feels thin though, and a use case that better brings out this aspect of scheduling future events may be better.

A better example I think was given in the OP but not expanded on: flight scheduling. While the operating arm of airlines (pilots, airports, arrivals, departures) always run in UTC, the scheduling arm operates based on local times in particular locations. But since airlines operate across many locations, it would be convenient to store both the local time and zone together.

[wkornewald]

We have to integrate with existing standards and those don't necessarily provide location information, but only zone information (and sometimes even only offsets). However, in case of ambiguity or zone DB changes or when only offsets are provided we could go even further and optionally allow adding location information if available. If we only have an Instant we could also use the location information to convert to the local time.

However, I don't think we need to come up with such a solution in the first version of this LocalDateTime+TimeZone object. In particular, converting locations to zones requires having a conversion DB with the complete history of all GPS coordinates of all zone borders. We should check if such a DB would be small enough to be bundled by default or if we need to make this an optional feature. Also, who will maintain such a DB for us?

Maybe this DB should not even be bundled with the module but regularly downloaded from some service, so a calendar app can react to DB changes without needing an update of the whole app. Zone DBs aren't bundled in each app either.

[dkhalanskyjb]

There's an interesting recent proposal for changes to the ZonedDateTime format: https://datatracker.ietf.org/doc/draft-ietf-sedate-datetime-extended/ Let's see how it goes.

Highlights:

• When the offset is unimportant, one will be expected to use Z, which is no longer equivalent to +00:00, instead meaning "the date-time is with the zero UTC offset, but we don't care which offset is used, this can be translated to other offsets freely as needed."
• If the time zone is marked with the "critical flag" ! (for example, 2022-07-08T00:14:07+01:00[!Europe/Paris]), an error must be raised in case of an inconsistency between an offset and the actual time zone rules. Otherwise, the time zone rules are unimportant: the error may be acted on, but not necessarily.

[LouisCAD]

Any reason there is no consideration for Instant + TimeZone instead of apparently very controversial and potentially DST-unsafe LocalDateTime + TimeZone?

InstantInTimeZone would allow:

• getting a LocalDateTime in the initial timezone + info on whether it's DST shifting/replay hour.
• getting an Instant to show it an other time zones.

[dkhalanskyjb]

apparently very controversial and potentially DST-unsafe LocalDateTime + TimeZone?

Huh? Where is it controversial and/or unsafe?

Any reason there is no consideration for Instant + TimeZone

Yes, it's unclear why it must be a data structure.

getting a LocalDateTime in the initial timezone
getting an Instant to show it an other time zones.

I'm imagining that you mean an API like this:

val instantInZone = InstantInZone(instant, initialZone)
val ldt1 = instantInZone.toLocalDateTime()
val ldt2 = instantInZone.withZone(anotherZone).toLocalDateTime()

If so, how is this better than the following (what we already have)?

val ldt1 = instant.toLocalDateTime(initialZone)
val ldt2 = instant.toLocalDateTime(anotherZone)

info on whether it's DST shifting/replay hour.

If you need such functionality, please file an issue and explain your use case. For the purposes of this discussion, however, it's still unclear why you'd need an Instant + TimeZone datastructure with instantInZone.transitionInfo() instead of zone.transitionInfoAtInstant(instant): TransitionInfo or something like that.

[CLOVIS-AI]

Storing user-visible data. For example, let's say that one day, at 8:13, a user wakes up in Moscow and adds an entry that they took a pill. Then, a month later, they fly to New York. Opening their diary, they expect that entry to be at 8:13, not at whatever representation that moment had in New York.

Is this really a use-case? This is not the behavior I would expect, and this is not how Google Calendar nor KOrganizer (the two calendar apps I use) operate.

These calendars make a difference between:

• The wallclock changed because I changed location,
• The wallclock changed because the current location changed timezone.

In this situation, I changed locations, so I would see the past event in my calendar to have a different wallclock time. So, I would expect to see the time I took that pill to be in the middle of the night (probably, I didn't do the math).

However, if I took the pill at 8:13 in Moscow, and the next day Moscow changes time offset, then the next day I would expect to see the event at 8:13 in my calendar: although the timezone has changed, it was not due to me being in a different place, and thus it displays continuously.

This is the behavior I expect to see in a hypothetical ZonedDateTime: converting to LocalTime gives the same value if the zone ID is the same (even if the UTC offset is different!), but gives different values when the zone ID is different (even if the time section is the same). For example:

• ZonedDateTime 12:02 in Moscow, when I'm in Moscow → LocalTime 12:02
• ZonedDateTime 12:02 in Moscow (summer time), when I'm in Moscow (winter time) → LocalTime 12:02
• ZonedDateTime 12:02 in Moscow, when I'm in New York → LocalTime (something other than 12:02, do the offset conversion in this case)

Now, I'm a bit confused that no one mentioned this in the thread… I believe this is how most calendars work, and I would see value in having this behavior.

[dkhalanskyjb]

So, I would expect to see the time I took that pill to be in the middle of the night (probably, I didn't do the math).

It's great if this behavior works for you; then, you can use the kotlinx.datetime.Instant class to represent the moment when you took the pill. When you convert it to the LocalDateTime in the current timezone, you will see the local times of past events updated to reflect your location.

However, some applications have other requirements. The example of a diary still works: if you have some plain text describing what happened, in won't change just because you moved to another place; if you want to enhance this plain text with smart behavior that recognizes the dates you've entered, this shouldn't break the text.

I believe this is how most calendars work, and I would see value in having this behavior.

Supporting new use cases doesn't break the support for the existing use cases, so you will have this behavior anyway.

This is the behavior I expect to see in a hypothetical ZonedDateTime: converting to LocalTime gives the same value if the zone ID is the same (even if the UTC offset is different!), but gives different values when the zone ID is different

It's against the spirit of the library to implicitly query TimeZone.currentSystemDefault(), so from the point of view of ZonedDateTime.toLocalTime, there would only be the time zone stored in ZonedDateTime, or you'd have to pass a time zone to toLocalTime explicitly.

[chrisjenx]

Another common case, is finding midnight at that same time zone, this is basically impossible using kdatetime:

billingStartDate = request.billingStartDate
                .toJodaDateTime(request.billingTimeZone)
                .withTimeAtStartOfDay(),
                ```

[dkhalanskyjb]

Did you try this https://kotlinlang.org/api/kotlinx-datetime/kotlinx-datetime/kotlinx.datetime/at-start-of-day-in.html ?

[tonicsoft]

A data structure that is called ZonedDateTime in Java is typically used to represent these. However, it's actually unsuitable for that.

I'm surprised to see no references in the comments to the OffsetDateTime class in java. Since it references a fixed offset from UTC, it does not have the overlap issue.

I have used this class for many years, back to when it was introduced with joda, and it performs a useful function admirably. I'm sure I am missing something but without an explicit explanation on why kotlinx-datetime doesn't have this concept, it looks like you are attempting to re-invent the wheel.

I'm just getting started with kotlinx-datetime but I guess OffsetDateTime would be like LocalDateTime + FixedOffsetTimeZone?

Is this idea already covered on another issue?

[tonicsoft]

There seems to be a lot of issues with identifying a use case too, so I'll add my two cents there too:

I'm sure we all come across strings like this from time to time: 2025-01-17T16:20:33+0000. Being able to have two way serialization of that into a single object would be useful. If I understand things correctly, I would have to create my own class for this since none of the kotlinx types capture the point in time (which is unique I think) without losing the offset information.

[dkhalanskyjb]

Since it references a fixed offset from UTC, it does not have the overlap issue.

It also is not applicable when you do want to take daylight savings time into account. Using UTC offsets when proper timezone identifiers can be used instead is typically discouraged, outside of some peculiar use cases.

I'm just getting started with kotlinx-datetime but I guess OffsetDateTime would be like LocalDateTime + FixedOffsetTimeZone?

It would be LocalDateTime + UtcOffset.

I'm sure we all come across strings like this from time to time: 2025-01-17T16:20:33+0000. Being able to have two way serialization of that into a single object would be useful. If I understand things correctly, I would have to create my own class for this

This functionality is already available. Please see the first code block in https://github.com/Kotlin/kotlinx-datetime?tab=readme-ov-file#parsing-and-formatting-partial-compound-or-out-of-bounds-data
In general, https://github.com/Kotlin/kotlinx-datetime/blob/master/README.md should be a good introductory document to get you up to speed with the library.