Skip to content

Commit 8650026

Browse files
author
Roger Riggs
committedJul 27, 2023
8310033: Clarify return value of Java Time compareTo methods
Reviewed-by: bpb, scolebourne, prappo, naoto
·
jdk-25+17jdk-22-ga
1 parent 25058cd commit 8650026

17 files changed

+84
-35
lines changed
 

‎src/java.base/share/classes/java/time/Duration.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -1419,7 +1419,8 @@ public Duration truncatedTo(TemporalUnit unit) {
14191419
* It is "consistent with equals", as defined by {@link Comparable}.
14201420
*
14211421
* @param otherDuration the other duration to compare to, not null
1422-
* @return the comparator value, negative if less, positive if greater
1422+
* @return the comparator value, that is less than zero if this duration is less than {@code otherDuration},
1423+
* zero if they are equal, greater than zero if this duration is greater than {@code otherDuration}
14231424
*/
14241425
@Override
14251426
public int compareTo(Duration otherDuration) {

‎src/java.base/share/classes/java/time/Instant.java

+4-1
Original file line numberDiff line numberDiff line change
@@ -1272,8 +1272,11 @@ public long toEpochMilli() {
12721272
* It is "consistent with equals", as defined by {@link Comparable}.
12731273
*
12741274
* @param otherInstant the other instant to compare to, not null
1275-
* @return the comparator value, negative if less, positive if greater
1275+
* @return the comparator value, that is less than zero if this instant is before {@code otherInstant},
1276+
* zero if they are equal, or greater than zero if this instant is after {@code otherInstant}
12761277
* @throws NullPointerException if otherInstant is null
1278+
* @see #isBefore
1279+
* @see #isAfter
12771280
*/
12781281
@Override
12791282
public int compareTo(Instant otherInstant) {

‎src/java.base/share/classes/java/time/LocalDate.java

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -1988,7 +1988,11 @@ public long toEpochSecond(LocalTime time, ZoneOffset offset) {
19881988
* chronology is also considered, see {@link java.time.chrono.ChronoLocalDate#compareTo}.
19891989
*
19901990
* @param other the other date to compare to, not null
1991-
* @return the comparator value, negative if less, positive if greater
1991+
* @return the comparator value, that is the comparison of this local date with
1992+
* the {@code other} local date and this chronology with the {@code other} chronology,
1993+
* in order, returning the first non-zero result, and otherwise returning zero
1994+
* @see #isBefore
1995+
* @see #isAfter
19921996
*/
19931997
@Override // override for Javadoc and performance
19941998
public int compareTo(ChronoLocalDate other) {

‎src/java.base/share/classes/java/time/LocalDateTime.java

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -1807,7 +1807,11 @@ public ZonedDateTime atZone(ZoneId zone) {
18071807
* chronology is also considered, see {@link ChronoLocalDateTime#compareTo}.
18081808
*
18091809
* @param other the other date-time to compare to, not null
1810-
* @return the comparator value, negative if less, positive if greater
1810+
* @return the comparator value, that is the comparison of this local date-time with
1811+
* the {@code other} local date-time and this chronology with the {@code other} chronology,
1812+
* in order, returning the first non-zero result, and otherwise returning zero
1813+
* @see #isBefore
1814+
* @see #isAfter
18111815
*/
18121816
@Override // override for Javadoc and performance
18131817
public int compareTo(ChronoLocalDateTime<?> other) {

‎src/java.base/share/classes/java/time/LocalTime.java

+5-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -1531,7 +1531,10 @@ public long toEpochSecond(LocalDate date, ZoneOffset offset) {
15311531
* It is "consistent with equals", as defined by {@link Comparable}.
15321532
*
15331533
* @param other the other time to compare to, not null
1534-
* @return the comparator value, negative if less, positive if greater
1534+
* @return the comparator value, that is less than zero if this is before {@code other},
1535+
* zero if they are equal, or greater than zero if this is after {@code other}
1536+
* @see #isBefore
1537+
* @see #isAfter
15351538
*/
15361539
@Override
15371540
public int compareTo(LocalTime other) {

‎src/java.base/share/classes/java/time/MonthDay.java

+5-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -675,7 +675,10 @@ public LocalDate atYear(int year) {
675675
* It is "consistent with equals", as defined by {@link Comparable}.
676676
*
677677
* @param other the other month-day to compare to, not null
678-
* @return the comparator value, negative if less, positive if greater
678+
* @return the comparator value, that is less than zero if this is before {@code other},
679+
* zero if they are equal, greater than zero if this is after {@code other}
680+
* @see #isBefore
681+
* @see #isAfter
679682
*/
680683
@Override
681684
public int compareTo(MonthDay other) {

‎src/java.base/share/classes/java/time/OffsetDateTime.java

+7-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -169,7 +169,8 @@ public static Comparator<OffsetDateTime> timeLineOrder() {
169169
*
170170
* @param datetime1 the first date-time to compare, not null
171171
* @param datetime2 the other date-time to compare to, not null
172-
* @return the comparator value, negative if less, positive if greater
172+
* @return the comparator value, that is less than zero if {@code datetime1} is before {@code datetime2},
173+
* zero if they are equal, greater than zero if {@code datetime1} is after {@code datetime2}
173174
*/
174175
private static int compareInstant(OffsetDateTime datetime1, OffsetDateTime datetime2) {
175176
if (datetime1.getOffset().equals(datetime2.getOffset())) {
@@ -1801,7 +1802,10 @@ public long toEpochSecond() {
18011802
* consistent with {@code equals()}.
18021803
*
18031804
* @param other the other date-time to compare to, not null
1804-
* @return the comparator value, negative if less, positive if greater
1805+
* @return the comparator value, that is the comparison with the {@code other}'s instant, if they are not equal;
1806+
* and if equal to the {@code other}'s instant, the comparison of the {@code other}'s local date-time
1807+
* @see #isBefore
1808+
* @see #isAfter
18051809
*/
18061810
@Override
18071811
public int compareTo(OffsetDateTime other) {

‎src/java.base/share/classes/java/time/OffsetTime.java

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -1281,7 +1281,11 @@ public long toEpochSecond(LocalDate date) {
12811281
* use {@link ChronoField#NANO_OF_DAY} as a comparator.
12821282
*
12831283
* @param other the other time to compare to, not null
1284-
* @return the comparator value, negative if less, positive if greater
1284+
* @return the comparator value, that is the comparison of the UTC equivalent {@code other} instant,
1285+
* if they are not equal, and if the UTC equivalent {@code other} instant is equal,
1286+
* the comparison of this local time with {@code other} local time
1287+
* @see #isBefore
1288+
* @see #isAfter
12851289
*/
12861290
@Override
12871291
public int compareTo(OffsetTime other) {

‎src/java.base/share/classes/java/time/Year.java

+5-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -1018,7 +1018,10 @@ public LocalDate atMonthDay(MonthDay monthDay) {
10181018
* It is "consistent with equals", as defined by {@link Comparable}.
10191019
*
10201020
* @param other the other year to compare to, not null
1021-
* @return the comparator value, negative if less, positive if greater
1021+
* @return the comparator value, that is less than zero if this is before {@code other},
1022+
* zero if they are equal, or greater than zero if this is after {@code other}
1023+
* @see #isBefore
1024+
* @see #isAfter
10221025
*/
10231026
@Override
10241027
public int compareTo(Year other) {

‎src/java.base/share/classes/java/time/YearMonth.java

+5-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -1122,7 +1122,10 @@ public LocalDate atEndOfMonth() {
11221122
* It is "consistent with equals", as defined by {@link Comparable}.
11231123
*
11241124
* @param other the other year-month to compare to, not null
1125-
* @return the comparator value, negative if less, positive if greater
1125+
* @return the comparator value, that is less than zero if this is before {@code other},
1126+
* zero if they are equal, greater than zero if this is after {@code other}
1127+
* @see #isBefore
1128+
* @see #isAfter
11261129
*/
11271130
@Override
11281131
public int compareTo(YearMonth other) {

‎src/java.base/share/classes/java/time/ZoneOffset.java

+3-1
Original file line numberDiff line numberDiff line change
@@ -714,7 +714,9 @@ public Temporal adjustInto(Temporal temporal) {
714714
* The comparison is "consistent with equals", as defined by {@link Comparable}.
715715
*
716716
* @param other the other date to compare to, not null
717-
* @return the comparator value, negative if less, positive if greater
717+
* @return the comparator value, that is less than zero if this totalSeconds is
718+
* less than {@code other} totalSeconds, zero if they are equal,
719+
* greater than zero if this totalSeconds is greater than {@code other} totalSeconds
718720
* @throws NullPointerException if {@code other} is null
719721
*/
720722
@Override

‎src/java.base/share/classes/java/time/chrono/AbstractChronology.java

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -656,7 +656,7 @@ void addFieldValue(Map<TemporalField, Long> fieldValues, ChronoField field, long
656656
* Subclasses must compare any additional state that they store.
657657
*
658658
* @param other the other chronology to compare to, not null
659-
* @return the comparator value, negative if less, positive if greater
659+
* @return the comparator value, that is this ID string compared with the {@code other}'s ID string
660660
*/
661661
@Override
662662
public int compareTo(Chronology other) {

‎src/java.base/share/classes/java/time/chrono/ChronoLocalDate.java

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -700,7 +700,11 @@ default long toEpochDay() {
700700
* This default implementation performs the comparison defined above.
701701
*
702702
* @param other the other date to compare to, not null
703-
* @return the comparator value, negative if less, positive if greater
703+
* @return the comparator value, that is the comparison of this local date with
704+
* the {@code other} local date and this chronology with the {@code other} chronology,
705+
* in order, returning the first non-zero result, and otherwise returning zero
706+
* @see #isBefore
707+
* @see #isAfter
704708
*/
705709
@Override
706710
default int compareTo(ChronoLocalDate other) {

‎src/java.base/share/classes/java/time/chrono/ChronoLocalDateTime.java

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -500,7 +500,11 @@ default long toEpochSecond(ZoneOffset offset) {
500500
* This default implementation performs the comparison defined above.
501501
*
502502
* @param other the other date-time to compare to, not null
503-
* @return the comparator value, negative if less, positive if greater
503+
* @return the comparator value, that is the comparison of this local date-time with
504+
* the {@code other} local date-time and this chronology with the {@code other} chronology,
505+
* in order, returning the first non-zero result, and otherwise returning zero
506+
* @see #isBefore
507+
* @see #isAfter
504508
*/
505509
@Override
506510
default int compareTo(ChronoLocalDateTime<?> other) {

‎src/java.base/share/classes/java/time/chrono/ChronoZonedDateTime.java

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -569,7 +569,11 @@ default long toEpochSecond() {
569569
* This default implementation performs the comparison defined above.
570570
*
571571
* @param other the other date-time to compare to, not null
572-
* @return the comparator value, negative if less, positive if greater
572+
* @return the comparator value, that is the comparison of this with the {@code other} values for the instant,
573+
* the local date-time, the zone ID, and the chronology, in order, returning the first non-zero result,
574+
* and otherwise returning zero
575+
* @see #isBefore
576+
* @see #isAfter
573577
*/
574578
@Override
575579
default int compareTo(ChronoZonedDateTime<?> other) {

‎src/java.base/share/classes/java/time/chrono/Chronology.java

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -807,7 +807,9 @@ default boolean isIsoBased() {
807807
* It is "consistent with equals", as defined by {@link Comparable}.
808808
*
809809
* @param other the other chronology to compare to, not null
810-
* @return the comparator value, negative if less, positive if greater
810+
* @return the comparator value, that is this ID string compared with the {@code other}'s ID string
811+
* unless the ID strings are equal and
812+
* the chronology distinguishes instances using additional information
811813
*/
812814
@Override
813815
int compareTo(Chronology other);

‎src/java.base/share/classes/java/time/zone/ZoneOffsetTransition.java

+6-5
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -399,12 +399,13 @@ List<ZoneOffset> getValidOffsets() {
399399
* This compares the instants of each transition.
400400
* The offsets are ignored, making this order inconsistent with equals.
401401
*
402-
* @param transition the transition to compare to, not null
403-
* @return the comparator value, negative if less, positive if greater
402+
* @param otherTransition the transition to compare to, not null
403+
* @return the comparator value, that is the comparison of this transition instant
404+
* with {@code otherTransition} instant
404405
*/
405406
@Override
406-
public int compareTo(ZoneOffsetTransition transition) {
407-
return Long.compare(epochSecond, transition.epochSecond);
407+
public int compareTo(ZoneOffsetTransition otherTransition) {
408+
return Long.compare(epochSecond, otherTransition.epochSecond);
408409
}
409410

410411
//-----------------------------------------------------------------------

3 commit comments

Comments
 (3)

openjdk-notifier[bot] commented on Jul 27, 2023

@openjdk-notifier[bot]
openjdk-notifier[bot]
on Jul 27, 2023

Review

Issues

RogerRiggs commented on Jul 31, 2023

@RogerRiggs
RogerRiggs
on Jul 31, 2023
Contributor

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

openjdk[bot] commented on Jul 31, 2023

@openjdk[bot]
openjdk[bot]
on Jul 31, 2023

@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.