Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8310064

Clarify Java Time documentation of the return value of compareTo methods

    XMLWordPrintable

Details

    • CSR
    • Resolution: Approved
    • P4
    • 22
    • core-libs
    • None
    • behavioral
    • minimal
    • This is a doc-only change; the behavior is not changed.
    • Java API
    • SE

    Description

      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) {...}

      Attachments

        1. time-july-11.patch
          34 kB
        2. time-july-21.patch
          35 kB
        3. time-july-5.patch
          20 kB
        4. time-july-7.patch
          20 kB

        Issue Links

          Activity

            People

              rriggs Roger Riggs
              rriggs Roger Riggs
              Brian Burkhalter, Pavel Rappo
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: