CKTIS / Java
ZonedDateTime: creation, conversion, formatting, and calendar edits
Create a zoned date-time, convert it without changing the instant, format it for display, and edit local fields while accounting for time-zone transitions.
Version: Java SE 21
Syntax
java.time.ZonedDateTime — Java SE 21
static ZonedDateTime of(LocalDateTime dateTime, ZoneId zone)
static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone)
static ZonedDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone)
static ZonedDateTime ofInstant(Instant instant, ZoneId zone)
static ZonedDateTime ofInstant(LocalDateTime dateTime, ZoneOffset offset, ZoneId zone)
Instant toInstant() // inherited from ChronoZonedDateTime
ZonedDateTime withZoneSameInstant(ZoneId zone)
String format(DateTimeFormatter formatter)
ZonedDateTime with(TemporalAdjuster adjuster)
ZonedDateTime with(TemporalField field, long newValue)
ZonedDateTime withHour(int hour)
ZonedDateTime withMinute(int minute)java.time.ZonedDateTime stores a local date and time, a zone ID, and the resolved offset from UTC. The static factory ZonedDateTime.of takes a LocalDateTime, a LocalDate and LocalTime pair, or seven integers (year through nanoOfSecond), always with a ZoneId. In a gap when clocks jump forward, it moves the local date-time forward by the gap length. In an overlap when clocks go back, it chooses the offset that gives the earlier instant. Invalid numeric fields or an impossible date cause DateTimeException.
ZonedDateTime.ofInstant(Instant, ZoneId) derives the local date-time and offset for the given instant in the target zone. The (LocalDateTime, ZoneOffset, ZoneId) overload first derives the instant from the supplied local date-time and offset, then represents it in the target zone; the result can differ from the input in both local time and offset. The inherited ZonedDateTime.toInstant() returns the same point on the timeline without zone information. ZonedDateTime.withZoneSameInstant(ZoneId) keeps the instant but can change the local date and time. By contrast, withZoneSameLocal tries to keep the local date and time and may change the instant.
ZonedDateTime.format(DateTimeFormatter) returns a String without changing the object. ISO_OFFSET_DATE_TIME prints the local date-time and offset, but not a region-based zone ID. If formatting fails, the method throws DateTimeException.
ZonedDateTime.with(TemporalAdjuster) applies a rule, such as TemporalAdjusters.lastDayOfMonth(). The with(TemporalField, long) overload sets a supported field, such as ChronoField.MONTH_OF_YEAR. INSTANT_SECONDS sets the second on the timeline while keeping the zone and fractional second; OFFSET_SECONDS can only switch to the other valid offset in an overlap. An unsupported field can cause UnsupportedTemporalTypeException; an invalid value can cause DateTimeException.
ZonedDateTime.withHour(int) sets the hour (0–23), and ZonedDateTime.withMinute(int) sets the minute (0–59); neither adds elapsed time. Out-of-range values cause DateTimeException. When editing local fields, the zone stays the same but the instant can change. A gap shifts the result forward by the gap length; an overlap keeps the previous offset if valid and otherwise chooses the earlier instant. The objects are immutable, so keep the returned result.
Examples
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.temporal.ChronoField;
import java.time.temporal.TemporalAdjusters;
public class Main {
public static void main(String[] args) {
ZoneOffset east = ZoneOffset.of("+01:00");
ZoneOffset west = ZoneOffset.of("-05:00");
DateTimeFormatter iso = DateTimeFormatter.ISO_OFFSET_DATE_TIME;
ZonedDateTime original = ZonedDateTime.of(
LocalDateTime.of(2024, 1, 15, 10, 30), east);
Instant instant = original.toInstant();
ZonedDateTime converted = original.withZoneSameInstant(west);
ZonedDateTime rebuilt = ZonedDateTime.ofInstant(instant, west);
ZonedDateTime edited = original.with(ChronoField.MONTH_OF_YEAR, 2)
.with(TemporalAdjusters.lastDayOfMonth())
.withHour(14)
.withMinute(45);
System.out.println(original.format(iso));
System.out.println(instant);
System.out.println(converted.format(iso));
System.out.println(converted.equals(rebuilt));
System.out.println(edited.format(iso));
}
}Result
2024-01-15T10:30:00+01:00 2024-01-15T09:30:00Z 2024-01-15T04:30:00-05:00 true 2024-02-29T14:45:00+01:00
The first three lines represent the same instant. `true` shows that both conversions to `-05:00` agree. The last line shows the calendar edit to February 29 at 14:45 with the original offset. Fixed offsets keep the example independent of regional time-zone rules.
Related lessons
- Java · Lesson 59 · Intermediate · Version: 2