Class DateTimeZone

java.lang.Object
org.teavm.classlib.impl.tz.DateTimeZone
Direct Known Subclasses:
StorableDateTimeZone

public abstract class DateTimeZone extends Object
DateTimeZone represents a time zone.

A time zone is a system of rules to convert time from one geographic location to another. For example, Paris, France is one hour ahead of London, England. Thus when it is 10:00 in London, it is 11:00 in Paris.

All time zone rules are expressed, for historical reasons, relative to Greenwich, London. Local time in Greenwich is referred to as Greenwich Mean Time (GMT). This is similar, but not precisely identical, to Universal Coordinated Time, or UTC. This library only uses the term UTC.

Using this system, America/Los_Angeles is expressed as UTC-08:00, or UTC-07:00 in the summer. The offset -08:00 indicates that America/Los_Angeles time is obtained from UTC by adding -08:00, that is, by subtracting 8 hours.

The offset differs in the summer because of daylight saving time, or DST. The following definitions of time are generally used:

  • UTC - The reference time.
  • Standard Time - The local time without a daylight saving time offset. For example, in Paris, standard time is UTC+01:00.
  • Daylight Saving Time - The local time with a daylight saving time offset. This offset is typically one hour, but not always. It is typically used in most countries away from the equator. In Paris, daylight saving time is UTC+02:00.
  • Wall Time - This is what a local clock on the wall reads. This will be either Standard Time or Daylight Saving Time depending on the time of year and whether the location uses Daylight Saving Time.

Unlike the Java TimeZone class, DateTimeZone is immutable. It also only supports long format time zone ids. Thus EST and ECT are not accepted. However, the factory that accepts a TimeZone will attempt to convert from the old short id to a suitable long id.

Unless you override the standard behaviour, the default if the third approach.

DateTimeZone is thread-safe and immutable, and all subclasses must be as well.

