How do Instant and ZonedDateTime relate, and how do you convert between them and reinterpret a moment in another zone?

## A ladder of richness java.time offers several types that all relate to a moment, differing in how much context they carry: - **`Instant`** — a single point on the global timeline (epoch seconds + nanos, in UTC). No human formatting. - **`OffsetDateTime`** — a date-time with a **fixed offset** from UTC (e.g. `+02:00`) but **no zone rules**. It pins a moment and has a wall-clock reading, but it doesn't know about DST transitions. - **`ZonedDateTime`** — a date-time with a full **`ZoneId`** (e.g. `Europe/Paris`) plus the offset resolved for that moment. It knows the zone's rules, so it handles DST and historical offset changes. Think of it as: `Instant` = the moment, `OffsetDateTime` = moment + a number, `ZonedDateTime` = moment + a region (which implies the number, and how it changes over time). ## Converting Instant <-> ZonedDateTime ```java Instant now = Instant.now(); // Instant -> ZonedDateTime (attach a zone) ZonedDateTime zdt = now.atZone(ZoneId.of("Europe/Paris")); // equivalent: ZonedDateTime.ofInstant(now, zone) // ZonedDateTime -> Instant (drop to UTC) Instant back = zdt.toInstant(); ``` `atZone` is non-lossy in the moment dimension: `zdt.toInstant()` returns exactly the `Instant` you started with. You're just adding/removing the human-readable context. ## Reinterpreting a moment in another zone: the two `withZone*` methods This is the most-tested subtlety: - **`withZoneSameInstant(otherZone)`** — **keep the same physical instant**, recompute the wall clock for the new zone. The underlying `Instant` is unchanged; only the displayed time changes. ```java ZonedDateTime london = ZonedDateTime.of(2026, 6, 20, 15, 0, 0, 0, ZoneId.of("Europe/London")); ZonedDateTime paris = london.withZoneSameInstant(ZoneId.of("Europe/Paris")); // paris reads 16:00; london.toInstant().equals(paris.toInstant()) == true ``` This is how you answer "what time is it in Tokyo when it's 3pm here?" - **`withZoneSameLocal(otherZone)`** — **keep the wall-clock digits**, change which moment they mean. The `Instant` shifts. ```java ZonedDateTime parisSameLocal = london.withZoneSameLocal(ZoneId.of("Europe/Paris")); // still reads 15:00, but is now a DIFFERENT instant (an hour earlier in UTC) ``` Use `withZoneSameLocal` only when the wall-clock value itself is the thing you're moving (rare). Confusing the two silently corrupts times — a frequent production bug. ## Instant <-> OffsetDateTime ```java OffsetDateTime odt = instant.atOffset(ZoneOffset.ofHours(2)); Instant fromOdt = odt.toInstant(); ``` Prefer `ZonedDateTime` when you need DST correctness; `OffsetDateTime` is handy for protocols/storage that record a fixed offset (e.g. RFC 3339 timestamps). ## Equality vs same-instant Two `ZonedDateTime`s in different zones are **not `equals()`** even if they denote the same moment (equals compares all fields). To compare moments, compare their `Instant`s, or use `isEqual()` / `compareTo` semantics that look at the timeline. This trips people who expect `london.equals(paris)` to be true after `withZoneSameInstant`. ## Mental model `Instant` is the truth; zoned/offset types are *views* of that truth. `atZone`/`toInstant` switch between truth and view; `withZoneSameInstant` switches between views *without* changing the truth; `withZoneSameLocal` deliberately changes the truth while keeping the view's digits.