diff --git a/src/java.base/share/classes/java/time/Duration.java b/src/java.base/share/classes/java/time/Duration.java
index 925e9c2f6a9..c1894e2db5a 100644
--- a/src/java.base/share/classes/java/time/Duration.java
+++ b/src/java.base/share/classes/java/time/Duration.java
@@ -1413,19 +1413,20 @@ public final class Duration
//-----------------------------------------------------------------------
/**
* Compares this duration to the specified {@code Duration}.
* <p>
* The comparison is based on the total length of the durations.
* 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) {
int cmp = Long.compare(seconds, otherDuration.seconds);
if (cmp != 0) {
return cmp;
}
return nanos - otherDuration.nanos;
}
diff --git a/src/java.base/share/classes/java/time/Instant.java b/src/java.base/share/classes/java/time/Instant.java
index 6b01d4d4323..37dd9f8d2ac 100644
--- a/src/java.base/share/classes/java/time/Instant.java
+++ b/src/java.base/share/classes/java/time/Instant.java
@@ -1266,20 +1266,23 @@ public final class Instant
//-----------------------------------------------------------------------
/**
* Compares this instant to the specified instant.
* <p>
* The comparison is based on the time-line position of the instants.
* 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) {
int cmp = Long.compare(seconds, otherInstant.seconds);
if (cmp != 0) {
return cmp;
}
return nanos - otherInstant.nanos;
}
diff --git a/src/java.base/share/classes/java/time/LocalDate.java b/src/java.base/share/classes/java/time/LocalDate.java
index d7a63c20a5d..59f9fcd6413 100644
--- a/src/java.base/share/classes/java/time/LocalDate.java
+++ b/src/java.base/share/classes/java/time/LocalDate.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -1982,19 +1982,22 @@ public final class LocalDate
* The comparison is primarily based on the date, from earliest to latest.
* It is "consistent with equals", as defined by {@link Comparable}.
* <p>
* If all the dates being compared are instances of {@code LocalDate},
* then the comparison will be entirely based on the date.
* If some dates being compared are in different chronologies, then the
* 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 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 // override for Javadoc and performance
public int compareTo(ChronoLocalDate other) {
if (other instanceof LocalDate) {
return compareTo0((LocalDate) other);
}
return ChronoLocalDate.super.compareTo(other);
}
diff --git a/src/java.base/share/classes/java/time/LocalDateTime.java b/src/java.base/share/classes/java/time/LocalDateTime.java
index 51d88711aba..4e93004722f 100644
--- a/src/java.base/share/classes/java/time/LocalDateTime.java
+++ b/src/java.base/share/classes/java/time/LocalDateTime.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -1801,19 +1801,22 @@ public final class LocalDateTime
* The comparison is primarily based on the date-time, from earliest to latest.
* It is "consistent with equals", as defined by {@link Comparable}.
* <p>
* If all the date-times being compared are instances of {@code LocalDateTime},
* then the comparison will be entirely based on the date-time.
* If some dates being compared are in different chronologies, then the
* 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 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 // override for Javadoc and performance
public int compareTo(ChronoLocalDateTime<?> other) {
if (other instanceof LocalDateTime) {
return compareTo0((LocalDateTime) other);
}
return ChronoLocalDateTime.super.compareTo(other);
}
diff --git a/src/java.base/share/classes/java/time/LocalTime.java b/src/java.base/share/classes/java/time/LocalTime.java
index 42993d8da7c..499dca627e2 100644
--- a/src/java.base/share/classes/java/time/LocalTime.java
+++ b/src/java.base/share/classes/java/time/LocalTime.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -1525,19 +1525,22 @@ public final class LocalTime
//-----------------------------------------------------------------------
/**
* Compares this time to another time.
* <p>
* The comparison is based on the time-line position of the local times within a day.
* 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) {
int cmp = Integer.compare(hour, other.hour);
if (cmp == 0) {
cmp = Integer.compare(minute, other.minute);
if (cmp == 0) {
cmp = Integer.compare(second, other.second);
if (cmp == 0) {
diff --git a/src/java.base/share/classes/java/time/MonthDay.java b/src/java.base/share/classes/java/time/MonthDay.java
index a95c7b4ad6f..acb3087a5e5 100644
--- a/src/java.base/share/classes/java/time/MonthDay.java
+++ b/src/java.base/share/classes/java/time/MonthDay.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -669,19 +669,22 @@ public final class MonthDay
//-----------------------------------------------------------------------
/**
* Compares this month-day to another month-day.
* <p>
* The comparison is based first on value of the month, then on the value of the day.
* 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) {
int cmp = (month - other.month);
if (cmp == 0) {
cmp = (day - other.day);
}
return cmp;
}
diff --git a/src/java.base/share/classes/java/time/OffsetDateTime.java b/src/java.base/share/classes/java/time/OffsetDateTime.java
index e9a3a3ebe03..bd75fffb24e 100644
--- a/src/java.base/share/classes/java/time/OffsetDateTime.java
+++ b/src/java.base/share/classes/java/time/OffsetDateTime.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -163,19 +163,20 @@ public final class OffsetDateTime
return OffsetDateTime::compareInstant;
}
/**
* Compares this {@code OffsetDateTime} to another date-time.
* The comparison is based on the instant.
*
* @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())) {
return datetime1.toLocalDateTime().compareTo(datetime2.toLocalDateTime());
}
int cmp = Long.compare(datetime1.toEpochSecond(), datetime2.toEpochSecond());
if (cmp == 0) {
cmp = datetime1.toLocalTime().getNano() - datetime2.toLocalTime().getNano();
}
@@ -1795,19 +1796,22 @@ public final class OffsetDateTime
* <li>{@code 2008-12-03T12:00+01:00}</li>
* <li>{@code 2008-12-03T12:30+01:00}</li>
* </ol>
* Values #2 and #3 represent the same instant on the time-line.
* When two values represent the same instant, the local date-time is compared
* to distinguish them. This step is needed to make the ordering
* 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) {
int cmp = getOffset().compareTo(other.getOffset());
if (cmp != 0) {
cmp = Long.compare(toEpochSecond(), other.toEpochSecond());
if (cmp == 0) {
cmp = toLocalTime().getNano() - other.toLocalTime().getNano();
}
diff --git a/src/java.base/share/classes/java/time/OffsetTime.java b/src/java.base/share/classes/java/time/OffsetTime.java
index d3c43a0d9dd..e7ce5877b5f 100644
--- a/src/java.base/share/classes/java/time/OffsetTime.java
+++ b/src/java.base/share/classes/java/time/OffsetTime.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -1275,19 +1275,23 @@ public final class OffsetTime
* Values #2 and #3 represent the same instant on the time-line.
* When two values represent the same instant, the local time is compared
* to distinguish them. This step is needed to make the ordering
* consistent with {@code equals()}.
* <p>
* To compare the underlying local time of two {@code TemporalAccessor} instances,
* 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 date-time with {@code other} local date-time
+ * @see #isBefore
+ * @see #isAfter
*/
@Override
public int compareTo(OffsetTime other) {
if (offset.equals(other.offset)) {
return time.compareTo(other.time);
}
int compare = Long.compare(toEpochNano(), other.toEpochNano());
if (compare == 0) {
compare = time.compareTo(other.time);
diff --git a/src/java.base/share/classes/java/time/Year.java b/src/java.base/share/classes/java/time/Year.java
index d73560884e1..df4707e8b32 100644
--- a/src/java.base/share/classes/java/time/Year.java
+++ b/src/java.base/share/classes/java/time/Year.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -1012,19 +1012,22 @@ public final class Year
//-----------------------------------------------------------------------
/**
* Compares this year to another year.
* <p>
* The comparison is based on the value of the 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) {
return year - other.year;
}
/**
* Checks if this year is after the specified year.
*
diff --git a/src/java.base/share/classes/java/time/YearMonth.java b/src/java.base/share/classes/java/time/YearMonth.java
index 90f5d08210c..201c01a2193 100644
--- a/src/java.base/share/classes/java/time/YearMonth.java
+++ b/src/java.base/share/classes/java/time/YearMonth.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -1116,19 +1116,22 @@ public final class YearMonth
//-----------------------------------------------------------------------
/**
* Compares this year-month to another year-month.
* <p>
* The comparison is based first on the value of the year, then on the value of the month.
* 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) {
int cmp = (year - other.year);
if (cmp == 0) {
cmp = (month - other.month);
}
return cmp;
}
diff --git a/src/java.base/share/classes/java/time/ZoneOffset.java b/src/java.base/share/classes/java/time/ZoneOffset.java
index 6120898ebda..14ac5fcfb6b 100644
--- a/src/java.base/share/classes/java/time/ZoneOffset.java
+++ b/src/java.base/share/classes/java/time/ZoneOffset.java
@@ -708,19 +708,21 @@ public final class ZoneOffset
* Compares this offset to another offset in descending order.
* <p>
* The offsets are compared in the order that they occur for the same time
* of day around the world. Thus, an offset of {@code +10:00} comes before an
* offset of {@code +09:00} and so on down to {@code -18:00}.
* <p>
* 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
public int compareTo(ZoneOffset other) {
// abs(totalSeconds) <= MAX_SECONDS, so no overflow can happen here
return other.totalSeconds - totalSeconds;
}
//-----------------------------------------------------------------------
diff --git a/src/java.base/share/classes/java/time/chrono/AbstractChronology.java b/src/java.base/share/classes/java/time/chrono/AbstractChronology.java
index a663d13a3a6..b506826fdef 100644
--- a/src/java.base/share/classes/java/time/chrono/AbstractChronology.java
+++ b/src/java.base/share/classes/java/time/chrono/AbstractChronology.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -650,19 +650,19 @@ public abstract class AbstractChronology implements Chronology {
* The comparison order first by the chronology ID string, then by any
* additional information specific to the subclass.
* It is "consistent with equals", as defined by {@link Comparable}.
*
* @implSpec
* This implementation compares the chronology ID.
* 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) {
return getId().compareTo(other.getId());
}
/**
* Checks if this chronology is equal to another chronology.
* <p>
diff --git a/src/java.base/share/classes/java/time/chrono/ChronoLocalDate.java b/src/java.base/share/classes/java/time/chrono/ChronoLocalDate.java
index 9d90ade63da..43be43a742e 100644
--- a/src/java.base/share/classes/java/time/chrono/ChronoLocalDate.java
+++ b/src/java.base/share/classes/java/time/chrono/ChronoLocalDate.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -694,19 +694,22 @@ public interface ChronoLocalDate
* <p>
* If all the date objects being compared are in the same chronology, then the
* additional chronology stage is not required and only the local date is used.
* To compare the dates of two {@code TemporalAccessor} instances, including dates
* in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
* <p>
* 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 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
default int compareTo(ChronoLocalDate other) {
int cmp = Long.compare(toEpochDay(), other.toEpochDay());
if (cmp == 0) {
cmp = getChronology().compareTo(other.getChronology());
}
return cmp;
}
diff --git a/src/java.base/share/classes/java/time/chrono/ChronoLocalDateTime.java b/src/java.base/share/classes/java/time/chrono/ChronoLocalDateTime.java
index ed0da48b688..73b3a1e8a88 100644
--- a/src/java.base/share/classes/java/time/chrono/ChronoLocalDateTime.java
+++ b/src/java.base/share/classes/java/time/chrono/ChronoLocalDateTime.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -494,19 +494,23 @@ public interface ChronoLocalDateTime<D extends ChronoLocalDate>
* When two values represent the same date-time, the chronology ID is compared to distinguish them.
* This step is needed to make the ordering "consistent with equals".
* <p>
* If all the date-time objects being compared are in the same chronology, then the
* additional chronology stage is not required and only the local date-time is used.
* <p>
* 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) {
int cmp = toLocalDate().compareTo(other.toLocalDate());
if (cmp == 0) {
cmp = toLocalTime().compareTo(other.toLocalTime());
if (cmp == 0) {
cmp = getChronology().compareTo(other.getChronology());
}
diff --git a/src/java.base/share/classes/java/time/chrono/ChronoZonedDateTime.java b/src/java.base/share/classes/java/time/chrono/ChronoZonedDateTime.java
index fb65c9d8a7b..8892bc471b6 100644
--- a/src/java.base/share/classes/java/time/chrono/ChronoZonedDateTime.java
+++ b/src/java.base/share/classes/java/time/chrono/ChronoZonedDateTime.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -563,19 +563,23 @@ public interface ChronoZonedDateTime<D extends ChronoLocalDate>
* then on the zone ID, then on the chronology.
* It is "consistent with equals", as defined by {@link Comparable}.
* <p>
* If all the date-time objects being compared are in the same chronology, then the
* additional chronology stage is not required.
* <p>
* 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) {
int cmp = Long.compare(toEpochSecond(), other.toEpochSecond());
if (cmp == 0) {
cmp = toLocalTime().getNano() - other.toLocalTime().getNano();
if (cmp == 0) {
cmp = toLocalDateTime().compareTo(other.toLocalDateTime());
if (cmp == 0) {
diff --git a/src/java.base/share/classes/java/time/chrono/Chronology.java b/src/java.base/share/classes/java/time/chrono/Chronology.java
index a4915def75a..f573155ae21 100644
--- a/src/java.base/share/classes/java/time/chrono/Chronology.java
+++ b/src/java.base/share/classes/java/time/chrono/Chronology.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -801,19 +801,21 @@ public interface Chronology extends Comparable<Chronology> {
//-----------------------------------------------------------------------
/**
* Compares this chronology to another chronology.
* <p>
* The comparison order first by the chronology ID string, then by any
* additional information specific to the subclass.
* 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);
/**
* Checks if this chronology is equal to another chronology.
* <p>
* The comparison is based on the entire state of the object.
*
diff --git a/src/java.base/share/classes/java/time/zone/ZoneOffsetTransition.java b/src/java.base/share/classes/java/time/zone/ZoneOffsetTransition.java
index 3119458ec8d..f5d27a0cae0 100644
--- a/src/java.base/share/classes/java/time/zone/ZoneOffsetTransition.java
+++ b/src/java.base/share/classes/java/time/zone/ZoneOffsetTransition.java
@@ -1,11 +1,11 @@
/*
- * 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
@@ -393,24 +393,25 @@ public final class ZoneOffsetTransition
}
//-----------------------------------------------------------------------
/**
* Compares this transition to another based on the transition instant.
* <p>
* 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);
}
//-----------------------------------------------------------------------
/**
* Checks if this object equals another.
* <p>
* The entire state of the object is compared.
*
* @param other the other object to compare to, null returns false