diff options
Diffstat (limited to 'core')
| -rw-r--r-- | core/java/android/text/format/Time.java | 33 |
1 files changed, 30 insertions, 3 deletions
diff --git a/core/java/android/text/format/Time.java b/core/java/android/text/format/Time.java index aa6ad20..3c90ab6 100644 --- a/core/java/android/text/format/Time.java +++ b/core/java/android/text/format/Time.java @@ -212,13 +212,15 @@ public class Time { * <p> * If "ignoreDst" is true, then this method sets the "isDst" field to -1 * (the "unknown" value) before normalizing. It then computes the - * correct value for "isDst". + * time in milliseconds and sets the correct value for "isDst" if the + * fields resolve to a valid date / time. * * <p> * See {@link #toMillis(boolean)} for more information about when to - * use <tt>true</tt> or <tt>false</tt> for "ignoreDst". + * use <tt>true</tt> or <tt>false</tt> for "ignoreDst" and when {@code -1} + * might be returned. * - * @return the UTC milliseconds since the epoch + * @return the UTC milliseconds since the epoch, or {@code -1} */ public long normalize(boolean ignoreDst) { calculator.copyFieldsFromTime(this); @@ -314,6 +316,11 @@ public class Time { * a} is less than {@code b}, a positive number if {@code a} is greater than * {@code b}, or 0 if they are equal. * + * <p> + * This method can return an incorrect answer when the date / time fields of + * either {@code Time} have been set to a local time that contradicts the + * available timezone information. + * * @param a first {@code Time} instance to compare * @param b second {@code Time} instance to compare * @throws NullPointerException if either argument is {@code null} @@ -727,6 +734,14 @@ public class Time { * <p> * You should also use <tt>toMillis(false)</tt> if you want * to read back the same milliseconds that you set with {@link #set(long)} + * + * <p> + * This method can return {@code -1} when the date / time fields have been + * set to a local time that conflicts with available timezone information. + * For example, when daylight savings transitions cause an hour to be + * skipped: times within that hour will return {@code -1} if isDst = + * {@code -1}. + * * or {@link #set(Time)} or after parsing a date string. */ public long toMillis(boolean ignoreDst) { @@ -822,6 +837,10 @@ public class Time { * Returns true if the time represented by this Time object occurs before * the given time. * + * <p> + * Equivalent to {@code Time.compare(this, that) < 0}. See + * {@link #compare(Time, Time)} for details. + * * @param that a given Time object to compare against * @return true if this time is less than the given time */ @@ -834,6 +853,10 @@ public class Time { * Returns true if the time represented by this Time object occurs after * the given time. * + * <p> + * Equivalent to {@code Time.compare(this, that) > 0}. See + * {@link #compare(Time, Time)} for details. + * * @param that a given Time object to compare against * @return true if this time is greater than the given time */ @@ -914,6 +937,10 @@ public class Time { * Returns true if the day of the given time is the epoch on the Julian Calendar * (January 1, 1970 on the Gregorian calendar). * + * <p> + * This method can return an incorrect answer when the date / time fields have + * been set to a local time that contradicts the available timezone information. + * * @param time the time to test * @return true if epoch. */ |