withZoneSameLocal: Changing Zone Without Adjusting Time
You'll learn how to change a ZonedDateTime's time zone while preserving the local date-time values, not the physical instant.
The Core Difference from withZoneSameInstant
You've already learned withZoneSameInstant(), which adjusts the local time to preserve the same moment in history. But what if you want to keep the clock reading (like "3:00 PM") and just reinterpret it in a different zone?
That's exactly what withZoneSameLocal() does.
How withZoneSameLocal Works
When you call withZoneSameLocal(ZoneId) on a ZonedDateTime:
- The local date-time values (year, month, day, hour, minute, etc.) stay exactly the same
- Only the
ZoneIdchanges - The underlying instant (moment in time) changes as a result
The Analogy
Imagine you're watching a TV show at 3:00 PM in New York. With withZoneSameInstant(), you'd travel to Tokyo and watch the same broadcast (different local time). With withZoneSameLocal(), you'd travel to Tokyo and watch whatever's on at 3:00 PM Tokyo time (different moment, same clock reading).
When You'd Use This
This method is useful when you need to:
- Interpret a local time as if it occurred in a different zone
- Convert scheduling data where the "3:00 PM meeting" means 3:00 PM wherever you are
- Handle scenarios where the clock time matters more than the absolute moment
ZonedDateTime newYork = ZonedDateTime.of(2024, 1, 15, 15, 0, 0, 0,
ZoneId.of("America/New_York"));
// 2024-01-15T15:00:00-05:00[America/New_York]
ZonedDateTime tokyo = newYork.withZoneSameLocal(ZoneId.of("Asia/Tokyo"));
// 2024-01-15T15:00:00+09:00[Asia/Tokyo]
// Notice: still 15:00, but now in Tokyo's zone (different instant!)
Key Takeaway: withZoneSameLocal() preserves the local clock reading while changing the time zone, effectively creating a different moment in time with the same displayed date-time values.