Skip to content

Commit

Permalink
8310033: Clarify return value of Java Time compareTo methods
Browse files Browse the repository at this point in the history
Reviewed-by: bpb, scolebourne, prappo, naoto
  • Loading branch information
Roger Riggs committed Jul 27, 2023
1 parent 25058cd commit 8650026
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

3 comments on commit 8650026

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

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

@RogerRiggs
Copy link
Contributor

Choose a reason for hiding this comment

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

/backport jdk21
A java.time doc-only change for JDK 21; the CSR review included consideration for JDK 21.

@openjdk
Copy link

@openjdk openjdk bot commented on 8650026 Jul 31, 2023

Choose a reason for hiding this comment

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

@RogerRiggs the backport was successfully created on the branch RogerRiggs-backport-8650026f in my personal fork of openjdk/jdk21. To create a pull request with this backport targeting openjdk/jdk21:master, just click the following link:

➡️ Create pull request

The title of the pull request is automatically filled in correctly and below you find a suggestion for the pull request body:

Hi all,

This pull request contains a backport of commit 8650026f from the openjdk/jdk repository.

The commit being backported was authored by Roger Riggs on 27 Jul 2023 and was reviewed by Brian Burkhalter, Stephen Colebourne, Pavel Rappo and Naoto Sato.

Thanks!

If you need to update the source branch of the pull then run the following commands in a local clone of your personal fork of openjdk/jdk21:

$ git fetch https://github.com/openjdk-bots/jdk21.git RogerRiggs-backport-8650026f:RogerRiggs-backport-8650026f
$ git checkout RogerRiggs-backport-8650026f
# make changes
$ git add paths/to/changed/files
$ git commit --message 'Describe additional changes made'
$ git push https://github.com/openjdk-bots/jdk21.git RogerRiggs-backport-8650026f

Please sign in to comment.