Skip to content
This repository has been archived by the owner on Sep 19, 2023. It is now read-only.
/ jdk21 Public archive

Commit

Permalink
8310033: Clarify return value of Java Time compareTo methods
Browse files Browse the repository at this point in the history
Reviewed-by: naoto
Backport-of: 8650026ff16e5c5eff897f9fd39c0c35fd8b7367
  • Loading branch information
Roger Riggs committed Aug 1, 2023
1 parent 731b2e9 commit a228185
Show file tree
Hide file tree
Showing 17 changed files with 84 additions and 35 deletions.
3 changes: 2 additions & 1 deletion src/java.base/share/classes/java/time/Duration.java
Original file line number Diff line number Diff line change
Expand Up @@ -1419,7 +1419,8 @@ public Duration truncatedTo(TemporalUnit unit) {
* It is "consistent with equals", as defined by {@link Comparable}.
*
* @param otherDuration the other duration to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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}
*/
@Override
public int compareTo(Duration otherDuration) {
Expand Down
5 changes: 4 additions & 1 deletion src/java.base/share/classes/java/time/Instant.java
Original file line number Diff line number Diff line change
Expand Up @@ -1272,8 +1272,11 @@ public long toEpochMilli() {
* It is "consistent with equals", as defined by {@link Comparable}.
*
* @param otherInstant the other instant to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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}
* @throws NullPointerException if otherInstant is null
* @see #isBefore
* @see #isAfter
*/
@Override
public int compareTo(Instant otherInstant) {
Expand Down
8 changes: 6 additions & 2 deletions src/java.base/share/classes/java/time/LocalDate.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -1988,7 +1988,11 @@ public long toEpochSecond(LocalTime time, ZoneOffset offset) {
* chronology is also considered, see {@link java.time.chrono.ChronoLocalDate#compareTo}.
*
* @param other the other date to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
* @see #isBefore
* @see #isAfter
*/
@Override // override for Javadoc and performance
public int compareTo(ChronoLocalDate other) {
Expand Down
8 changes: 6 additions & 2 deletions src/java.base/share/classes/java/time/LocalDateTime.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -1807,7 +1807,11 @@ public ZonedDateTime atZone(ZoneId zone) {
* chronology is also considered, see {@link ChronoLocalDateTime#compareTo}.
*
* @param other the other date-time to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
* @see #isBefore
* @see #isAfter
*/
@Override // override for Javadoc and performance
public int compareTo(ChronoLocalDateTime<?> other) {
Expand Down
7 changes: 5 additions & 2 deletions src/java.base/share/classes/java/time/LocalTime.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -1531,7 +1531,10 @@ public long toEpochSecond(LocalDate date, ZoneOffset offset) {
* It is "consistent with equals", as defined by {@link Comparable}.
*
* @param other the other time to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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}
* @see #isBefore
* @see #isAfter
*/
@Override
public int compareTo(LocalTime other) {
Expand Down
7 changes: 5 additions & 2 deletions src/java.base/share/classes/java/time/MonthDay.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -675,7 +675,10 @@ public LocalDate atYear(int year) {
* It is "consistent with equals", as defined by {@link Comparable}.
*
* @param other the other month-day to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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}
* @see #isBefore
* @see #isAfter
*/
@Override
public int compareTo(MonthDay other) {
Expand Down
10 changes: 7 additions & 3 deletions src/java.base/share/classes/java/time/OffsetDateTime.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -169,7 +169,8 @@ public static Comparator<OffsetDateTime> timeLineOrder() {
*
* @param datetime1 the first date-time to compare, not null
* @param datetime2 the other date-time to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @return the comparator value, that is less than zero if {@code datetime1} is before {@code datetime2},
* zero if they are equal, greater than zero if {@code datetime1} is after {@code datetime2}
*/
private static int compareInstant(OffsetDateTime datetime1, OffsetDateTime datetime2) {
if (datetime1.getOffset().equals(datetime2.getOffset())) {
Expand Down Expand Up @@ -1801,7 +1802,10 @@ public long toEpochSecond() {
* consistent with {@code equals()}.
*
* @param other the other date-time to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
* @see #isBefore
* @see #isAfter
*/
@Override
public int compareTo(OffsetDateTime other) {
Expand Down
8 changes: 6 additions & 2 deletions src/java.base/share/classes/java/time/OffsetTime.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -1281,7 +1281,11 @@ public long toEpochSecond(LocalDate date) {
* use {@link ChronoField#NANO_OF_DAY} as a comparator.
*
* @param other the other time to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
* @see #isBefore
* @see #isAfter
*/
@Override
public int compareTo(OffsetTime other) {
Expand Down
7 changes: 5 additions & 2 deletions src/java.base/share/classes/java/time/Year.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -1018,7 +1018,10 @@ public LocalDate atMonthDay(MonthDay monthDay) {
* It is "consistent with equals", as defined by {@link Comparable}.
*
* @param other the other year to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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}
* @see #isBefore
* @see #isAfter
*/
@Override
public int compareTo(Year other) {
Expand Down
7 changes: 5 additions & 2 deletions src/java.base/share/classes/java/time/YearMonth.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -1122,7 +1122,10 @@ public LocalDate atEndOfMonth() {
* It is "consistent with equals", as defined by {@link Comparable}.
*
* @param other the other year-month to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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}
* @see #isBefore
* @see #isAfter
*/
@Override
public int compareTo(YearMonth other) {
Expand Down
4 changes: 3 additions & 1 deletion src/java.base/share/classes/java/time/ZoneOffset.java
Original file line number Diff line number Diff line change
Expand Up @@ -714,7 +714,9 @@ public Temporal adjustInto(Temporal temporal) {
* The comparison is "consistent with equals", as defined by {@link Comparable}.
*
* @param other the other date to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
* @throws NullPointerException if {@code other} is null
*/
@Override
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -656,7 +656,7 @@ void addFieldValue(Map<TemporalField, Long> fieldValues, ChronoField field, long
* Subclasses must compare any additional state that they store.
*
* @param other the other chronology to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @return the comparator value, that is this ID string compared with the {@code other}'s ID string
*/
@Override
public int compareTo(Chronology other) {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -700,7 +700,11 @@ default long toEpochDay() {
* This default implementation performs the comparison defined above.
*
* @param other the other date to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
* @see #isBefore
* @see #isAfter
*/
@Override
default int compareTo(ChronoLocalDate other) {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -500,7 +500,11 @@ default long toEpochSecond(ZoneOffset offset) {
* This default implementation performs the comparison defined above.
*
* @param other the other date-time to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
* @see #isBefore
* @see #isAfter
*/
@Override
default int compareTo(ChronoLocalDateTime<?> other) {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -569,7 +569,11 @@ default long toEpochSecond() {
* This default implementation performs the comparison defined above.
*
* @param other the other date-time to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
* @see #isBefore
* @see #isAfter
*/
@Override
default int compareTo(ChronoZonedDateTime<?> other) {
Expand Down
6 changes: 4 additions & 2 deletions src/java.base/share/classes/java/time/chrono/Chronology.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -807,7 +807,9 @@ default boolean isIsoBased() {
* It is "consistent with equals", as defined by {@link Comparable}.
*
* @param other the other chronology to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
*/
@Override
int compareTo(Chronology other);
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
Expand Down Expand Up @@ -399,12 +399,13 @@ List<ZoneOffset> getValidOffsets() {
* This compares the instants of each transition.
* The offsets are ignored, making this order inconsistent with equals.
*
* @param transition the transition to compare to, not null
* @return the comparator value, negative if less, positive if greater
* @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
*/
@Override
public int compareTo(ZoneOffsetTransition transition) {
return Long.compare(epochSecond, transition.epochSecond);
public int compareTo(ZoneOffsetTransition otherTransition) {
return Long.compare(epochSecond, otherTransition.epochSecond);
}

//-----------------------------------------------------------------------
Expand Down

1 comment on commit a228185

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.