Since:
1.0
Author:
Brian S O'Neill, Stephen Colebourne
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    long
    adjustOffset​(long instant, boolean earlierOrLater)
    Adjusts the offset to be the earlier or later one during an overlap.
    abstract ZoneRules
     
    long
    convertLocalToUTC​(long instantLocal, boolean strict)
    Converts a local instant to a standard UTC instant with the same local time.
    long
    convertLocalToUTC​(long instantLocal, boolean strict, long originalInstantUTC)
    Converts a local instant to a standard UTC instant with the same local time attempting to use the same offset as the original.
    long
    convertUTCToLocal​(long instantUTC)
    Converts a standard UTC instant to a local instant with the same local time.
    Gets the ID of this datetime zone.
    long
    getMillisKeepLocal​(DateTimeZone newZone, long oldInstant)
    Gets the millisecond instant in another zone keeping the same local time.
    abstract int
    getOffset​(long instant)
    Gets the millisecond offset to add to UTC to get local time.
    int
    getOffsetFromLocal​(long instantLocal)
    Gets the millisecond offset to subtract from local time to get UTC time.
    abstract int
    getStandardOffset​(long instant)
    Gets the standard millisecond offset to add to UTC to get local time, when standard time is in effect.
    abstract boolean
    Returns true if this time zone has no transitions.
    boolean
    isStandardOffset​(long instant)
    Checks whether, at a particular instant, the offset is standard or not.
    abstract long
    nextTransition​(long instant)
    Advances the given instant to where the time zone offset or name changes.
    abstract long
    previousTransition​(long instant)
    Retreats the given instant to where the time zone offset or name changes.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • DateTimeZone

      protected DateTimeZone(String id)
      Constructor.
      Parameters:
      id - the id to use
      Throws:
      IllegalArgumentException - if the id is null
  • Method Details

    • getID

      public final String getID()
      Gets the ID of this datetime zone.
      Returns:
      the ID of this datetime zone
    • getOffset

      public abstract int getOffset(long instant)
      Gets the millisecond offset to add to UTC to get local time.
      Parameters:
      instant - milliseconds from 1970-01-01T00:00:00Z to get the offset for
      Returns:
      the millisecond offset to add to UTC to get local time
    • getStandardOffset

      public abstract int getStandardOffset(long instant)
      Gets the standard millisecond offset to add to UTC to get local time, when standard time is in effect.
      Parameters:
      instant - milliseconds from 1970-01-01T00:00:00Z to get the offset for
      Returns:
      the millisecond offset to add to UTC to get local time
    • isStandardOffset

      public boolean isStandardOffset(long instant)
      Checks whether, at a particular instant, the offset is standard or not.

      This method can be used to determine whether Summer Time (DST) applies. As a general rule, if the offset at the specified instant is standard, then either Winter time applies, or there is no Summer Time. If the instant is not standard, then Summer Time applies.

      The implementation of the method is simply whether getOffset(long) equals getStandardOffset(long) at the specified instant.

      Parameters:
      instant - milliseconds from 1970-01-01T00:00:00Z to get the offset for
      Returns:
      true if the offset at the given instant is the standard offset
      Since:
      1.5
    • getOffsetFromLocal

      public int getOffsetFromLocal(long instantLocal)
      Gets the millisecond offset to subtract from local time to get UTC time. This offset can be used to undo adding the offset obtained by getOffset.
       millisLocal == millisUTC   + getOffset(millisUTC)
       millisUTC   == millisLocal - getOffsetFromLocal(millisLocal)
       
      NOTE: After calculating millisLocal, some error may be introduced. At offset transitions (due to DST or other historical changes), ranges of local times may map to different UTC times.

      For overlaps (where the local time is ambiguous), this method returns the offset applicable before the gap. The effect of this is that any instant calculated using the offset from an overlap will be in "summer" time.

      For gaps, this method returns the offset applicable before the gap, ie "winter" offset. However, the effect of this is that any instant calculated using the offset from a gap will be after the gap, in "summer" time.

      For example, consider a zone with a gap from 01:00 to 01:59:
      Input: 00:00 (before gap) Output: Offset applicable before gap DateTime: 00:00
      Input: 00:30 (before gap) Output: Offset applicable before gap DateTime: 00:30
      Input: 01:00 (in gap) Output: Offset applicable before gap DateTime: 02:00
      Input: 01:30 (in gap) Output: Offset applicable before gap DateTime: 02:30
      Input: 02:00 (after gap) Output: Offset applicable after gap DateTime: 02:00
      Input: 02:30 (after gap) Output: Offset applicable after gap DateTime: 02:30

      NOTE: Prior to v2.0, the DST overlap behaviour was not defined and varied by hemisphere. Prior to v1.5, the DST gap behaviour was also not defined. In v2.4, the documentation was clarified again.

      Parameters:
      instantLocal - the millisecond instant, relative to this time zone, to get the offset for
      Returns:
      the millisecond offset to subtract from local time to get UTC time
    • convertUTCToLocal

      public long convertUTCToLocal(long instantUTC)
      Converts a standard UTC instant to a local instant with the same local time. This conversion is used before performing a calculation so that the calculation can be done using a simple local zone.
      Parameters:
      instantUTC - the UTC instant to convert to local
      Returns:
      the local instant with the same local time
      Throws:
      ArithmeticException - if the result overflows a long
      Since:
      1.5
    • convertLocalToUTC

      public long convertLocalToUTC(long instantLocal, boolean strict, long originalInstantUTC)
      Converts a local instant to a standard UTC instant with the same local time attempting to use the same offset as the original.

      This conversion is used after performing a calculation where the calculation was done using a simple local zone. Whenever possible, the same offset as the original offset will be used. This is most significant during a daylight savings overlap.

      Parameters:
      instantLocal - the local instant to convert to UTC
      strict - whether the conversion should reject non-existent local times
      originalInstantUTC - the original instant that the calculation is based on
      Returns:
      the UTC instant with the same local time,
      Throws:
      ArithmeticException - if the result overflows a long
      IllegalArgumentException - if the zone has no equivalent local time
      Since:
      2.0
    • convertLocalToUTC

      public long convertLocalToUTC(long instantLocal, boolean strict)
      Converts a local instant to a standard UTC instant with the same local time. This conversion is used after performing a calculation where the calculation was done using a simple local zone.
      Parameters:
      instantLocal - the local instant to convert to UTC
      strict - whether the conversion should reject non-existent local times
      Returns:
      the UTC instant with the same local time,
      Throws:
      ArithmeticException - if the result overflows a long
      Since:
      1.5
    • getMillisKeepLocal

      public long getMillisKeepLocal(DateTimeZone newZone, long oldInstant)
      Gets the millisecond instant in another zone keeping the same local time.

      The conversion is performed by converting the specified UTC millis to local millis in this zone, then converting back to UTC millis in the new zone.

      Parameters:
      newZone - the new zone, null means default
      oldInstant - the UTC millisecond instant to convert
      Returns:
      the UTC millisecond instant with the same local time in the new zone
    • adjustOffset

      public long adjustOffset(long instant, boolean earlierOrLater)
      Adjusts the offset to be the earlier or later one during an overlap.
      Parameters:
      instant - the instant to adjust
      earlierOrLater - false for earlier, true for later
      Returns:
      the adjusted instant millis
    • isFixed

      public abstract boolean isFixed()
      Returns true if this time zone has no transitions.
      Returns:
      true if no transitions
    • nextTransition

      public abstract long nextTransition(long instant)
      Advances the given instant to where the time zone offset or name changes. If the instant returned is exactly the same as passed in, then no changes occur after the given instant.
      Parameters:
      instant - milliseconds from 1970-01-01T00:00:00Z
      Returns:
      milliseconds from 1970-01-01T00:00:00Z
    • previousTransition

      public abstract long previousTransition(long instant)
      Retreats the given instant to where the time zone offset or name changes. If the instant returned is exactly the same as passed in, then no changes occur before the given instant.
      Parameters:
      instant - milliseconds from 1970-01-01T00:00:00Z
      Returns:
      milliseconds from 1970-01-01T00:00:00Z
    • asZoneRules

      public abstract ZoneRules asZoneRules()