Summary

In the java.time classes that are Comparable, clarify the descriptions of the return value of the compareTo method to use appropriate terminology describing the relationship between the values on the timeline.

Problem

The current descriptions of java.time classes that are Comparable and implement the compareTo method do not use familiar terminology to describe the return value for the relationship between the values on the timeline. For example, using "before" and "after" can make it easier to understand the relationship between two Instants on the timeline. The behavior is unchanged, descriptions are clarified to be easy to read and understand.

Solution

Update the description of the return value of compareTo methods to map the return value that is less than zero, equal to zero, and greater than zero to the appropriate class specific relative terminology. The argument name in ZoneOffsetTransition.compareTo is updated to make the description easier to read.

The compete patch is attached as time-july-21.patch.

Specification

The descriptions of the return value of the compareTo(Object) methods in java.time classes are updated as follows:

• java.time.Duration

  public int compareTo(Duration otherDuration)

     * @return the comparator value, that is less than zero if this duration is less than {@code otherDuration},
     *          zero if they are equal, greater than zero if this duration is greater than {@code otherDuration}

• java.time.Instant

  public int compareTo(Instant otherInstant)

     * @return the comparator value, that is less than zero if this instant is before {@code otherInstant},
     *          zero if they are equal, or greater than zero if this instant is after {@code otherInstant}

• java.time.LocalDate

  public int compareTo(ChronoLocalDate other)

     * @return the comparator value, that is the comparison of this local date with
     *          the {@code other} local date and this chronology with the {@code other} chronology,
     *          in order, returning the first non-zero result, and otherwise returning zero

• java.time.LocalDateTime

  public int compareTo(ChronoLocalDateTime<?> other)

     * @return the comparator value, that is the comparison of this local date-time with
     *          the {@code other} local date-time and this chronology with the {@code other} chronology,
     *          in order, returning the first non-zero result, and otherwise returning zero

• java.time.LocalTime

  public int compareTo(LocalTime other)

     * @return the comparator value, that is less than zero if this is before {@code other},
     *          zero if they are equal, or greater than zero if this is after {@code other}

• java.time.MonthDay

  public int compareTo(MonthDay other)

     * @return the comparator value, that is less than zero if this is before {@code other},
     *          zero if they are equal, greater than zero if this is after {@code other}

• java.time.OffsetDateTime

  public int compareTo(OffsetDateTime other)

     * @return the comparator value, that is the comparison with the {@code other}'s instant, if they are not equal;
     *          and if equal to the {@code other}'s instant, the comparison of the {@code other}'s local date-time

• java.time.OffsetTime

  public int compareTo(OffsetTime other)

     * @return the comparator value, that is the comparison of the UTC equivalent {@code other} instant,
     *          if they are not equal, and if the UTC equivalent {@code other} instant is equal,
     *          the comparison of this local time with {@code other} local time

• java.time.Year

  public int compareTo(Year other)

     * @return the comparator value, that is less than zero if this is before {@code other},
     *          zero if they are equal, or greater than zero if this is after {@code other}

• java.time.YearMonth

  public int compareTo(YearMonth other)

     * @return the comparator value, that is less than zero if this is before {@code other},
     *          zero if they are equal, greater than zero if this is after {@code other}

• java.time.ZoneOffset

  public int compareTo(ZoneOffset other)

     * @return the comparator value, that is less than zero if this totalSeconds is
     *          less than {@code other} totalSeconds, zero if they are equal,
     *          greater than zero if this totalSeconds is greater than {@code other} totalSeconds

• java.time.chrono.AbstractChronology

  public int compareTo(Chronology other)

     * @return the comparator value, that is this ID string compared with the {@code other}'s ID string

• java.time.chrono.ChronoLocalDate

  default int compareTo(ChronoLocalDate other)

     * @return the comparator value, that is the comparison of this local date with
     *          the {@code other} local date and this chronology with the {@code other} chronology,
     *          in order, returning the first non-zero result, and otherwise returning zero

• java.time.chrono.ChronoLocalDateTime

  default int compareTo(ChronoLocalDateTime<?> other)

     * @return the comparator value, that is the comparison of this local date-time with
     *          the {@code other} local date-time and this chronology with the {@code other} chronology,
     *          in order, returning the first non-zero result, and otherwise returning zero

• java.time.chrono.ChronoZonedDateTime

  default int compareTo(ChronoZonedDateTime<?> other)

     * @return the comparator value, that is the comparison of this with the {@code other} values for the instant,
     *          the local date-time, the zone ID, and the chronology, in order, returning the first non-zero result,
     *          and otherwise returning zero

• java.time.chrono.Chronology

  int compareTo(Chronology other)

     * @return the comparator value, that is this ID string compared with the {@code other}'s ID string
     *          unless the ID strings are equal and
     *          the chronology distinguishes instances using additional information

• java.time.zone.ZoneOffsetTransition

  public int compareTo(ZoneOffsetTransition otherTransition)

     * @param otherTransition  the transition to compare to, not null
     * @return the comparator value, that is the comparison of this transition instant
     *          with {@code otherTransition} instant
    public int compareTo(ZoneOffsetTransition otherTransition) {...}