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}. *

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

* 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..2649c098a5b 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,23 @@ 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}. *

* 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 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) { 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..024aa1dacbe 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,23 @@ 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}. *

* 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 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) { 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. *

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

* 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 *

  • {@code 2008-12-03T12:00+01:00}
    • *
  • {@code 2008-12-03T12:30+01:00}
    • * * 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..b9fe5e533d8 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()}. *

    * 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 time with {@code other} local 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. *

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

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

    * 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}. *

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

    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..5543c8a73bc 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,23 @@ public interface ChronoLocalDate *

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

    * 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) { 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 * 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". *

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

    * 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 * then on the zone ID, then on the chronology. * It is "consistent with equals", as defined by {@link Comparable}. *

    * If all the date-time objects being compared are in the same chronology, then the * additional chronology stage is not required. *

    * 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 { //----------------------------------------------------------------------- /** * Compares this chronology to another 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}. * * @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. *

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

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

    * The entire state of the object is compared. * * @param other the other object to compare to, null returns false