1berry/openjdk
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

8310033: Clarify return value of Java Time compareTo methods

Browse Source 
Reviewed-by: bpb, scolebourne, prappo, naoto
This commit is contained in:
Roger Riggs 2023-07-27 14:01:25 +00:00
parent 25058cd23a
commit 8650026ff1
17 changed files with 84 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/java.base/share/classes/java/time/Duration.java
View File

@ -1419,7 +1419,8 @@ public final class Duration
* 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) {

5
src/java.base/share/classes/java/time/Instant.java
View File

@ -1272,8 +1272,11 @@ public final class Instant
* 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) {

8
src/java.base/share/classes/java/time/LocalDate.java
View File

@ -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
@ -1988,7 +1988,11 @@ public final class LocalDate
* 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) {

8
src/java.base/share/classes/java/time/LocalDateTime.java
View File

@ -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
@ -1807,7 +1807,11 @@ public final class LocalDateTime
* 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) {

7
src/java.base/share/classes/java/time/LocalTime.java
View File

@ -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
@ -1531,7 +1531,10 @@ public final class LocalTime
* 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) {

7
src/java.base/share/classes/java/time/MonthDay.java
View File

@ -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
@ -675,7 +675,10 @@ public final class MonthDay
* 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) {

10
src/java.base/share/classes/java/time/OffsetDateTime.java
View File

@ -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
@ -169,7 +169,8 @@ public final class OffsetDateTime
*
* @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())) {
@ -1801,7 +1802,10 @@ public final class OffsetDateTime
* 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) {

8
src/java.base/share/classes/java/time/OffsetTime.java
View File

@ -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
@ -1281,7 +1281,11 @@ public final class OffsetTime
* 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) {

7
src/java.base/share/classes/java/time/Year.java
View File

@ -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
@ -1018,7 +1018,10 @@ public final class Year
* 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) {

7
src/java.base/share/classes/java/time/YearMonth.java
View File

@ -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
@ -1122,7 +1122,10 @@ public final class YearMonth
* 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) {

4
src/java.base/share/classes/java/time/ZoneOffset.java
View File

@ -714,7 +714,9 @@ public final class ZoneOffset
* 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

4
src/java.base/share/classes/java/time/chrono/AbstractChronology.java
View File

@ -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
@ -656,7 +656,7 @@ public abstract class AbstractChronology implements Chronology {
* 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) {

8
src/java.base/share/classes/java/time/chrono/ChronoLocalDate.java
View File

@ -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
@ -700,7 +700,11 @@ public interface ChronoLocalDate
* 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) {

8
src/java.base/share/classes/java/time/chrono/ChronoLocalDateTime.java
View File

@ -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
@ -500,7 +500,11 @@ public interface ChronoLocalDateTime<D extends ChronoLocalDate>
* 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) {

8
src/java.base/share/classes/java/time/chrono/ChronoZonedDateTime.java
View File

@ -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
@ -569,7 +569,11 @@ public interface ChronoZonedDateTime<D extends ChronoLocalDate>
* 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) {

6
src/java.base/share/classes/java/time/chrono/Chronology.java
View File

@ -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
@ -807,7 +807,9 @@ public interface Chronology extends Comparable<Chronology> {
* 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);

11
src/java.base/share/classes/java/time/zone/ZoneOffsetTransition.java
View File

@ -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
@ -399,12 +399,13 @@ public final class ZoneOffsetTransition
* 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);
}
//-----------------------------------------------------------------------