Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

ZonedDateTime — date and time with a time zone

ZonedDateTime combines a local date and time, a zone, and a resolved UTC offset. It distinguishes changing zones while preserving an instant from preserving local clock time, and handles ambiguities caused by clock changes.

Version: Java SE 21; repository runtime, production runtime not attested

Syntax

ZonedDateTime.of(localDateTime, zone)
ZonedDateTime.ofInstant(instant, zone)
ZonedDateTime.ofLocal(localDateTime, zone, preferredOffset)
zdt.withZoneSameInstant(zone)
zdt.withZoneSameLocal(zone)
zdt.toInstant()
zdt.format(formatter)
zdt.with(adjuster)
zdt.with(field, value)
zdt.withHour(hour)
zdt.withMinute(minute)

ZonedDateTime is an immutable, thread-safe ISO date-time with a ZoneId and a ZoneOffset. A regional zone defines rules for offset changes; a fixed offset has no such changes.

ZonedDateTime.of creates a value from a local date-time and zone. In a gap it shifts the time forward by the gap length; in an overlap it chooses the earlier offset. ZonedDateTime.ofLocal additionally accepts a preferred offset: it uses that offset if valid, otherwise the earlier offset; null means no preference. It resolves gaps the same way. ZonedDateTime.ofInstant(instant, zone) preserves the supplied instant without this ambiguity.

ZonedDateTime.withZoneSameInstant preserves the instant, usually changing local clock time. ZonedDateTime.withZoneSameLocal preserves the local date-time if possible, applying the rules of ofLocal; it can change the instant. ZonedDateTime.toInstant returns the instant alone, without the zone identifier, while ZonedDateTime.format formats the value using a DateTimeFormatter.

ZonedDateTime.with(adjuster) applies a TemporalAdjuster, while ZonedDateTime.with(field, value) sets a field. ZonedDateTime.withHour sets the hour to 0–23, and ZonedDateTime.withMinute sets the minute to 0–59. Keep the returned result: the original is unchanged. Local hour or minute changes also follow gap and overlap rules; they do not mean adding an elapsed duration.

Examples

import java.time.*;
import java.time.format.DateTimeFormatter;

public class Main {
    public static void main(String[] args) {
        ZoneId source = ZoneOffset.ofHours(1);
        ZoneId target = ZoneOffset.ofHours(-5);
        LocalDateTime local = LocalDateTime.of(2024, 1, 15, 12, 0);
        ZonedDateTime original = ZonedDateTime.of(local, source);
        ZonedDateTime sameInstant = original.withZoneSameInstant(target);
        ZonedDateTime sameLocal = original.withZoneSameLocal(target);

        System.out.println(sameInstant.format(DateTimeFormatter.ISO_ZONED_DATE_TIME));
        System.out.println(sameLocal.format(DateTimeFormatter.ISO_ZONED_DATE_TIME));
        System.out.println(original.toInstant().equals(sameInstant.toInstant()));
        System.out.println(original.toInstant().equals(sameLocal.toInstant()));
    }
}

Result

2024-01-15T06:00:00-05:00
2024-01-15T12:00:00-05:00
true
false

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources