ZonedDateTime

ZonedDateTime is a date-time class in the Java platform, part of the java.time API. It represents a date and time together with a time zone, combining a LocalDateTime with a ZoneId and the corresponding offset. It follows the ISO-8601 calendar system and is immutable and thread-safe, making it suitable for use in multi-threaded code and as a map key.

It can be created from a date and time with a zone, from a LocalDateTime and ZoneId, or from an Instant with a ZoneId using factory methods such as of, ofInstant, and parse from ISO-8601 strings. The time zone information ensures that the same local date-time can map to different instants in different zones.

ZonedDateTime exposes accessors for the date and time fields (year, month, day, hour, minute, second, nano) as well as zone information and offset. It can be converted to an Instant via toInstant, or to a LocalDateTime with toLocalDateTime. It also supports conversions to another zone with methods like withZoneSameInstant and withZoneSameLocal.

Arithmetic and comparison are defined: you can add or subtract years, months, days, hours, and so on, and comparisons are based on the instant in time, not merely the local fields. Its toString method renders an ISO-8601 representation including the zone.

DST and time-zone rules affect the interpretation of certain local times: some local times are skipped or occur twice during transitions, and ZoneRules determine the exact offset for a given instant. ZonedDateTime thus encapsulates both the local wall clock time and the zone's offset rules.

Common use cases include timestamping events across regions, scheduling calendar events, and displaying times in the user's time zone. A best practice is to store instants (or UTC) and convert to a zone only for display or user interaction.