1 /*
   2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * This file is available under and governed by the GNU General Public
  28  * License version 2 only, as published by the Free Software Foundation.
  29  * However, the following notice accompanied the original version of this
  30  * file:
  31  *
  32  * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos
  33  *
  34  * All rights reserved.
  35  *
  36  * Redistribution and use in source and binary forms, with or without
  37  * modification, are permitted provided that the following conditions are met:
  38  *
  39  *  * Redistributions of source code must retain the above copyright notice,
  40  *    this list of conditions and the following disclaimer.
  41  *
  42  *  * Redistributions in binary form must reproduce the above copyright notice,
  43  *    this list of conditions and the following disclaimer in the documentation
  44  *    and/or other materials provided with the distribution.
  45  *
  46  *  * Neither the name of JSR-310 nor the names of its contributors
  47  *    may be used to endorse or promote products derived from this software
  48  *    without specific prior written permission.
  49  *
  50  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  51  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  52  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  53  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  54  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  55  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  56  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  57  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  58  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  59  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  60  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  61  */
  62 package java.time.temporal;
  63 
  64 import static java.time.temporal.ChronoField.EPOCH_DAY;
  65 import static java.time.temporal.ChronoField.ERA;
  66 import static java.time.temporal.ChronoField.YEAR;
  67 import static java.time.temporal.ChronoUnit.DAYS;
  68 
  69 import java.time.DateTimeException;
  70 import java.time.LocalDate;
  71 import java.time.LocalTime;
  72 import java.time.format.DateTimeFormatter;
  73 import java.util.Comparator;
  74 import java.util.Objects;
  75 
  76 /**
  77  * A date without time-of-day or time-zone in an arbitrary chronology, intended
  78  * for advanced globalization use cases.
  79  * <p>
  80  * <b>Most applications should declare method signatures, fields and variables
  81  * as {@link LocalDate}, not this interface.</b>
  82  * <p>
  83  * A {@code ChronoLocalDate} is the abstract representation of a date where the
  84  * {@code Chrono chronology}, or calendar system, is pluggable.
  85  * The date is defined in terms of fields expressed by {@link TemporalField},
  86  * where most common implementations are defined in {@link ChronoField}.
  87  * The chronology defines how the calendar system operates and the meaning of
  88  * the standard fields.
  89  *
  90  * <h3>When to use this interface</h3>
  91  * The design of the API encourages the use of {@code LocalDate} rather than this
  92  * interface, even in the case where the application needs to deal with multiple
  93  * calendar systems. The rationale for this is explored in the following documentation.
  94  * <p>
  95  * The primary use case where this interface should be used is where the generic
  96  * type parameter {@code <C>} is fully defined as a specific chronology.
  97  * In that case, the assumptions of that chronology are known at development
  98  * time and specified in the code.
  99  * <p>
 100  * When the chronology is defined in the generic type parameter as ? or otherwise
 101  * unknown at development time, the rest of the discussion below applies.
 102  * <p>
 103  * To emphasize the point, declaring a method signature, field or variable as this
 104  * interface type can initially seem like the sensible way to globalize an application,
 105  * however it is usually the wrong approach.
 106  * As such, it should be considered an application-wide architectural decision to choose
 107  * to use this interface as opposed to {@code LocalDate}.
 108  *
 109  * <h3>Architectural issues to consider</h3>
 110  * These are some of the points that must be considered before using this interface
 111  * throughout an application.
 112  * <p>
 113  * 1) Applications using this interface, as opposed to using just {@code LocalDate},
 114  * face a significantly higher probability of bugs. This is because the calendar system
 115  * in use is not known at development time. A key cause of bugs is where the developer
 116  * applies assumptions from their day-to-day knowledge of the ISO calendar system
 117  * to code that is intended to deal with any arbitrary calendar system.
 118  * The section below outlines how those assumptions can cause problems
 119  * The primary mechanism for reducing this increased risk of bugs is a strong code review process.
 120  * This should also be considered a extra cost in maintenance for the lifetime of the code.
 121  * <p>
 122  * 2) This interface does not enforce immutability of implementations.
 123  * While the implementation notes indicate that all implementations must be immutable
 124  * there is nothing in the code or type system to enforce this. Any method declared
 125  * to accept a {@code ChronoLocalDate} could therefore be passed a poorly or
 126  * maliciously written mutable implementation.
 127  * <p>
 128  * 3) Applications using this interface  must consider the impact of eras.
 129  * {@code LocalDate} shields users from the concept of eras, by ensuring that {@code getYear()}
 130  * returns the proleptic year. That decision ensures that developers can think of
 131  * {@code LocalDate} instances as consisting of three fields - year, month-of-year and day-of-month.
 132  * By contrast, users of this interface must think of dates as consisting of four fields -
 133  * era, year-of-era, month-of-year and day-of-month. The extra era field is frequently
 134  * forgotten, yet it is of vital importance to dates in an arbitrary calendar system.
 135  * For example, in the Japanese calendar system, the era represents the reign of an Emperor.
 136  * Whenever one reign ends and another starts, the year-of-era is reset to one.
 137  * <p>
 138  * 4) The only agreed international standard for passing a date between two systems
 139  * is the ISO-8601 standard which requires the ISO calendar system. Using this interface
 140  * throughout the application will inevitably lead to the requirement to pass the date
 141  * across a network or component boundary, requiring an application specific protocol or format.
 142  * <p>
 143  * 5) Long term persistence, such as a database, will almost always only accept dates in the
 144  * ISO-8601 calendar system (or the related Julian-Gregorian). Passing around dates in other
 145  * calendar systems increases the complications of interacting with persistence.
 146  * <p>
 147  * 6) Most of the time, passing a {@code ChronoLocalDate} throughout an application
 148  * is unnecessary, as discussed in the last section below.
 149  *
 150  * <h3>False assumptions causing bugs in multi-calendar system code</h3>
 151  * As indicated above, there are many issues to consider when try to use and manipulate a
 152  * date in an arbitrary calendar system. These are some of the key issues.
 153  * <p>
 154  * Code that queries the day-of-month and assumes that the value will never be more than
 155  * 31 is invalid. Some calendar systems have more than 31 days in some months.
 156  * <p>
 157  * Code that adds 12 months to a date and assumes that a year has been added is invalid.
 158  * Some calendar systems have a different number of months, such as 13 in the Coptic or Ethiopic.
 159  * <p>
 160  * Code that adds one month to a date and assumes that the month-of-year value will increase
 161  * by one or wrap to the next year is invalid. Some calendar systems have a variable number
 162  * of months in a year, such as the Hebrew.
 163  * <p>
 164  * Code that adds one month, then adds a second one month and assumes that the day-of-month
 165  * will remain close to its original value is invalid. Some calendar systems have a large difference
 166  * between the length of the longest month and the length of the shortest month.
 167  * For example, the Coptic or Ethiopic have 12 months of 30 days and 1 month of 5 days.
 168  * <p>
 169  * Code that adds seven days and assumes that a week has been added is invalid.
 170  * Some calendar systems have weeks of other than seven days, such as the French Revolutionary.
 171  * <p>
 172  * Code that assumes that because the year of {@code date1} is greater than the year of {@code date2}
 173  * then {@code date1} is after {@code date2} is invalid. This is invalid for all calendar systems
 174  * when referring to the year-of-era, and especially untrue of the Japanese calendar system
 175  * where the year-of-era restarts with the reign of every new Emperor.
 176  * <p>
 177  * Code that treats month-of-year one and day-of-month one as the start of the year is invalid.
 178  * Not all calendar systems start the year when the month value is one.
 179  * <p>
 180  * In general, manipulating a date, and even querying a date, is wide open to bugs when the
 181  * calendar system is unknown at development time. This is why it is essential that code using
 182  * this interface is subjected to additional code reviews. It is also why an architectural
 183  * decision to avoid this interface type is usually the correct one.
 184  *
 185  * <h3>Using LocalDate instead</h3>
 186  * The primary alternative to using this interface throughout your application is as follows.
 187  * <p><ul>
 188  * <li>Declare all method signatures referring to dates in terms of {@code LocalDate}.
 189  * <li>Either store the chronology (calendar system) in the user profile or lookup
 190  *  the chronology from the user locale
 191  * <li>Convert the ISO {@code LocalDate} to and from the user's preferred calendar system during
 192  *  printing and parsing
 193  * </ul><p>
 194  * This approach treats the problem of globalized calendar systems as a localization issue
 195  * and confines it to the UI layer. This approach is in keeping with other localization
 196  * issues in the java platform.
 197  * <p>
 198  * As discussed above, performing calculations on a date where the rules of the calendar system
 199  * are pluggable requires skill and is not recommended.
 200  * Fortunately, the need to perform calculations on a date in an arbitrary calendar system
 201  * is extremely rare. For example, it is highly unlikely that the business rules of a library
 202  * book rental scheme will allow rentals to be for one month, where meaning of the month
 203  * is dependent on the user's preferred calendar system.
 204  * <p>
 205  * A key use case for calculations on a date in an arbitrary calendar system is producing
 206  * a month-by-month calendar for display and user interaction. Again, this is a UI issue,
 207  * and use of this interface solely within a few methods of the UI layer may be justified.
 208  * <p>
 209  * In any other part of the system, where a date must be manipulated in a calendar system
 210  * other than ISO, the use case will generally specify the calendar system to use.
 211  * For example, an application may need to calculate the next Islamic or Hebrew holiday
 212  * which may require manipulating the date.
 213  * This kind of use case can be handled as follows:
 214  * <p><ul>
 215  * <li>start from the ISO {@code LocalDate} being passed to the method
 216  * <li>convert the date to the alternate calendar system, which for this use case is known
 217  *  rather than arbitrary
 218  * <li>perform the calculation
 219  * <li>convert back to {@code LocalDate}
 220  * </ul><p>
 221  * Developers writing low-level frameworks or libraries should also avoid this interface.
 222  * Instead, one of the two general purpose access interfaces should be used.
 223  * Use {@link TemporalAccessor} if read-only access is required, or use {@link Temporal}
 224  * if read-write access is required.
 225  *
 226  * <h3>Specification for implementors</h3>
 227  * This interface must be implemented with care to ensure other classes operate correctly.
 228  * All implementations that can be instantiated must be final, immutable and thread-safe.
 229  * Subclasses should be Serializable wherever possible.
 230  * <p>
 231  * Additional calendar systems may be added to the system.
 232  * See {@link Chrono} for more details.
 233  *
 234  * @param <C> the chronology of this date
 235  * @since 1.8
 236  */
 237 public interface ChronoLocalDate<C extends Chrono<C>>
 238         extends Temporal, TemporalAdjuster, Comparable<ChronoLocalDate<?>> {
 239 
 240     /**
 241      * Comparator for two {@code ChronoLocalDate}s ignoring the chronology.
 242      * <p>
 243      * This comparator differs from the comparison in {@link #compareTo} in that it
 244      * only compares the underlying date and not the chronology.
 245      * This allows dates in different calendar systems to be compared based
 246      * on the time-line position.
 247      * This is equivalent to using {@code Long.compare(date1.toEpochDay(),  date2.toEpochDay())}.
 248      *
 249      * @see #isAfter
 250      * @see #isBefore
 251      * @see #isEqual
 252      */
 253     public static final Comparator<ChronoLocalDate<?>> DATE_COMPARATOR =
 254             new Comparator<ChronoLocalDate<?>>() {
 255         @Override
 256         public int compare(ChronoLocalDate<?> date1, ChronoLocalDate<?> date2) {
 257             return Long.compare(date1.toEpochDay(), date2.toEpochDay());
 258         }
 259     };
 260 
 261     //-----------------------------------------------------------------------
 262     /**
 263      * Gets the chronology of this date.
 264      * <p>
 265      * The {@code Chrono} represents the calendar system in use.
 266      * The era and other fields in {@link ChronoField} are defined by the chronology.
 267      *
 268      * @return the chronology, not null
 269      */
 270     C getChrono();
 271 
 272     /**
 273      * Gets the era, as defined by the chronology.
 274      * <p>
 275      * The era is, conceptually, the largest division of the time-line.
 276      * Most calendar systems have a single epoch dividing the time-line into two eras.
 277      * However, some have multiple eras, such as one for the reign of each leader.
 278      * The exact meaning is determined by the {@code Chrono}.
 279      * <p>
 280      * All correctly implemented {@code Era} classes are singletons, thus it
 281      * is valid code to write {@code date.getEra() == SomeChrono.ERA_NAME)}.
 282      * <p>
 283      * This default implementation uses {@link Chrono#eraOf(int)}.
 284      *
 285      * @return the chronology specific era constant applicable at this date, not null
 286      */
 287     public default Era<C> getEra() {
 288         return getChrono().eraOf(get(ERA));
 289     }
 290 
 291     /**
 292      * Checks if the year is a leap year, as defined by the calendar system.
 293      * <p>
 294      * A leap-year is a year of a longer length than normal.
 295      * The exact meaning is determined by the chronology with the constraint that
 296      * a leap-year must imply a year-length longer than a non leap-year.
 297      * <p>
 298      * This default implementation uses {@link Chrono#isLeapYear(long)}.
 299      *
 300      * @return true if this date is in a leap year, false otherwise
 301      */
 302     public default boolean isLeapYear() {
 303         return getChrono().isLeapYear(getLong(YEAR));
 304     }
 305 
 306     /**
 307      * Returns the length of the month represented by this date, as defined by the calendar system.
 308      * <p>
 309      * This returns the length of the month in days.
 310      *
 311      * @return the length of the month in days
 312      */
 313     int lengthOfMonth();
 314 
 315     /**
 316      * Returns the length of the year represented by this date, as defined by the calendar system.
 317      * <p>
 318      * This returns the length of the year in days.
 319      * <p>
 320      * The default implementation uses {@link #isLeapYear()} and returns 365 or 366.
 321      *
 322      * @return the length of the year in days
 323      */
 324     public default int lengthOfYear() {
 325         return (isLeapYear() ? 366 : 365);
 326     }
 327 
 328     @Override
 329     public default boolean isSupported(TemporalField field) {
 330         if (field instanceof ChronoField) {
 331             return ((ChronoField) field).isDateField();
 332         }
 333         return field != null && field.doIsSupported(this);
 334     }
 335 
 336     //-----------------------------------------------------------------------
 337     // override for covariant return type
 338     /**
 339      * {@inheritDoc}
 340      * @throws DateTimeException {@inheritDoc}
 341      * @throws ArithmeticException {@inheritDoc}
 342      */
 343     @Override
 344     public default ChronoLocalDate<C> with(TemporalAdjuster adjuster) {
 345         return getChrono().ensureChronoLocalDate(Temporal.super.with(adjuster));
 346     }
 347 
 348     /**
 349      * {@inheritDoc}
 350      * @throws DateTimeException {@inheritDoc}
 351      * @throws ArithmeticException {@inheritDoc}
 352      */
 353     @Override
 354     public default ChronoLocalDate<C> with(TemporalField field, long newValue) {
 355         if (field instanceof ChronoField) {
 356             throw new DateTimeException("Unsupported field: " + field.getName());
 357         }
 358         return getChrono().ensureChronoLocalDate(field.doWith(this, newValue));
 359     }
 360 
 361     /**
 362      * {@inheritDoc}
 363      * @throws DateTimeException {@inheritDoc}
 364      * @throws ArithmeticException {@inheritDoc}
 365      */
 366     @Override
 367     public default ChronoLocalDate<C> plus(TemporalAdder adder) {
 368         return getChrono().ensureChronoLocalDate(Temporal.super.plus(adder));
 369     }
 370 
 371     /**
 372      * {@inheritDoc}
 373      * @throws DateTimeException {@inheritDoc}
 374      * @throws ArithmeticException {@inheritDoc}
 375      */
 376     @Override
 377     public default ChronoLocalDate<C> plus(long amountToAdd, TemporalUnit unit) {
 378         if (unit instanceof ChronoUnit) {
 379             throw new DateTimeException("Unsupported unit: " + unit.getName());
 380         }
 381         return getChrono().ensureChronoLocalDate(unit.doPlus(this, amountToAdd));
 382     }
 383 
 384     /**
 385      * {@inheritDoc}
 386      * @throws DateTimeException {@inheritDoc}
 387      * @throws ArithmeticException {@inheritDoc}
 388      */
 389     @Override
 390     public default ChronoLocalDate<C> minus(TemporalSubtractor subtractor) {
 391         return getChrono().ensureChronoLocalDate(Temporal.super.minus(subtractor));
 392     }
 393 
 394     /**
 395      * {@inheritDoc}
 396      * @throws DateTimeException {@inheritDoc}
 397      * @throws ArithmeticException {@inheritDoc}
 398      */
 399     @Override
 400     public default ChronoLocalDate<C> minus(long amountToSubtract, TemporalUnit unit) {
 401         return getChrono().ensureChronoLocalDate(Temporal.super.minus(amountToSubtract, unit));
 402     }
 403 
 404     //-----------------------------------------------------------------------
 405     /**
 406      * Queries this date using the specified query.
 407      * <p>
 408      * This queries this date using the specified query strategy object.
 409      * The {@code TemporalQuery} object defines the logic to be used to
 410      * obtain the result. Read the documentation of the query to understand
 411      * what the result of this method will be.
 412      * <p>
 413      * The result of this method is obtained by invoking the
 414      * {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the
 415      * specified query passing {@code this} as the argument.
 416      *
 417      * @param <R> the type of the result
 418      * @param query  the query to invoke, not null
 419      * @return the query result, null may be returned (defined by the query)
 420      * @throws DateTimeException if unable to query (defined by the query)
 421      * @throws ArithmeticException if numeric overflow occurs (defined by the query)
 422      */
 423     @SuppressWarnings("unchecked")
 424     @Override
 425     public default <R> R query(TemporalQuery<R> query) {
 426         if (query == Queries.chrono()) {
 427             return (R) getChrono();
 428         }
 429         if (query == Queries.precision()) {
 430             return (R) DAYS;
 431         }
 432         // inline TemporalAccessor.super.query(query) as an optimization
 433         if (query == Queries.zoneId() || query == Queries.zone() || query == Queries.offset()) {
 434             return null;
 435         }
 436         return query.queryFrom(this);
 437     }
 438 
 439     /**
 440      * Adjusts the specified temporal object to have the same date as this object.
 441      * <p>
 442      * This returns a temporal object of the same observable type as the input
 443      * with the date changed to be the same as this.
 444      * <p>
 445      * The adjustment is equivalent to using {@link Temporal#with(TemporalField, long)}
 446      * passing {@link ChronoField#EPOCH_DAY} as the field.
 447      * <p>
 448      * In most cases, it is clearer to reverse the calling pattern by using
 449      * {@link Temporal#with(TemporalAdjuster)}:
 450      * <pre>
 451      *   // these two lines are equivalent, but the second approach is recommended
 452      *   temporal = thisLocalDate.adjustInto(temporal);
 453      *   temporal = temporal.with(thisLocalDate);
 454      * </pre>
 455      * <p>
 456      * This instance is immutable and unaffected by this method call.
 457      *
 458      * @param temporal  the target object to be adjusted, not null
 459      * @return the adjusted object, not null
 460      * @throws DateTimeException if unable to make the adjustment
 461      * @throws ArithmeticException if numeric overflow occurs
 462      */
 463     @Override
 464     public default Temporal adjustInto(Temporal temporal) {
 465         return temporal.with(EPOCH_DAY, toEpochDay());
 466     }
 467 
 468     /**
 469      * Calculates the period between this date and another date in
 470      * terms of the specified unit.
 471      * <p>
 472      * This calculates the period between two dates in terms of a single unit.
 473      * The start and end points are {@code this} and the specified date.
 474      * The result will be negative if the end is before the start.
 475      * The {@code Temporal} passed to this method must be a
 476      * {@code ChronoLocalDate} in the same chronology.
 477      * The calculation returns a whole number, representing the number of
 478      * complete units between the two dates.
 479      * For example, the period in days between two dates can be calculated
 480      * using {@code startDate.periodUntil(endDate, DAYS)}.
 481      * <p>
 482      * This method operates in association with {@link TemporalUnit#between}.
 483      * The result of this method is a {@code long} representing the amount of
 484      * the specified unit. By contrast, the result of {@code between} is an
 485      * object that can be used directly in addition/subtraction:
 486      * <pre>
 487      *   long period = start.periodUntil(end, MONTHS);   // this method
 488      *   dateTime.plus(MONTHS.between(start, end));      // use in plus/minus
 489      * </pre>
 490      * <p>
 491      * The calculation is implemented in this method for {@link ChronoUnit}.
 492      * The units {@code DAYS}, {@code WEEKS}, {@code MONTHS}, {@code YEARS},
 493      * {@code DECADES}, {@code CENTURIES}, {@code MILLENNIA} and {@code ERAS}
 494      * should be supported by all implementations.
 495      * Other {@code ChronoUnit} values will throw an exception.
 496      * <p>
 497      * If the unit is not a {@code ChronoUnit}, then the result of this method
 498      * is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)}
 499      * passing {@code this} as the first argument and the input temporal as
 500      * the second argument.
 501      * <p>
 502      * This instance is immutable and unaffected by this method call.
 503      *
 504      * @param endDate  the end date, which must be a {@code ChronoLocalDate}
 505      *  in the same chronology, not null
 506      * @param unit  the unit to measure the period in, not null
 507      * @return the amount of the period between this date and the end date
 508      * @throws DateTimeException if the period cannot be calculated
 509      * @throws ArithmeticException if numeric overflow occurs
 510      */
 511     @Override  // override for Javadoc
 512     public abstract long periodUntil(Temporal endDate, TemporalUnit unit);
 513 
 514     //-----------------------------------------------------------------------
 515     /**
 516      * Returns a date-time formed from this date at the specified time.
 517      * <p>
 518      * This merges the two objects - {@code this} and the specified time -
 519      * to form an instance of {@code ChronoLocalDateTime}.
 520      * <p>
 521      * This instance is immutable and unaffected by this method call.
 522      * <p>
 523      * This default implementation creates the date-time.
 524      *
 525      * @param localTime  the local time to use, not null
 526      * @return the local date-time formed from this date and the specified time, not null
 527      */
 528     public default ChronoLocalDateTime<C> atTime(LocalTime localTime) {
 529         return Chrono.dateTime(this, localTime);
 530     }
 531 
 532     //-----------------------------------------------------------------------
 533     /**
 534      * Converts this date to the Epoch Day.
 535      * <p>
 536      * The {@link ChronoField#EPOCH_DAY Epoch Day count} is a simple
 537      * incrementing count of days where day 0 is 1970-01-01 (ISO).
 538      * This definition is the same for all chronologies, enabling conversion.
 539      * <p>
 540      * This default implementation queries the {@code EPOCH_DAY} field.
 541      *
 542      * @return the Epoch Day equivalent to this date
 543      */
 544     public default long toEpochDay() {
 545         return getLong(EPOCH_DAY);
 546     }
 547 
 548     //-----------------------------------------------------------------------
 549     /**
 550      * Compares this date to another date, including the chronology.
 551      * <p>
 552      * The comparison is based first on the underlying time-line date, then
 553      * on the chronology.
 554      * It is "consistent with equals", as defined by {@link Comparable}.
 555      * <p>
 556      * For example, the following is the comparator order:
 557      * <ol>
 558      * <li>{@code 2012-12-03 (ISO)}</li>
 559      * <li>{@code 2012-12-04 (ISO)}</li>
 560      * <li>{@code 2555-12-04 (ThaiBuddhist)}</li>
 561      * <li>{@code 2012-12-05 (ISO)}</li>
 562      * </ol>
 563      * Values #2 and #3 represent the same date on the time-line.
 564      * When two values represent the same date, the chronology ID is compared to distinguish them.
 565      * This step is needed to make the ordering "consistent with equals".
 566      * <p>
 567      * If all the date objects being compared are in the same chronology, then the
 568      * additional chronology stage is not required and only the local date is used.
 569      * To compare the dates of two {@code TemporalAccessor} instances, including dates
 570      * in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
 571      * <p>
 572      * This default implementation performs the comparison defined above.
 573      *
 574      * @param other  the other date to compare to, not null
 575      * @return the comparator value, negative if less, positive if greater
 576      */
 577     @Override
 578     public default int compareTo(ChronoLocalDate<?> other) {
 579         int cmp = Long.compare(toEpochDay(), other.toEpochDay());
 580         if (cmp == 0) {
 581             cmp = getChrono().compareTo(other.getChrono());
 582         }
 583         return cmp;
 584     }
 585 
 586     /**
 587      * Checks if this date is after the specified date ignoring the chronology.
 588      * <p>
 589      * This method differs from the comparison in {@link #compareTo} in that it
 590      * only compares the underlying date and not the chronology.
 591      * This allows dates in different calendar systems to be compared based
 592      * on the time-line position.
 593      * This is equivalent to using {@code date1.toEpochDay() &gt; date2.toEpochDay()}.
 594      * <p>
 595      * This default implementation performs the comparison based on the epoch-day.
 596      *
 597      * @param other  the other date to compare to, not null
 598      * @return true if this is after the specified date
 599      */
 600     public default boolean isAfter(ChronoLocalDate<?> other) {
 601         return this.toEpochDay() > other.toEpochDay();
 602     }
 603 
 604     /**
 605      * Checks if this date is before the specified date ignoring the chronology.
 606      * <p>
 607      * This method differs from the comparison in {@link #compareTo} in that it
 608      * only compares the underlying date and not the chronology.
 609      * This allows dates in different calendar systems to be compared based
 610      * on the time-line position.
 611      * This is equivalent to using {@code date1.toEpochDay() &lt; date2.toEpochDay()}.
 612      * <p>
 613      * This default implementation performs the comparison based on the epoch-day.
 614      *
 615      * @param other  the other date to compare to, not null
 616      * @return true if this is before the specified date
 617      */
 618     public default boolean isBefore(ChronoLocalDate<?> other) {
 619         return this.toEpochDay() < other.toEpochDay();
 620     }
 621 
 622     /**
 623      * Checks if this date is equal to the specified date ignoring the chronology.
 624      * <p>
 625      * This method differs from the comparison in {@link #compareTo} in that it
 626      * only compares the underlying date and not the chronology.
 627      * This allows dates in different calendar systems to be compared based
 628      * on the time-line position.
 629      * This is equivalent to using {@code date1.toEpochDay() == date2.toEpochDay()}.
 630      * <p>
 631      * This default implementation performs the comparison based on the epoch-day.
 632      *
 633      * @param other  the other date to compare to, not null
 634      * @return true if the underlying date is equal to the specified date
 635      */
 636     public default boolean isEqual(ChronoLocalDate<?> other) {
 637         return this.toEpochDay() == other.toEpochDay();
 638     }
 639 
 640     //-----------------------------------------------------------------------
 641     /**
 642      * Checks if this date is equal to another date, including the chronology.
 643      * <p>
 644      * Compares this date with another ensuring that the date and chronology are the same.
 645      * <p>
 646      * To compare the dates of two {@code TemporalAccessor} instances, including dates
 647      * in two different chronologies, use {@link ChronoField#EPOCH_DAY} as a comparator.
 648      *
 649      * @param obj  the object to check, null returns false
 650      * @return true if this is equal to the other date
 651      */
 652     @Override
 653     boolean equals(Object obj);
 654 
 655     /**
 656      * A hash code for this date.
 657      *
 658      * @return a suitable hash code
 659      */
 660     @Override
 661     int hashCode();
 662 
 663     //-----------------------------------------------------------------------
 664     /**
 665      * Outputs this date as a {@code String}.
 666      * <p>
 667      * The output will include the full local date and the chronology ID.
 668      *
 669      * @return the formatted date, not null
 670      */
 671     @Override
 672     String toString();
 673 
 674     /**
 675      * Outputs this date as a {@code String} using the formatter.
 676      * <p>
 677      * The default implementation must behave as follows:
 678      * <pre>
 679      *  return formatter.print(this);
 680      * </pre>
 681      *
 682      * @param formatter  the formatter to use, not null
 683      * @return the formatted date string, not null
 684      * @throws DateTimeException if an error occurs during printing
 685      */
 686     public default String toString(DateTimeFormatter formatter) {
 687         Objects.requireNonNull(formatter, "formatter");
 688         return formatter.print(this);
 689     }
 690 
 691 }