Java Reference ยท Date and Time
ZoneId and ZoneOffset
Reference for java.time ZoneId and ZoneOffset: region IDs versus fixed offsets, looking up zone rules, daylight saving transitions and converting between zones.
A time zone tells you how to turn a point on the global timeline into a local date and time. Java models this with two related classes. ZoneId identifies a zone by its region name, such as Europe/Paris or America/New_York, and carries the rules for that region, including every daylight saving change in history. ZoneOffset is a subclass of ZoneId for a fixed difference from UTC, such as +05:30, with no rules and no changes over time.
Use a region ZoneId when you mean "the clock in that place" and a ZoneOffset when you only have a fixed offset, for example from a stored timestamp or a protocol header.
ZoneId paris = ZoneId.of("Europe/Paris"); ZoneOffset plusTwo = ZoneOffset.ofHours(2);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
static ZoneId of(String zoneId) static ZoneId systemDefault() static ZoneOffset of(String offsetId) static ZoneOffset ofHours(int hours) static ZoneOffset ofHoursMinutes(int hours, int minutes) static ZoneOffset ofTotalSeconds(int totalSeconds)
| Member | Description |
|---|---|
ZoneId.of(id) |
A region ID, "Z", an offset like "+02:00", or a prefixed form like "UTC+2". |
ZoneId.systemDefault() |
The JVM's default zone; depends on the machine, so avoid it in logic that must be reproducible. |
ZoneId.getAvailableZoneIds() |
The set of known region IDs (about 600). |
getRules() |
A ZoneRules object: getOffset(...), getStandardOffset(...), isDaylightSavings(...), getTransitions(). |
normalized() |
Collapses a fixed-offset zone to a ZoneOffset. |
ZoneOffset.UTC |
Offset zero. |
getTotalSeconds() |
The offset in seconds (ZoneOffset only). |
Throws: ZoneRulesException for an unknown region ID; DateTimeException for a malformed ID or an offset outside -18:00 to +18:00.
Usage notes
- Always prefer region IDs. A stored
+01:00is wrong for half the year if you meant "Paris time". Keep the region ID and let the rules produce the offset. - Three-letter abbreviations are ambiguous.
ZoneId.of("EST")andZoneId.of("PST")throwZoneRulesExceptionunless you pass theZoneId.SHORT_IDSmap as a second argument; useAmerica/New_York. - Gaps and overlaps. When a local time falls in a gap,
atZoneshifts it forward by the length of the gap; in an overlap it picks the earlier offset. UsewithEarlierOffsetAtOverlap()orwithLaterOffsetAtOverlap()to choose. - Tzdb changes. Governments change rules. The data ships with the JDK, so very old runtimes can have stale rules for future dates.
ZoneOffsetis aZoneId. Both can be passed wherever aZoneIdis accepted; anOffsetDateTimetakes only aZoneOffset.ZoneId.of("UTC")is not equal toZoneOffset.UTC. They behave the same for conversions but are different classes; callnormalized()on theZoneIdbefore comparing (it then equalsZoneOffset.UTC).- Immutable and thread-safe. Cache them in constants.
Related
ZonedDateTime,Instant,LocalDateTime,Clock- Lessons: Dates and times