Java ZoneOffset Class
Last modified: April 16, 2025
The java.time.ZoneOffset class represents a fixed time zone offset
from UTC/Greenwich. It is used to handle time zone differences in hours, minutes
and seconds. ZoneOffset is immutable and thread-safe.
ZoneOffset is typically used with other date-time classes like
OffsetDateTime. It supports offsets ranging from +18:00 to -18:00.
The class provides constants for common offsets like UTC.
ZoneOffset Class Overview
ZoneOffset provides methods to create and manipulate fixed time
zone offsets. Key operations include parsing strings, comparing offsets, and
getting total offset seconds. The class handles daylight saving time transitions.
public final class ZoneOffset implements ZoneId, TemporalAccessor,
TemporalAdjuster, Comparable<ZoneOffset>, Serializable {
public static final ZoneOffset UTC;
public static ZoneOffset of(String offsetId);
public static ZoneOffset ofHours(int hours);
public static ZoneOffset ofHoursMinutes(int hours, int minutes);
public static ZoneOffset ofHoursMinutesSeconds(int hours, int minutes, int seconds);
public static ZoneOffset ofTotalSeconds(int totalSeconds);
public int getTotalSeconds();
public String getId();
public boolean equals(Object obj);
}
The code above shows key methods provided by ZoneOffset. These
methods allow creating and working with fixed time zone offsets. The UTC
constant represents the zero offset from Greenwich.
Creating ZoneOffset Objects
ZoneOffset objects can be created in several ways. The most common methods are
of for string parsing and factory methods for specific offsets.
The UTC constant is also available.
package com.zetcode;
import java.time.ZoneOffset;
public class Main {
public static void main(String[] args) {
// UTC constant
ZoneOffset utc = ZoneOffset.UTC;
System.out.println("UTC offset: " + utc);
// From string
ZoneOffset offset1 = ZoneOffset.of("+02:00");
System.out.println("+02:00 offset: " + offset1);
// From hours
ZoneOffset offset2 = ZoneOffset.ofHours(5);
System.out.println("+05:00 offset: " + offset2);
// From hours and minutes
ZoneOffset offset3 = ZoneOffset.ofHoursMinutes(5, 30);
System.out.println("+05:30 offset: " + offset3);
// From total seconds
ZoneOffset offset4 = ZoneOffset.ofTotalSeconds(3600);
System.out.println("+01:00 offset (from seconds): " + offset4);
}
}
This example demonstrates different ways to create ZoneOffset objects. The output shows various time zone offsets. Note that string format must follow ISO-8601 time zone designator pattern.
Getting Offset Information
A ZoneOffset can provide its total offset in seconds and its string ID. These values are useful for calculations and display purposes. The methods provide access to the offset's fundamental properties.
package com.zetcode;
import java.time.ZoneOffset;
public class Main {
public static void main(String[] args) {
ZoneOffset offset = ZoneOffset.of("+05:30");
// Get total offset in seconds
int totalSeconds = offset.getTotalSeconds();
System.out.println("Total seconds: " + totalSeconds);
// Get ID string
String id = offset.getId();
System.out.println("ID: " + id);
// Calculate hours and minutes
int hours = totalSeconds / 3600;
int minutes = (totalSeconds % 3600) / 60;
System.out.printf("Human-readable: %+02d:%02d%n", hours, minutes);
}
}
This example shows how to extract information from a ZoneOffset. The
getTotalSeconds method returns the complete offset in seconds.
The ID follows the ISO-8601 format for time zone offsets.
Comparing ZoneOffsets
ZoneOffsets can be compared to determine their relative positions from UTC. The
class provides equals and compareTo methods. These
comparisons are useful for sorting or grouping by time zone.
package com.zetcode;
import java.time.ZoneOffset;
public class Main {
public static void main(String[] args) {
ZoneOffset offset1 = ZoneOffset.of("+02:00");
ZoneOffset offset2 = ZoneOffset.of("+05:30");
ZoneOffset offset3 = ZoneOffset.of("-03:00");
// Equality check
ZoneOffset sameOffset = ZoneOffset.ofHours(2);
System.out.println("Equals check: " + offset1.equals(sameOffset));
// Comparison
System.out.println("Compare +02:00 and +05:30: " +
offset1.compareTo(offset2));
System.out.println("Compare +02:00 and -03:00: " +
offset1.compareTo(offset3));
// Sorting example
System.out.println("Is +02:00 before +05:30? " +
(offset1.compareTo(offset2) < 0));
}
}
This example demonstrates various ways to compare ZoneOffset objects. The comparison is based on total seconds from UTC. Note that equal offsets will always have the same string representation.
Using ZoneOffset with Other Classes
ZoneOffset is often used with other date-time classes like OffsetDateTime. These combinations allow representing date-time values with specific offsets. The integration is seamless in the Java Time API.
package com.zetcode;
import java.time.OffsetDateTime;
import java.time.ZoneOffset;
import java.time.LocalDateTime;
public class Main {
public static void main(String[] args) {
ZoneOffset offset = ZoneOffset.of("+05:30");
// Create OffsetDateTime with offset
OffsetDateTime odt = OffsetDateTime.now(offset);
System.out.println("Current date-time with offset: " + odt);
// Convert LocalDateTime to OffsetDateTime
LocalDateTime ldt = LocalDateTime.now();
OffsetDateTime odt2 = ldt.atOffset(offset);
System.out.println("Local date-time with offset: " + odt2);
// Extract offset from OffsetDateTime
ZoneOffset extractedOffset = odt.getOffset();
System.out.println("Extracted offset: " + extractedOffset);
}
}
This example shows how ZoneOffset works with other date-time classes. The
atOffset method attaches an offset to a local date-time. All
operations preserve the exact time being represented.
Handling Maximum and Minimum Offsets
ZoneOffset supports offsets from +18:00 to -18:00. Attempting to create offsets outside this range throws an exception. The class validates all input values.
package com.zetcode;
import java.time.ZoneOffset;
public class Main {
public static void main(String[] args) {
// Maximum offset
ZoneOffset maxOffset = ZoneOffset.of("+18:00");
System.out.println("Maximum offset: " + maxOffset);
// Minimum offset
ZoneOffset minOffset = ZoneOffset.of("-18:00");
System.out.println("Minimum offset: " + minOffset);
try {
// Invalid offset (too large)
ZoneOffset invalid = ZoneOffset.of("+19:00");
} catch (Exception e) {
System.out.println("Caught exception: " + e.getMessage());
}
// Edge case in seconds
ZoneOffset edgeCase = ZoneOffset.ofTotalSeconds(18 * 3600);
System.out.println("Edge case offset: " + edgeCase);
}
}
This example demonstrates the valid range for ZoneOffset. The class enforces the +18:00 to -18:00 limit strictly. All factory methods perform this validation.
ZoneOffset vs ZoneId
ZoneOffset differs from ZoneId in representing fixed offsets versus full time zone rules. ZoneOffset is simpler but doesn't handle daylight saving time. ZoneId is more flexible but complex.
package com.zetcode;
import java.time.ZoneId;
import java.time.ZoneOffset;
import java.time.ZonedDateTime;
public class Main {
public static void main(String[] args) {
// ZoneOffset example
ZoneOffset offset = ZoneOffset.of("+02:00");
System.out.println("Fixed offset: " + offset);
// ZoneId example
ZoneId zone = ZoneId.of("Europe/Paris");
System.out.println("Full time zone: " + zone);
// Both can be used with ZonedDateTime
ZonedDateTime zdt1 = ZonedDateTime.now(offset);
System.out.println("With offset: " + zdt1);
ZonedDateTime zdt2 = ZonedDateTime.now(zone);
System.out.println("With zone: " + zdt2);
// ZoneOffset is a ZoneId
System.out.println("Is ZoneOffset a ZoneId? " +
(offset instanceof ZoneId));
}
}
This example compares ZoneOffset and ZoneId usage. While both can be used as ZoneIds, ZoneOffset provides fixed offsets only. ZoneId handles daylight saving and historical changes.
Source
Java ZoneOffset Class Documentation
In this article, we've covered the essential methods and features of the Java ZoneOffset class. Understanding these concepts is crucial for accurate time zone handling in Java applications.
Author
List all Java tutorials.