* The offset differs in the summer because of daylight saving time, or DST. - * The following definitions of time are generally used: + * The following definitions are helpful: *
+ * For example, in 2018 Greece applied daylight saving. + * Throughout the whole year, the raw offset was +02:00. + * In winter, the additional offset was zero, while in summer the additional offset was one hour. + * Thus, the actual offset was +02:00 in winter and +03:00 in summer. + *
+ * Note: Some governments, most notably Ireland, define daylight saving by describing + * a "standard" time in summer and a negative DST offset in winter. + * Joda-Time, like the JDK, follows a model for time-zone data where there is a + * raw offset all year round and a positive additional offset. + * As such, callers cannot assume that the raw offset is that defined by law for the zone. + *
+ * Note: Some governments define a daylight saving time that applies for two separate periods. + * For example, the year might be winter time, then summer time, then a special time equal + * to winter time, then back to summer time before finally dropping back to winter time. + * As such, callers cannot assume that the raw and DST offsets directly correlate to summer and winter. + *
* Unlike the Java TimeZone class, DateTimeZone is immutable. It also only * supports long format time zone ids. Thus PST and ECT are not accepted. * However, the factory that accepts a TimeZone will attempt to convert from @@ -822,6 +835,10 @@ public String getName(long instant, Locale locale) { /** * Gets the millisecond offset to add to UTC to get local time. + *
+ * This returns the actual offset from UTC for the zone at the specified instant. + * If the method is called with a different instant, the offset returned may be different + * as a result of daylight saving or other government rule changes. * * @param instant milliseconds from 1970-01-01T00:00:00Z to get the offset for * @return the millisecond offset to add to UTC to get local time @@ -830,6 +847,10 @@ public String getName(long instant, Locale locale) { /** * Gets the millisecond offset to add to UTC to get local time. + *
+ * This returns the actual offset from UTC for the zone at the specified instant. + * If the method is called with a different instant, the offset returned may be different + * as a result of daylight saving or other government rule changes. * * @param instant instant to get the offset for, null means now * @return the millisecond offset to add to UTC to get local time @@ -842,8 +863,16 @@ public final int getOffset(ReadableInstant instant) { } /** - * Gets the standard millisecond offset to add to UTC to get local time, - * when standard time is in effect. + * Gets the raw millisecond offset to add to UTC. + *
+ * This should be treated as an implementation detail. + * End-users should use {@link #getOffset(long)}. + *
+ * This returns the raw offset from UTC for the zone at the specified instant, effectively ignoring DST. + * If the method is called with a different instant, the offset returned may be different + * as a result of government rule changes. + *
+ * This method should be named {@code getRawOffset()} but cannot be renamed for compatibility reasons. * * @param instant milliseconds from 1970-01-01T00:00:00Z to get the offset for * @return the millisecond offset to add to UTC to get local time @@ -851,18 +880,20 @@ public final int getOffset(ReadableInstant instant) { public abstract int getStandardOffset(long instant); /** - * Checks whether, at a particular instant, the offset is standard or not. + * Checks whether, at a particular instant, the offset is raw 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. + * This method can be used to estimate whether Summer Time (DST) applies at the specified instant. + * As a general rule, if the actual offset equals the raw offset at the specified instant + * then either winter time applies or the zone does not have DST rules. + * If the actual offset does not equal the raw offset, then some form of Summer Time applies. *
* The implementation of the method is simply whether {@link #getOffset(long)} * equals {@link #getStandardOffset(long)} at the specified instant. + *
+ * This method should be named {@code isRawOffsetInUse()} but cannot be renamed for compatibility reasons. * * @param instant milliseconds from 1970-01-01T00:00:00Z to get the offset for - * @return true if the offset at the given instant is the standard offset + * @return true if the offset at the given instant is the same as the raw offset * @since 1.5 */ public boolean isStandardOffset(long instant) { @@ -945,7 +976,7 @@ public int getOffsetFromLocal(long instantLocal) { } /** - * Converts a standard UTC instant to a local instant with the same + * Converts an actual 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. * @@ -965,7 +996,7 @@ public long convertUTCToLocal(long instantUTC) { } /** - * Converts a local instant to a standard UTC instant with the same + * Converts a local instant to an actual UTC instant with the same * local time attempting to use the same offset as the original. *
* This conversion is used after performing a calculation @@ -992,7 +1023,7 @@ public long convertLocalToUTC(long instantLocal, boolean strict, long originalIn } /** - * Converts a local instant to a standard UTC instant with the same + * Converts a local instant to an actual 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. * @@ -1067,107 +1098,11 @@ public long getMillisKeepLocal(DateTimeZone newZone, long oldInstant) { return newZone.convertLocalToUTC(instantLocal, false, oldInstant); } -// //----------------------------------------------------------------------- -// /** -// * Checks if the given {@link LocalDateTime} is within an overlap. -// *
-// * When switching from Daylight Savings Time to standard time there is -// * typically an overlap where the same clock hour occurs twice. This -// * method identifies whether the local datetime refers to such an overlap. -// * -// * @param localDateTime the time to check, not null -// * @return true if the given datetime refers to an overlap -// */ -// public boolean isLocalDateTimeOverlap(LocalDateTime localDateTime) { -// if (isFixed()) { -// return false; -// } -// long instantLocal = localDateTime.toDateTime(DateTimeZone.UTC).getMillis(); -// // get the offset at instantLocal (first estimate) -// int offsetLocal = getOffset(instantLocal); -// // adjust instantLocal using the estimate and recalc the offset -// int offset = getOffset(instantLocal - offsetLocal); -// // if the offsets differ, we must be near a DST boundary -// if (offsetLocal != offset) { -// long nextLocal = nextTransition(instantLocal - offsetLocal); -// long nextAdjusted = nextTransition(instantLocal - offset); -// if (nextLocal != nextAdjusted) { -// // in DST gap -// return false; -// } -// long diff = Math.abs(offset - offsetLocal); -// DateTime dateTime = localDateTime.toDateTime(this); -// DateTime adjusted = dateTime.plus(diff); -// if (dateTime.getHourOfDay() == adjusted.getHourOfDay() && -// dateTime.getMinuteOfHour() == adjusted.getMinuteOfHour() && -// dateTime.getSecondOfMinute() == adjusted.getSecondOfMinute()) { -// return true; -// } -// adjusted = dateTime.minus(diff); -// if (dateTime.getHourOfDay() == adjusted.getHourOfDay() && -// dateTime.getMinuteOfHour() == adjusted.getMinuteOfHour() && -// dateTime.getSecondOfMinute() == adjusted.getSecondOfMinute()) { -// return true; -// } -// return false; -// } -// return false; -// } -// -// -// DateTime dateTime = null; -// try { -// dateTime = localDateTime.toDateTime(this); -// } catch (IllegalArgumentException ex) { -// return false; // it is a gap, not an overlap -// } -// long offset1 = Math.abs(getOffset(dateTime.getMillis() + 1) - getStandardOffset(dateTime.getMillis() + 1)); -// long offset2 = Math.abs(getOffset(dateTime.getMillis() - 1) - getStandardOffset(dateTime.getMillis() - 1)); -// long offset = Math.max(offset1, offset2); -// if (offset == 0) { -// return false; -// } -// DateTime adjusted = dateTime.plus(offset); -// if (dateTime.getHourOfDay() == adjusted.getHourOfDay() && -// dateTime.getMinuteOfHour() == adjusted.getMinuteOfHour() && -// dateTime.getSecondOfMinute() == adjusted.getSecondOfMinute()) { -// return true; -// } -// adjusted = dateTime.minus(offset); -// if (dateTime.getHourOfDay() == adjusted.getHourOfDay() && -// dateTime.getMinuteOfHour() == adjusted.getMinuteOfHour() && -// dateTime.getSecondOfMinute() == adjusted.getSecondOfMinute()) { -// return true; -// } -// return false; - -// long millis = dateTime.getMillis(); -// long nextTransition = nextTransition(millis); -// long previousTransition = previousTransition(millis); -// long deltaToPreviousTransition = millis - previousTransition; -// long deltaToNextTransition = nextTransition - millis; -// if (deltaToNextTransition < deltaToPreviousTransition) { -// int offset = getOffset(nextTransition); -// int standardOffset = getStandardOffset(nextTransition); -// if (Math.abs(offset - standardOffset) >= deltaToNextTransition) { -// return true; -// } -// } else { -// int offset = getOffset(previousTransition); -// int standardOffset = getStandardOffset(previousTransition); -// if (Math.abs(offset - standardOffset) >= deltaToPreviousTransition) { -// return true; -// } -// } -// return false; -// } - /** * Checks if the given {@link LocalDateTime} is within a gap. *
- * When switching from standard time to Daylight Savings Time there is - * typically a gap where a clock hour is missing. This method identifies - * whether the local datetime refers to such a gap. + * When switching into Daylight Savings Time there is typically a gap where a clock hour is missing. + * This method identifies whether the local datetime refers to such a gap. * * @param localDateTime the time to check, not null * @return true if the given datetime refers to a gap