1 /* 2 * Copyright (c) 2012, 2023, 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) 2007-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; 63 64 import static java.time.LocalTime.HOURS_PER_DAY; 65 import static java.time.LocalTime.MICROS_PER_DAY; 66 import static java.time.LocalTime.MILLIS_PER_DAY; 67 import static java.time.LocalTime.MINUTES_PER_DAY; 68 import static java.time.LocalTime.NANOS_PER_DAY; 69 import static java.time.LocalTime.NANOS_PER_HOUR; 70 import static java.time.LocalTime.NANOS_PER_MINUTE; 71 import static java.time.LocalTime.NANOS_PER_SECOND; 72 import static java.time.LocalTime.SECONDS_PER_DAY; 73 import static java.time.temporal.ChronoField.NANO_OF_SECOND; 74 75 import java.io.DataInput; 76 import java.io.DataOutput; 77 import java.io.IOException; 78 import java.io.InvalidObjectException; 79 import java.io.ObjectInputStream; 80 import java.io.Serializable; 81 import java.time.chrono.ChronoLocalDateTime; 82 import java.time.format.DateTimeFormatter; 83 import java.time.format.DateTimeParseException; 84 import java.time.temporal.ChronoField; 85 import java.time.temporal.ChronoUnit; 86 import java.time.temporal.Temporal; 87 import java.time.temporal.TemporalAccessor; 88 import java.time.temporal.TemporalAdjuster; 89 import java.time.temporal.TemporalAmount; 90 import java.time.temporal.TemporalField; 91 import java.time.temporal.TemporalQueries; 92 import java.time.temporal.TemporalQuery; 93 import java.time.temporal.TemporalUnit; 94 import java.time.temporal.UnsupportedTemporalTypeException; 95 import java.time.temporal.ValueRange; 96 import java.time.zone.ZoneRules; 97 import java.util.Objects; 98 99 /** 100 * A date-time without a time-zone in the ISO-8601 calendar system, 101 * such as {@code 2007-12-03T10:15:30}. 102 * <p> 103 * {@code LocalDateTime} is an immutable date-time object that represents a date-time, 104 * often viewed as year-month-day-hour-minute-second. Other date and time fields, 105 * such as day-of-year, day-of-week and week-of-year, can also be accessed. 106 * Time is represented to nanosecond precision. 107 * For example, the value "2nd October 2007 at 13:45.30.123456789" can be 108 * stored in a {@code LocalDateTime}. 109 * <p> 110 * This class does not store or represent a time-zone. 111 * Instead, it is a description of the date, as used for birthdays, combined with 112 * the local time as seen on a wall clock. 113 * It cannot represent an instant on the time-line without additional information 114 * such as an offset or time-zone. 115 * <p> 116 * The ISO-8601 calendar system is the modern civil calendar system used today 117 * in most of the world. It is equivalent to the proleptic Gregorian calendar 118 * system, in which today's rules for leap years are applied for all time. 119 * For most applications written today, the ISO-8601 rules are entirely suitable. 120 * However, any application that makes use of historical dates, and requires them 121 * to be accurate will find the ISO-8601 approach unsuitable. 122 * <p> 123 * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a> 124 * class; programmers should treat instances that are 125 * {@linkplain #equals(Object) equal} as interchangeable and should not 126 * use instances for synchronization, or unpredictable behavior may 127 * occur. For example, in a future release, synchronization may fail. 128 * The {@code equals} method should be used for comparisons. 129 * 130 * @implSpec 131 * This class is immutable and thread-safe. 132 * 133 * @since 1.8 134 */ 135 @jdk.internal.ValueBased 136 @jdk.internal.MigratedValueClass 137 public final class LocalDateTime 138 implements Temporal, TemporalAdjuster, ChronoLocalDateTime<LocalDate>, Serializable { 139 140 /** 141 * The minimum supported {@code LocalDateTime}, '-999999999-01-01T00:00:00'. 142 * This is the local date-time of midnight at the start of the minimum date. 143 * This combines {@link LocalDate#MIN} and {@link LocalTime#MIN}. 144 * This could be used by an application as a "far past" date-time. 145 */ 146 public static final LocalDateTime MIN = LocalDateTime.of(LocalDate.MIN, LocalTime.MIN); 147 /** 148 * The maximum supported {@code LocalDateTime}, '+999999999-12-31T23:59:59.999999999'. 149 * This is the local date-time just before midnight at the end of the maximum date. 150 * This combines {@link LocalDate#MAX} and {@link LocalTime#MAX}. 151 * This could be used by an application as a "far future" date-time. 152 */ 153 public static final LocalDateTime MAX = LocalDateTime.of(LocalDate.MAX, LocalTime.MAX); 154 155 /** 156 * Serialization version. 157 */ 158 @java.io.Serial 159 private static final long serialVersionUID = 6207766400415563566L; 160 161 /** 162 * The date part. 163 */ 164 private final LocalDate date; 165 /** 166 * The time part. 167 */ 168 private final LocalTime time; 169 170 //----------------------------------------------------------------------- 171 /** 172 * Obtains the current date-time from the system clock in the default time-zone. 173 * <p> 174 * This will query the {@link Clock#systemDefaultZone() system clock} in the default 175 * time-zone to obtain the current date-time. 176 * <p> 177 * Using this method will prevent the ability to use an alternate clock for testing 178 * because the clock is hard-coded. 179 * 180 * @return the current date-time using the system clock and default time-zone, not null 181 */ 182 public static LocalDateTime now() { 183 return now(Clock.systemDefaultZone()); 184 } 185 186 /** 187 * Obtains the current date-time from the system clock in the specified time-zone. 188 * <p> 189 * This will query the {@link Clock#system(ZoneId) system clock} to obtain the current date-time. 190 * Specifying the time-zone avoids dependence on the default time-zone. 191 * <p> 192 * Using this method will prevent the ability to use an alternate clock for testing 193 * because the clock is hard-coded. 194 * 195 * @param zone the zone ID to use, not null 196 * @return the current date-time using the system clock, not null 197 */ 198 public static LocalDateTime now(ZoneId zone) { 199 return now(Clock.system(zone)); 200 } 201 202 /** 203 * Obtains the current date-time from the specified clock. 204 * <p> 205 * This will query the specified clock to obtain the current date-time. 206 * Using this method allows the use of an alternate clock for testing. 207 * The alternate clock may be introduced using {@link Clock dependency injection}. 208 * 209 * @param clock the clock to use, not null 210 * @return the current date-time, not null 211 */ 212 public static LocalDateTime now(Clock clock) { 213 Objects.requireNonNull(clock, "clock"); 214 final Instant now = clock.instant(); // called once 215 ZoneOffset offset = clock.getZone().getRules().getOffset(now); 216 return ofEpochSecond(now.getEpochSecond(), now.getNano(), offset); 217 } 218 219 //----------------------------------------------------------------------- 220 /** 221 * Obtains an instance of {@code LocalDateTime} from year, month, 222 * day, hour and minute, setting the second and nanosecond to zero. 223 * <p> 224 * This returns a {@code LocalDateTime} with the specified year, month, 225 * day-of-month, hour and minute. 226 * The day must be valid for the year and month, otherwise an exception will be thrown. 227 * The second and nanosecond fields will be set to zero. 228 * 229 * @param year the year to represent, from MIN_YEAR to MAX_YEAR 230 * @param month the month-of-year to represent, not null 231 * @param dayOfMonth the day-of-month to represent, from 1 to 31 232 * @param hour the hour-of-day to represent, from 0 to 23 233 * @param minute the minute-of-hour to represent, from 0 to 59 234 * @return the local date-time, not null 235 * @throws DateTimeException if the value of any field is out of range, 236 * or if the day-of-month is invalid for the month-year 237 */ 238 public static LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute) { 239 LocalDate date = LocalDate.of(year, month, dayOfMonth); 240 LocalTime time = LocalTime.of(hour, minute); 241 return new LocalDateTime(date, time); 242 } 243 244 /** 245 * Obtains an instance of {@code LocalDateTime} from year, month, 246 * day, hour, minute and second, setting the nanosecond to zero. 247 * <p> 248 * This returns a {@code LocalDateTime} with the specified year, month, 249 * day-of-month, hour, minute and second. 250 * The day must be valid for the year and month, otherwise an exception will be thrown. 251 * The nanosecond field will be set to zero. 252 * 253 * @param year the year to represent, from MIN_YEAR to MAX_YEAR 254 * @param month the month-of-year to represent, not null 255 * @param dayOfMonth the day-of-month to represent, from 1 to 31 256 * @param hour the hour-of-day to represent, from 0 to 23 257 * @param minute the minute-of-hour to represent, from 0 to 59 258 * @param second the second-of-minute to represent, from 0 to 59 259 * @return the local date-time, not null 260 * @throws DateTimeException if the value of any field is out of range, 261 * or if the day-of-month is invalid for the month-year 262 */ 263 public static LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second) { 264 LocalDate date = LocalDate.of(year, month, dayOfMonth); 265 LocalTime time = LocalTime.of(hour, minute, second); 266 return new LocalDateTime(date, time); 267 } 268 269 /** 270 * Obtains an instance of {@code LocalDateTime} from year, month, 271 * day, hour, minute, second and nanosecond. 272 * <p> 273 * This returns a {@code LocalDateTime} with the specified year, month, 274 * day-of-month, hour, minute, second and nanosecond. 275 * The day must be valid for the year and month, otherwise an exception will be thrown. 276 * 277 * @param year the year to represent, from MIN_YEAR to MAX_YEAR 278 * @param month the month-of-year to represent, not null 279 * @param dayOfMonth the day-of-month to represent, from 1 to 31 280 * @param hour the hour-of-day to represent, from 0 to 23 281 * @param minute the minute-of-hour to represent, from 0 to 59 282 * @param second the second-of-minute to represent, from 0 to 59 283 * @param nanoOfSecond the nano-of-second to represent, from 0 to 999,999,999 284 * @return the local date-time, not null 285 * @throws DateTimeException if the value of any field is out of range, 286 * or if the day-of-month is invalid for the month-year 287 */ 288 public static LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond) { 289 LocalDate date = LocalDate.of(year, month, dayOfMonth); 290 LocalTime time = LocalTime.of(hour, minute, second, nanoOfSecond); 291 return new LocalDateTime(date, time); 292 } 293 294 //----------------------------------------------------------------------- 295 /** 296 * Obtains an instance of {@code LocalDateTime} from year, month, 297 * day, hour and minute, setting the second and nanosecond to zero. 298 * <p> 299 * This returns a {@code LocalDateTime} with the specified year, month, 300 * day-of-month, hour and minute. 301 * The day must be valid for the year and month, otherwise an exception will be thrown. 302 * The second and nanosecond fields will be set to zero. 303 * 304 * @param year the year to represent, from MIN_YEAR to MAX_YEAR 305 * @param month the month-of-year to represent, from 1 (January) to 12 (December) 306 * @param dayOfMonth the day-of-month to represent, from 1 to 31 307 * @param hour the hour-of-day to represent, from 0 to 23 308 * @param minute the minute-of-hour to represent, from 0 to 59 309 * @return the local date-time, not null 310 * @throws DateTimeException if the value of any field is out of range, 311 * or if the day-of-month is invalid for the month-year 312 */ 313 public static LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute) { 314 LocalDate date = LocalDate.of(year, month, dayOfMonth); 315 LocalTime time = LocalTime.of(hour, minute); 316 return new LocalDateTime(date, time); 317 } 318 319 /** 320 * Obtains an instance of {@code LocalDateTime} from year, month, 321 * day, hour, minute and second, setting the nanosecond to zero. 322 * <p> 323 * This returns a {@code LocalDateTime} with the specified year, month, 324 * day-of-month, hour, minute and second. 325 * The day must be valid for the year and month, otherwise an exception will be thrown. 326 * The nanosecond field will be set to zero. 327 * 328 * @param year the year to represent, from MIN_YEAR to MAX_YEAR 329 * @param month the month-of-year to represent, from 1 (January) to 12 (December) 330 * @param dayOfMonth the day-of-month to represent, from 1 to 31 331 * @param hour the hour-of-day to represent, from 0 to 23 332 * @param minute the minute-of-hour to represent, from 0 to 59 333 * @param second the second-of-minute to represent, from 0 to 59 334 * @return the local date-time, not null 335 * @throws DateTimeException if the value of any field is out of range, 336 * or if the day-of-month is invalid for the month-year 337 */ 338 public static LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second) { 339 LocalDate date = LocalDate.of(year, month, dayOfMonth); 340 LocalTime time = LocalTime.of(hour, minute, second); 341 return new LocalDateTime(date, time); 342 } 343 344 /** 345 * Obtains an instance of {@code LocalDateTime} from year, month, 346 * day, hour, minute, second and nanosecond. 347 * <p> 348 * This returns a {@code LocalDateTime} with the specified year, month, 349 * day-of-month, hour, minute, second and nanosecond. 350 * The day must be valid for the year and month, otherwise an exception will be thrown. 351 * 352 * @param year the year to represent, from MIN_YEAR to MAX_YEAR 353 * @param month the month-of-year to represent, from 1 (January) to 12 (December) 354 * @param dayOfMonth the day-of-month to represent, from 1 to 31 355 * @param hour the hour-of-day to represent, from 0 to 23 356 * @param minute the minute-of-hour to represent, from 0 to 59 357 * @param second the second-of-minute to represent, from 0 to 59 358 * @param nanoOfSecond the nano-of-second to represent, from 0 to 999,999,999 359 * @return the local date-time, not null 360 * @throws DateTimeException if the value of any field is out of range, 361 * or if the day-of-month is invalid for the month-year 362 */ 363 public static LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond) { 364 LocalDate date = LocalDate.of(year, month, dayOfMonth); 365 LocalTime time = LocalTime.of(hour, minute, second, nanoOfSecond); 366 return new LocalDateTime(date, time); 367 } 368 369 /** 370 * Obtains an instance of {@code LocalDateTime} from a date and time. 371 * 372 * @param date the local date, not null 373 * @param time the local time, not null 374 * @return the local date-time, not null 375 */ 376 public static LocalDateTime of(LocalDate date, LocalTime time) { 377 Objects.requireNonNull(date, "date"); 378 Objects.requireNonNull(time, "time"); 379 return new LocalDateTime(date, time); 380 } 381 382 //------------------------------------------------------------------------- 383 /** 384 * Obtains an instance of {@code LocalDateTime} from an {@code Instant} and zone ID. 385 * <p> 386 * This creates a local date-time based on the specified instant. 387 * First, the offset from UTC/Greenwich is obtained using the zone ID and instant, 388 * which is simple as there is only one valid offset for each instant. 389 * Then, the instant and offset are used to calculate the local date-time. 390 * 391 * @param instant the instant to create the date-time from, not null 392 * @param zone the time-zone, which may be an offset, not null 393 * @return the local date-time, not null 394 * @throws DateTimeException if the result exceeds the supported range 395 */ 396 public static LocalDateTime ofInstant(Instant instant, ZoneId zone) { 397 Objects.requireNonNull(instant, "instant"); 398 Objects.requireNonNull(zone, "zone"); 399 ZoneRules rules = zone.getRules(); 400 ZoneOffset offset = rules.getOffset(instant); 401 return ofEpochSecond(instant.getEpochSecond(), instant.getNano(), offset); 402 } 403 404 /** 405 * Obtains an instance of {@code LocalDateTime} using seconds from the 406 * epoch of 1970-01-01T00:00:00Z. 407 * <p> 408 * This allows the {@link ChronoField#INSTANT_SECONDS epoch-second} field 409 * to be converted to a local date-time. This is primarily intended for 410 * low-level conversions rather than general application usage. 411 * 412 * @param epochSecond the number of seconds from the epoch of 1970-01-01T00:00:00Z 413 * @param nanoOfSecond the nanosecond within the second, from 0 to 999,999,999 414 * @param offset the zone offset, not null 415 * @return the local date-time, not null 416 * @throws DateTimeException if the result exceeds the supported range, 417 * or if the nano-of-second is invalid 418 */ 419 public static LocalDateTime ofEpochSecond(long epochSecond, int nanoOfSecond, ZoneOffset offset) { 420 Objects.requireNonNull(offset, "offset"); 421 NANO_OF_SECOND.checkValidValue(nanoOfSecond); 422 long localSecond = epochSecond + offset.getTotalSeconds(); // overflow caught later 423 long localEpochDay = Math.floorDiv(localSecond, SECONDS_PER_DAY); 424 int secsOfDay = Math.floorMod(localSecond, SECONDS_PER_DAY); 425 LocalDate date = LocalDate.ofEpochDay(localEpochDay); 426 LocalTime time = LocalTime.ofNanoOfDay(secsOfDay * NANOS_PER_SECOND + nanoOfSecond); 427 return new LocalDateTime(date, time); 428 } 429 430 //----------------------------------------------------------------------- 431 /** 432 * Obtains an instance of {@code LocalDateTime} from a temporal object. 433 * <p> 434 * This obtains a local date-time based on the specified temporal. 435 * A {@code TemporalAccessor} represents an arbitrary set of date and time information, 436 * which this factory converts to an instance of {@code LocalDateTime}. 437 * <p> 438 * The conversion extracts and combines the {@code LocalDate} and the 439 * {@code LocalTime} from the temporal object. 440 * Implementations are permitted to perform optimizations such as accessing 441 * those fields that are equivalent to the relevant objects. 442 * <p> 443 * This method matches the signature of the functional interface {@link TemporalQuery} 444 * allowing it to be used as a query via method reference, {@code LocalDateTime::from}. 445 * 446 * @param temporal the temporal object to convert, not null 447 * @return the local date-time, not null 448 * @throws DateTimeException if unable to convert to a {@code LocalDateTime} 449 */ 450 public static LocalDateTime from(TemporalAccessor temporal) { 451 if (temporal instanceof LocalDateTime) { 452 return (LocalDateTime) temporal; 453 } else if (temporal instanceof ZonedDateTime) { 454 return ((ZonedDateTime) temporal).toLocalDateTime(); 455 } else if (temporal instanceof OffsetDateTime) { 456 return ((OffsetDateTime) temporal).toLocalDateTime(); 457 } 458 try { 459 LocalDate date = LocalDate.from(temporal); 460 LocalTime time = LocalTime.from(temporal); 461 return new LocalDateTime(date, time); 462 } catch (DateTimeException ex) { 463 throw new DateTimeException("Unable to obtain LocalDateTime from TemporalAccessor: " + 464 temporal + " of type " + temporal.getClass().getName(), ex); 465 } 466 } 467 468 //----------------------------------------------------------------------- 469 /** 470 * Obtains an instance of {@code LocalDateTime} from a text string such as {@code 2007-12-03T10:15:30}. 471 * <p> 472 * The string must represent a valid date-time and is parsed using 473 * {@link java.time.format.DateTimeFormatter#ISO_LOCAL_DATE_TIME}. 474 * 475 * @param text the text to parse such as "2007-12-03T10:15:30", not null 476 * @return the parsed local date-time, not null 477 * @throws DateTimeParseException if the text cannot be parsed 478 */ 479 public static LocalDateTime parse(CharSequence text) { 480 return parse(text, DateTimeFormatter.ISO_LOCAL_DATE_TIME); 481 } 482 483 /** 484 * Obtains an instance of {@code LocalDateTime} from a text string using a specific formatter. 485 * <p> 486 * The text is parsed using the formatter, returning a date-time. 487 * 488 * @param text the text to parse, not null 489 * @param formatter the formatter to use, not null 490 * @return the parsed local date-time, not null 491 * @throws DateTimeParseException if the text cannot be parsed 492 */ 493 public static LocalDateTime parse(CharSequence text, DateTimeFormatter formatter) { 494 Objects.requireNonNull(formatter, "formatter"); 495 return formatter.parse(text, LocalDateTime::from); 496 } 497 498 //----------------------------------------------------------------------- 499 /** 500 * Constructor. 501 * 502 * @param date the date part of the date-time, validated not null 503 * @param time the time part of the date-time, validated not null 504 */ 505 private LocalDateTime(LocalDate date, LocalTime time) { 506 this.date = date; 507 this.time = time; 508 } 509 510 /** 511 * Returns a copy of this date-time with the new date and time, checking 512 * to see if a new object is in fact required. 513 * 514 * @param newDate the date of the new date-time, not null 515 * @param newTime the time of the new date-time, not null 516 * @return the date-time, not null 517 */ 518 private LocalDateTime with(LocalDate newDate, LocalTime newTime) { 519 if (date == newDate && time == newTime) { 520 return this; 521 } 522 return new LocalDateTime(newDate, newTime); 523 } 524 525 //----------------------------------------------------------------------- 526 /** 527 * Checks if the specified field is supported. 528 * <p> 529 * This checks if this date-time can be queried for the specified field. 530 * If false, then calling the {@link #range(TemporalField) range}, 531 * {@link #get(TemporalField) get} and {@link #with(TemporalField, long)} 532 * methods will throw an exception. 533 * <p> 534 * If the field is a {@link ChronoField} then the query is implemented here. 535 * The supported fields are: 536 * <ul> 537 * <li>{@code NANO_OF_SECOND} 538 * <li>{@code NANO_OF_DAY} 539 * <li>{@code MICRO_OF_SECOND} 540 * <li>{@code MICRO_OF_DAY} 541 * <li>{@code MILLI_OF_SECOND} 542 * <li>{@code MILLI_OF_DAY} 543 * <li>{@code SECOND_OF_MINUTE} 544 * <li>{@code SECOND_OF_DAY} 545 * <li>{@code MINUTE_OF_HOUR} 546 * <li>{@code MINUTE_OF_DAY} 547 * <li>{@code HOUR_OF_AMPM} 548 * <li>{@code CLOCK_HOUR_OF_AMPM} 549 * <li>{@code HOUR_OF_DAY} 550 * <li>{@code CLOCK_HOUR_OF_DAY} 551 * <li>{@code AMPM_OF_DAY} 552 * <li>{@code DAY_OF_WEEK} 553 * <li>{@code ALIGNED_DAY_OF_WEEK_IN_MONTH} 554 * <li>{@code ALIGNED_DAY_OF_WEEK_IN_YEAR} 555 * <li>{@code DAY_OF_MONTH} 556 * <li>{@code DAY_OF_YEAR} 557 * <li>{@code EPOCH_DAY} 558 * <li>{@code ALIGNED_WEEK_OF_MONTH} 559 * <li>{@code ALIGNED_WEEK_OF_YEAR} 560 * <li>{@code MONTH_OF_YEAR} 561 * <li>{@code PROLEPTIC_MONTH} 562 * <li>{@code YEAR_OF_ERA} 563 * <li>{@code YEAR} 564 * <li>{@code ERA} 565 * </ul> 566 * All other {@code ChronoField} instances will return false. 567 * <p> 568 * If the field is not a {@code ChronoField}, then the result of this method 569 * is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)} 570 * passing {@code this} as the argument. 571 * Whether the field is supported is determined by the field. 572 * 573 * @param field the field to check, null returns false 574 * @return true if the field is supported on this date-time, false if not 575 */ 576 @Override 577 public boolean isSupported(TemporalField field) { 578 if (field instanceof ChronoField chronoField) { 579 return chronoField.isDateBased() || chronoField.isTimeBased(); 580 } 581 return field != null && field.isSupportedBy(this); 582 } 583 584 /** 585 * Checks if the specified unit is supported. 586 * <p> 587 * This checks if the specified unit can be added to, or subtracted from, this date-time. 588 * If false, then calling the {@link #plus(long, TemporalUnit)} and 589 * {@link #minus(long, TemporalUnit) minus} methods will throw an exception. 590 * <p> 591 * If the unit is a {@link ChronoUnit} then the query is implemented here. 592 * The supported units are: 593 * <ul> 594 * <li>{@code NANOS} 595 * <li>{@code MICROS} 596 * <li>{@code MILLIS} 597 * <li>{@code SECONDS} 598 * <li>{@code MINUTES} 599 * <li>{@code HOURS} 600 * <li>{@code HALF_DAYS} 601 * <li>{@code DAYS} 602 * <li>{@code WEEKS} 603 * <li>{@code MONTHS} 604 * <li>{@code YEARS} 605 * <li>{@code DECADES} 606 * <li>{@code CENTURIES} 607 * <li>{@code MILLENNIA} 608 * <li>{@code ERAS} 609 * </ul> 610 * All other {@code ChronoUnit} instances will return false. 611 * <p> 612 * If the unit is not a {@code ChronoUnit}, then the result of this method 613 * is obtained by invoking {@code TemporalUnit.isSupportedBy(Temporal)} 614 * passing {@code this} as the argument. 615 * Whether the unit is supported is determined by the unit. 616 * 617 * @param unit the unit to check, null returns false 618 * @return true if the unit can be added/subtracted, false if not 619 */ 620 @Override // override for Javadoc 621 public boolean isSupported(TemporalUnit unit) { 622 return ChronoLocalDateTime.super.isSupported(unit); 623 } 624 625 //----------------------------------------------------------------------- 626 /** 627 * Gets the range of valid values for the specified field. 628 * <p> 629 * The range object expresses the minimum and maximum valid values for a field. 630 * This date-time is used to enhance the accuracy of the returned range. 631 * If it is not possible to return the range, because the field is not supported 632 * or for some other reason, an exception is thrown. 633 * <p> 634 * If the field is a {@link ChronoField} then the query is implemented here. 635 * The {@link #isSupported(TemporalField) supported fields} will return 636 * appropriate range instances. 637 * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}. 638 * <p> 639 * If the field is not a {@code ChronoField}, then the result of this method 640 * is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)} 641 * passing {@code this} as the argument. 642 * Whether the range can be obtained is determined by the field. 643 * 644 * @param field the field to query the range for, not null 645 * @return the range of valid values for the field, not null 646 * @throws DateTimeException if the range for the field cannot be obtained 647 * @throws UnsupportedTemporalTypeException if the field is not supported 648 */ 649 @Override 650 public ValueRange range(TemporalField field) { 651 if (field instanceof ChronoField chronoField) { 652 return (chronoField.isTimeBased() ? time.range(field) : date.range(field)); 653 } 654 return field.rangeRefinedBy(this); 655 } 656 657 /** 658 * Gets the value of the specified field from this date-time as an {@code int}. 659 * <p> 660 * This queries this date-time for the value of the specified field. 661 * The returned value will always be within the valid range of values for the field. 662 * If it is not possible to return the value, because the field is not supported 663 * or for some other reason, an exception is thrown. 664 * <p> 665 * If the field is a {@link ChronoField} then the query is implemented here. 666 * The {@link #isSupported(TemporalField) supported fields} will return valid 667 * values based on this date-time, except {@code NANO_OF_DAY}, {@code MICRO_OF_DAY}, 668 * {@code EPOCH_DAY} and {@code PROLEPTIC_MONTH} which are too large to fit in 669 * an {@code int} and throw an {@code UnsupportedTemporalTypeException}. 670 * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}. 671 * <p> 672 * If the field is not a {@code ChronoField}, then the result of this method 673 * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)} 674 * passing {@code this} as the argument. Whether the value can be obtained, 675 * and what the value represents, is determined by the field. 676 * 677 * @param field the field to get, not null 678 * @return the value for the field 679 * @throws DateTimeException if a value for the field cannot be obtained or 680 * the value is outside the range of valid values for the field 681 * @throws UnsupportedTemporalTypeException if the field is not supported or 682 * the range of values exceeds an {@code int} 683 * @throws ArithmeticException if numeric overflow occurs 684 */ 685 @Override 686 public int get(TemporalField field) { 687 if (field instanceof ChronoField chronoField) { 688 return (chronoField.isTimeBased() ? time.get(field) : date.get(field)); 689 } 690 return ChronoLocalDateTime.super.get(field); 691 } 692 693 /** 694 * Gets the value of the specified field from this date-time as a {@code long}. 695 * <p> 696 * This queries this date-time for the value of the specified field. 697 * If it is not possible to return the value, because the field is not supported 698 * or for some other reason, an exception is thrown. 699 * <p> 700 * If the field is a {@link ChronoField} then the query is implemented here. 701 * The {@link #isSupported(TemporalField) supported fields} will return valid 702 * values based on this date-time. 703 * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}. 704 * <p> 705 * If the field is not a {@code ChronoField}, then the result of this method 706 * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)} 707 * passing {@code this} as the argument. Whether the value can be obtained, 708 * and what the value represents, is determined by the field. 709 * 710 * @param field the field to get, not null 711 * @return the value for the field 712 * @throws DateTimeException if a value for the field cannot be obtained 713 * @throws UnsupportedTemporalTypeException if the field is not supported 714 * @throws ArithmeticException if numeric overflow occurs 715 */ 716 @Override 717 public long getLong(TemporalField field) { 718 if (field instanceof ChronoField chronoField) { 719 return (chronoField.isTimeBased() ? time.getLong(field) : date.getLong(field)); 720 } 721 return field.getFrom(this); 722 } 723 724 //----------------------------------------------------------------------- 725 /** 726 * Gets the {@code LocalDate} part of this date-time. 727 * <p> 728 * This returns a {@code LocalDate} with the same year, month and day 729 * as this date-time. 730 * 731 * @return the date part of this date-time, not null 732 */ 733 @Override 734 public LocalDate toLocalDate() { 735 return date; 736 } 737 738 /** 739 * Gets the year field. 740 * <p> 741 * This method returns the primitive {@code int} value for the year. 742 * <p> 743 * The year returned by this method is proleptic as per {@code get(YEAR)}. 744 * To obtain the year-of-era, use {@code get(YEAR_OF_ERA)}. 745 * 746 * @return the year, from MIN_YEAR to MAX_YEAR 747 */ 748 public int getYear() { 749 return date.getYear(); 750 } 751 752 /** 753 * Gets the month-of-year field from 1 to 12. 754 * <p> 755 * This method returns the month as an {@code int} from 1 to 12. 756 * Application code is frequently clearer if the enum {@link Month} 757 * is used by calling {@link #getMonth()}. 758 * 759 * @return the month-of-year, from 1 to 12 760 * @see #getMonth() 761 */ 762 public int getMonthValue() { 763 return date.getMonthValue(); 764 } 765 766 /** 767 * Gets the month-of-year field using the {@code Month} enum. 768 * <p> 769 * This method returns the enum {@link Month} for the month. 770 * This avoids confusion as to what {@code int} values mean. 771 * If you need access to the primitive {@code int} value then the enum 772 * provides the {@link Month#getValue() int value}. 773 * 774 * @return the month-of-year, not null 775 * @see #getMonthValue() 776 */ 777 public Month getMonth() { 778 return date.getMonth(); 779 } 780 781 /** 782 * Gets the day-of-month field. 783 * <p> 784 * This method returns the primitive {@code int} value for the day-of-month. 785 * 786 * @return the day-of-month, from 1 to 31 787 */ 788 public int getDayOfMonth() { 789 return date.getDayOfMonth(); 790 } 791 792 /** 793 * Gets the day-of-year field. 794 * <p> 795 * This method returns the primitive {@code int} value for the day-of-year. 796 * 797 * @return the day-of-year, from 1 to 365, or 366 in a leap year 798 */ 799 public int getDayOfYear() { 800 return date.getDayOfYear(); 801 } 802 803 /** 804 * Gets the day-of-week field, which is an enum {@code DayOfWeek}. 805 * <p> 806 * This method returns the enum {@link DayOfWeek} for the day-of-week. 807 * This avoids confusion as to what {@code int} values mean. 808 * If you need access to the primitive {@code int} value then the enum 809 * provides the {@link DayOfWeek#getValue() int value}. 810 * <p> 811 * Additional information can be obtained from the {@code DayOfWeek}. 812 * This includes textual names of the values. 813 * 814 * @return the day-of-week, not null 815 */ 816 public DayOfWeek getDayOfWeek() { 817 return date.getDayOfWeek(); 818 } 819 820 //----------------------------------------------------------------------- 821 /** 822 * Gets the {@code LocalTime} part of this date-time. 823 * <p> 824 * This returns a {@code LocalTime} with the same hour, minute, second and 825 * nanosecond as this date-time. 826 * 827 * @return the time part of this date-time, not null 828 */ 829 @Override 830 public LocalTime toLocalTime() { 831 return time; 832 } 833 834 /** 835 * Gets the hour-of-day field. 836 * 837 * @return the hour-of-day, from 0 to 23 838 */ 839 public int getHour() { 840 return time.getHour(); 841 } 842 843 /** 844 * Gets the minute-of-hour field. 845 * 846 * @return the minute-of-hour, from 0 to 59 847 */ 848 public int getMinute() { 849 return time.getMinute(); 850 } 851 852 /** 853 * Gets the second-of-minute field. 854 * 855 * @return the second-of-minute, from 0 to 59 856 */ 857 public int getSecond() { 858 return time.getSecond(); 859 } 860 861 /** 862 * Gets the nano-of-second field. 863 * 864 * @return the nano-of-second, from 0 to 999,999,999 865 */ 866 public int getNano() { 867 return time.getNano(); 868 } 869 870 //----------------------------------------------------------------------- 871 /** 872 * Returns an adjusted copy of this date-time. 873 * <p> 874 * This returns a {@code LocalDateTime}, based on this one, with the date-time adjusted. 875 * The adjustment takes place using the specified adjuster strategy object. 876 * Read the documentation of the adjuster to understand what adjustment will be made. 877 * <p> 878 * A simple adjuster might simply set the one of the fields, such as the year field. 879 * A more complex adjuster might set the date to the last day of the month. 880 * <p> 881 * A selection of common adjustments is provided in 882 * {@link java.time.temporal.TemporalAdjusters TemporalAdjusters}. 883 * These include finding the "last day of the month" and "next Wednesday". 884 * Key date-time classes also implement the {@code TemporalAdjuster} interface, 885 * such as {@link Month} and {@link java.time.MonthDay MonthDay}. 886 * The adjuster is responsible for handling special cases, such as the varying 887 * lengths of month and leap years. 888 * <p> 889 * For example this code returns a date on the last day of July: 890 * <pre> 891 * import static java.time.Month.*; 892 * import static java.time.temporal.TemporalAdjusters.*; 893 * 894 * result = localDateTime.with(JULY).with(lastDayOfMonth()); 895 * </pre> 896 * <p> 897 * The classes {@link LocalDate} and {@link LocalTime} implement {@code TemporalAdjuster}, 898 * thus this method can be used to change the date, time or offset: 899 * <pre> 900 * result = localDateTime.with(date); 901 * result = localDateTime.with(time); 902 * </pre> 903 * <p> 904 * The result of this method is obtained by invoking the 905 * {@link TemporalAdjuster#adjustInto(Temporal)} method on the 906 * specified adjuster passing {@code this} as the argument. 907 * <p> 908 * This instance is immutable and unaffected by this method call. 909 * 910 * @param adjuster the adjuster to use, not null 911 * @return a {@code LocalDateTime} based on {@code this} with the adjustment made, not null 912 * @throws DateTimeException if the adjustment cannot be made 913 * @throws ArithmeticException if numeric overflow occurs 914 */ 915 @Override 916 public LocalDateTime with(TemporalAdjuster adjuster) { 917 // optimizations 918 if (adjuster instanceof LocalDate) { 919 return with((LocalDate) adjuster, time); 920 } else if (adjuster instanceof LocalTime) { 921 return with(date, (LocalTime) adjuster); 922 } else if (adjuster instanceof LocalDateTime) { 923 return (LocalDateTime) adjuster; 924 } 925 return (LocalDateTime) adjuster.adjustInto(this); 926 } 927 928 /** 929 * Returns a copy of this date-time with the specified field set to a new value. 930 * <p> 931 * This returns a {@code LocalDateTime}, based on this one, with the value 932 * for the specified field changed. 933 * This can be used to change any supported field, such as the year, month or day-of-month. 934 * If it is not possible to set the value, because the field is not supported or for 935 * some other reason, an exception is thrown. 936 * <p> 937 * In some cases, changing the specified field can cause the resulting date-time to become invalid, 938 * such as changing the month from 31st January to February would make the day-of-month invalid. 939 * In cases like this, the field is responsible for resolving the date. Typically it will choose 940 * the previous valid date, which would be the last valid day of February in this example. 941 * <p> 942 * If the field is a {@link ChronoField} then the adjustment is implemented here. 943 * The {@link #isSupported(TemporalField) supported fields} will behave as per 944 * the matching method on {@link LocalDate#with(TemporalField, long) LocalDate} 945 * or {@link LocalTime#with(TemporalField, long) LocalTime}. 946 * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}. 947 * <p> 948 * If the field is not a {@code ChronoField}, then the result of this method 949 * is obtained by invoking {@code TemporalField.adjustInto(Temporal, long)} 950 * passing {@code this} as the argument. In this case, the field determines 951 * whether and how to adjust the instant. 952 * <p> 953 * This instance is immutable and unaffected by this method call. 954 * 955 * @param field the field to set in the result, not null 956 * @param newValue the new value of the field in the result 957 * @return a {@code LocalDateTime} based on {@code this} with the specified field set, not null 958 * @throws DateTimeException if the field cannot be set 959 * @throws UnsupportedTemporalTypeException if the field is not supported 960 * @throws ArithmeticException if numeric overflow occurs 961 */ 962 @Override 963 public LocalDateTime with(TemporalField field, long newValue) { 964 if (field instanceof ChronoField chronoField) { 965 if (chronoField.isTimeBased()) { 966 return with(date, time.with(field, newValue)); 967 } else { 968 return with(date.with(field, newValue), time); 969 } 970 } 971 return field.adjustInto(this, newValue); 972 } 973 974 //----------------------------------------------------------------------- 975 /** 976 * Returns a copy of this {@code LocalDateTime} with the year altered. 977 * <p> 978 * The time does not affect the calculation and will be the same in the result. 979 * If the day-of-month is invalid for the year, it will be changed to the last valid day of the month. 980 * <p> 981 * This instance is immutable and unaffected by this method call. 982 * 983 * @param year the year to set in the result, from MIN_YEAR to MAX_YEAR 984 * @return a {@code LocalDateTime} based on this date-time with the requested year, not null 985 * @throws DateTimeException if the year value is invalid 986 */ 987 public LocalDateTime withYear(int year) { 988 return with(date.withYear(year), time); 989 } 990 991 /** 992 * Returns a copy of this {@code LocalDateTime} with the month-of-year altered. 993 * <p> 994 * The time does not affect the calculation and will be the same in the result. 995 * If the day-of-month is invalid for the year, it will be changed to the last valid day of the month. 996 * <p> 997 * This instance is immutable and unaffected by this method call. 998 * 999 * @param month the month-of-year to set in the result, from 1 (January) to 12 (December) 1000 * @return a {@code LocalDateTime} based on this date-time with the requested month, not null 1001 * @throws DateTimeException if the month-of-year value is invalid 1002 */ 1003 public LocalDateTime withMonth(int month) { 1004 return with(date.withMonth(month), time); 1005 } 1006 1007 /** 1008 * Returns a copy of this {@code LocalDateTime} with the day-of-month altered. 1009 * <p> 1010 * If the resulting date-time is invalid, an exception is thrown. 1011 * The time does not affect the calculation and will be the same in the result. 1012 * <p> 1013 * This instance is immutable and unaffected by this method call. 1014 * 1015 * @param dayOfMonth the day-of-month to set in the result, from 1 to 28-31 1016 * @return a {@code LocalDateTime} based on this date-time with the requested day, not null 1017 * @throws DateTimeException if the day-of-month value is invalid, 1018 * or if the day-of-month is invalid for the month-year 1019 */ 1020 public LocalDateTime withDayOfMonth(int dayOfMonth) { 1021 return with(date.withDayOfMonth(dayOfMonth), time); 1022 } 1023 1024 /** 1025 * Returns a copy of this {@code LocalDateTime} with the day-of-year altered. 1026 * <p> 1027 * If the resulting date-time is invalid, an exception is thrown. 1028 * <p> 1029 * This instance is immutable and unaffected by this method call. 1030 * 1031 * @param dayOfYear the day-of-year to set in the result, from 1 to 365-366 1032 * @return a {@code LocalDateTime} based on this date with the requested day, not null 1033 * @throws DateTimeException if the day-of-year value is invalid, 1034 * or if the day-of-year is invalid for the year 1035 */ 1036 public LocalDateTime withDayOfYear(int dayOfYear) { 1037 return with(date.withDayOfYear(dayOfYear), time); 1038 } 1039 1040 //----------------------------------------------------------------------- 1041 /** 1042 * Returns a copy of this {@code LocalDateTime} with the hour-of-day altered. 1043 * <p> 1044 * This instance is immutable and unaffected by this method call. 1045 * 1046 * @param hour the hour-of-day to set in the result, from 0 to 23 1047 * @return a {@code LocalDateTime} based on this date-time with the requested hour, not null 1048 * @throws DateTimeException if the hour value is invalid 1049 */ 1050 public LocalDateTime withHour(int hour) { 1051 LocalTime newTime = time.withHour(hour); 1052 return with(date, newTime); 1053 } 1054 1055 /** 1056 * Returns a copy of this {@code LocalDateTime} with the minute-of-hour altered. 1057 * <p> 1058 * This instance is immutable and unaffected by this method call. 1059 * 1060 * @param minute the minute-of-hour to set in the result, from 0 to 59 1061 * @return a {@code LocalDateTime} based on this date-time with the requested minute, not null 1062 * @throws DateTimeException if the minute value is invalid 1063 */ 1064 public LocalDateTime withMinute(int minute) { 1065 LocalTime newTime = time.withMinute(minute); 1066 return with(date, newTime); 1067 } 1068 1069 /** 1070 * Returns a copy of this {@code LocalDateTime} with the second-of-minute altered. 1071 * <p> 1072 * This instance is immutable and unaffected by this method call. 1073 * 1074 * @param second the second-of-minute to set in the result, from 0 to 59 1075 * @return a {@code LocalDateTime} based on this date-time with the requested second, not null 1076 * @throws DateTimeException if the second value is invalid 1077 */ 1078 public LocalDateTime withSecond(int second) { 1079 LocalTime newTime = time.withSecond(second); 1080 return with(date, newTime); 1081 } 1082 1083 /** 1084 * Returns a copy of this {@code LocalDateTime} with the nano-of-second altered. 1085 * <p> 1086 * This instance is immutable and unaffected by this method call. 1087 * 1088 * @param nanoOfSecond the nano-of-second to set in the result, from 0 to 999,999,999 1089 * @return a {@code LocalDateTime} based on this date-time with the requested nanosecond, not null 1090 * @throws DateTimeException if the nano value is invalid 1091 */ 1092 public LocalDateTime withNano(int nanoOfSecond) { 1093 LocalTime newTime = time.withNano(nanoOfSecond); 1094 return with(date, newTime); 1095 } 1096 1097 //----------------------------------------------------------------------- 1098 /** 1099 * Returns a copy of this {@code LocalDateTime} with the time truncated. 1100 * <p> 1101 * Truncation returns a copy of the original date-time with fields 1102 * smaller than the specified unit set to zero. 1103 * For example, truncating with the {@link ChronoUnit#MINUTES minutes} unit 1104 * will set the second-of-minute and nano-of-second field to zero. 1105 * <p> 1106 * The unit must have a {@linkplain TemporalUnit#getDuration() duration} 1107 * that divides into the length of a standard day without remainder. 1108 * This includes all supplied time units on {@link ChronoUnit} and 1109 * {@link ChronoUnit#DAYS DAYS}. Other units throw an exception. 1110 * <p> 1111 * This instance is immutable and unaffected by this method call. 1112 * 1113 * @param unit the unit to truncate to, not null 1114 * @return a {@code LocalDateTime} based on this date-time with the time truncated, not null 1115 * @throws DateTimeException if unable to truncate 1116 * @throws UnsupportedTemporalTypeException if the unit is not supported 1117 */ 1118 public LocalDateTime truncatedTo(TemporalUnit unit) { 1119 return with(date, time.truncatedTo(unit)); 1120 } 1121 1122 //----------------------------------------------------------------------- 1123 /** 1124 * Returns a copy of this date-time with the specified amount added. 1125 * <p> 1126 * This returns a {@code LocalDateTime}, based on this one, with the specified amount added. 1127 * The amount is typically {@link Period} or {@link Duration} but may be 1128 * any other type implementing the {@link TemporalAmount} interface. 1129 * <p> 1130 * The calculation is delegated to the amount object by calling 1131 * {@link TemporalAmount#addTo(Temporal)}. The amount implementation is free 1132 * to implement the addition in any way it wishes, however it typically 1133 * calls back to {@link #plus(long, TemporalUnit)}. Consult the documentation 1134 * of the amount implementation to determine if it can be successfully added. 1135 * <p> 1136 * This instance is immutable and unaffected by this method call. 1137 * 1138 * @param amountToAdd the amount to add, not null 1139 * @return a {@code LocalDateTime} based on this date-time with the addition made, not null 1140 * @throws DateTimeException if the addition cannot be made 1141 * @throws ArithmeticException if numeric overflow occurs 1142 */ 1143 @Override 1144 public LocalDateTime plus(TemporalAmount amountToAdd) { 1145 if (amountToAdd instanceof Period periodToAdd) { 1146 return with(date.plus(periodToAdd), time); 1147 } 1148 Objects.requireNonNull(amountToAdd, "amountToAdd"); 1149 return (LocalDateTime) amountToAdd.addTo(this); 1150 } 1151 1152 /** 1153 * Returns a copy of this date-time with the specified amount added. 1154 * <p> 1155 * This returns a {@code LocalDateTime}, based on this one, with the amount 1156 * in terms of the unit added. If it is not possible to add the amount, because the 1157 * unit is not supported or for some other reason, an exception is thrown. 1158 * <p> 1159 * If the field is a {@link ChronoUnit} then the addition is implemented here. 1160 * Date units are added as per {@link LocalDate#plus(long, TemporalUnit)}. 1161 * Time units are added as per {@link LocalTime#plus(long, TemporalUnit)} with 1162 * any overflow in days added equivalent to using {@link #plusDays(long)}. 1163 * <p> 1164 * If the field is not a {@code ChronoUnit}, then the result of this method 1165 * is obtained by invoking {@code TemporalUnit.addTo(Temporal, long)} 1166 * passing {@code this} as the argument. In this case, the unit determines 1167 * whether and how to perform the addition. 1168 * <p> 1169 * This instance is immutable and unaffected by this method call. 1170 * 1171 * @param amountToAdd the amount of the unit to add to the result, may be negative 1172 * @param unit the unit of the amount to add, not null 1173 * @return a {@code LocalDateTime} based on this date-time with the specified amount added, not null 1174 * @throws DateTimeException if the addition cannot be made 1175 * @throws UnsupportedTemporalTypeException if the unit is not supported 1176 * @throws ArithmeticException if numeric overflow occurs 1177 */ 1178 @Override 1179 public LocalDateTime plus(long amountToAdd, TemporalUnit unit) { 1180 if (unit instanceof ChronoUnit chronoUnit) { 1181 return switch (chronoUnit) { 1182 case NANOS -> plusNanos(amountToAdd); 1183 case MICROS -> plusDays(amountToAdd / MICROS_PER_DAY).plusNanos((amountToAdd % MICROS_PER_DAY) * 1000); 1184 case MILLIS -> plusDays(amountToAdd / MILLIS_PER_DAY).plusNanos((amountToAdd % MILLIS_PER_DAY) * 1000_000); 1185 case SECONDS -> plusSeconds(amountToAdd); 1186 case MINUTES -> plusMinutes(amountToAdd); 1187 case HOURS -> plusHours(amountToAdd); 1188 case HALF_DAYS -> plusDays(amountToAdd / 256).plusHours((amountToAdd % 256) * 12); // no overflow (256 is multiple of 2) 1189 default -> with(date.plus(amountToAdd, unit), time); 1190 }; 1191 } 1192 return unit.addTo(this, amountToAdd); 1193 } 1194 1195 //----------------------------------------------------------------------- 1196 /** 1197 * Returns a copy of this {@code LocalDateTime} with the specified number of years added. 1198 * <p> 1199 * This method adds the specified amount to the years field in three steps: 1200 * <ol> 1201 * <li>Add the input years to the year field</li> 1202 * <li>Check if the resulting date would be invalid</li> 1203 * <li>Adjust the day-of-month to the last valid day if necessary</li> 1204 * </ol> 1205 * <p> 1206 * For example, 2008-02-29 (leap year) plus one year would result in the 1207 * invalid date 2009-02-29 (standard year). Instead of returning an invalid 1208 * result, the last valid day of the month, 2009-02-28, is selected instead. 1209 * <p> 1210 * This instance is immutable and unaffected by this method call. 1211 * 1212 * @param years the years to add, may be negative 1213 * @return a {@code LocalDateTime} based on this date-time with the years added, not null 1214 * @throws DateTimeException if the result exceeds the supported date range 1215 */ 1216 public LocalDateTime plusYears(long years) { 1217 LocalDate newDate = date.plusYears(years); 1218 return with(newDate, time); 1219 } 1220 1221 /** 1222 * Returns a copy of this {@code LocalDateTime} with the specified number of months added. 1223 * <p> 1224 * This method adds the specified amount to the months field in three steps: 1225 * <ol> 1226 * <li>Add the input months to the month-of-year field</li> 1227 * <li>Check if the resulting date would be invalid</li> 1228 * <li>Adjust the day-of-month to the last valid day if necessary</li> 1229 * </ol> 1230 * <p> 1231 * For example, 2007-03-31 plus one month would result in the invalid date 1232 * 2007-04-31. Instead of returning an invalid result, the last valid day 1233 * of the month, 2007-04-30, is selected instead. 1234 * <p> 1235 * This instance is immutable and unaffected by this method call. 1236 * 1237 * @param months the months to add, may be negative 1238 * @return a {@code LocalDateTime} based on this date-time with the months added, not null 1239 * @throws DateTimeException if the result exceeds the supported date range 1240 */ 1241 public LocalDateTime plusMonths(long months) { 1242 LocalDate newDate = date.plusMonths(months); 1243 return with(newDate, time); 1244 } 1245 1246 /** 1247 * Returns a copy of this {@code LocalDateTime} with the specified number of weeks added. 1248 * <p> 1249 * This method adds the specified amount in weeks to the days field incrementing 1250 * the month and year fields as necessary to ensure the result remains valid. 1251 * The result is only invalid if the maximum/minimum year is exceeded. 1252 * <p> 1253 * For example, 2008-12-31 plus one week would result in 2009-01-07. 1254 * <p> 1255 * This instance is immutable and unaffected by this method call. 1256 * 1257 * @param weeks the weeks to add, may be negative 1258 * @return a {@code LocalDateTime} based on this date-time with the weeks added, not null 1259 * @throws DateTimeException if the result exceeds the supported date range 1260 */ 1261 public LocalDateTime plusWeeks(long weeks) { 1262 LocalDate newDate = date.plusWeeks(weeks); 1263 return with(newDate, time); 1264 } 1265 1266 /** 1267 * Returns a copy of this {@code LocalDateTime} with the specified number of days added. 1268 * <p> 1269 * This method adds the specified amount to the days field incrementing the 1270 * month and year fields as necessary to ensure the result remains valid. 1271 * The result is only invalid if the maximum/minimum year is exceeded. 1272 * <p> 1273 * For example, 2008-12-31 plus one day would result in 2009-01-01. 1274 * <p> 1275 * This instance is immutable and unaffected by this method call. 1276 * 1277 * @param days the days to add, may be negative 1278 * @return a {@code LocalDateTime} based on this date-time with the days added, not null 1279 * @throws DateTimeException if the result exceeds the supported date range 1280 */ 1281 public LocalDateTime plusDays(long days) { 1282 LocalDate newDate = date.plusDays(days); 1283 return with(newDate, time); 1284 } 1285 1286 //----------------------------------------------------------------------- 1287 /** 1288 * Returns a copy of this {@code LocalDateTime} with the specified number of hours added. 1289 * <p> 1290 * This instance is immutable and unaffected by this method call. 1291 * 1292 * @param hours the hours to add, may be negative 1293 * @return a {@code LocalDateTime} based on this date-time with the hours added, not null 1294 * @throws DateTimeException if the result exceeds the supported date range 1295 */ 1296 public LocalDateTime plusHours(long hours) { 1297 return plusWithOverflow(date, hours, 0, 0, 0, 1); 1298 } 1299 1300 /** 1301 * Returns a copy of this {@code LocalDateTime} with the specified number of minutes added. 1302 * <p> 1303 * This instance is immutable and unaffected by this method call. 1304 * 1305 * @param minutes the minutes to add, may be negative 1306 * @return a {@code LocalDateTime} based on this date-time with the minutes added, not null 1307 * @throws DateTimeException if the result exceeds the supported date range 1308 */ 1309 public LocalDateTime plusMinutes(long minutes) { 1310 return plusWithOverflow(date, 0, minutes, 0, 0, 1); 1311 } 1312 1313 /** 1314 * Returns a copy of this {@code LocalDateTime} with the specified number of seconds added. 1315 * <p> 1316 * This instance is immutable and unaffected by this method call. 1317 * 1318 * @param seconds the seconds to add, may be negative 1319 * @return a {@code LocalDateTime} based on this date-time with the seconds added, not null 1320 * @throws DateTimeException if the result exceeds the supported date range 1321 */ 1322 public LocalDateTime plusSeconds(long seconds) { 1323 return plusWithOverflow(date, 0, 0, seconds, 0, 1); 1324 } 1325 1326 /** 1327 * Returns a copy of this {@code LocalDateTime} with the specified number of nanoseconds added. 1328 * <p> 1329 * This instance is immutable and unaffected by this method call. 1330 * 1331 * @param nanos the nanos to add, may be negative 1332 * @return a {@code LocalDateTime} based on this date-time with the nanoseconds added, not null 1333 * @throws DateTimeException if the result exceeds the supported date range 1334 */ 1335 public LocalDateTime plusNanos(long nanos) { 1336 return plusWithOverflow(date, 0, 0, 0, nanos, 1); 1337 } 1338 1339 //----------------------------------------------------------------------- 1340 /** 1341 * Returns a copy of this date-time with the specified amount subtracted. 1342 * <p> 1343 * This returns a {@code LocalDateTime}, based on this one, with the specified amount subtracted. 1344 * The amount is typically {@link Period} or {@link Duration} but may be 1345 * any other type implementing the {@link TemporalAmount} interface. 1346 * <p> 1347 * The calculation is delegated to the amount object by calling 1348 * {@link TemporalAmount#subtractFrom(Temporal)}. The amount implementation is free 1349 * to implement the subtraction in any way it wishes, however it typically 1350 * calls back to {@link #minus(long, TemporalUnit)}. Consult the documentation 1351 * of the amount implementation to determine if it can be successfully subtracted. 1352 * <p> 1353 * This instance is immutable and unaffected by this method call. 1354 * 1355 * @param amountToSubtract the amount to subtract, not null 1356 * @return a {@code LocalDateTime} based on this date-time with the subtraction made, not null 1357 * @throws DateTimeException if the subtraction cannot be made 1358 * @throws ArithmeticException if numeric overflow occurs 1359 */ 1360 @Override 1361 public LocalDateTime minus(TemporalAmount amountToSubtract) { 1362 if (amountToSubtract instanceof Period periodToSubtract) { 1363 return with(date.minus(periodToSubtract), time); 1364 } 1365 Objects.requireNonNull(amountToSubtract, "amountToSubtract"); 1366 return (LocalDateTime) amountToSubtract.subtractFrom(this); 1367 } 1368 1369 /** 1370 * Returns a copy of this date-time with the specified amount subtracted. 1371 * <p> 1372 * This returns a {@code LocalDateTime}, based on this one, with the amount 1373 * in terms of the unit subtracted. If it is not possible to subtract the amount, 1374 * because the unit is not supported or for some other reason, an exception is thrown. 1375 * <p> 1376 * This method is equivalent to {@link #plus(long, TemporalUnit)} with the amount negated. 1377 * See that method for a full description of how addition, and thus subtraction, works. 1378 * <p> 1379 * This instance is immutable and unaffected by this method call. 1380 * 1381 * @param amountToSubtract the amount of the unit to subtract from the result, may be negative 1382 * @param unit the unit of the amount to subtract, not null 1383 * @return a {@code LocalDateTime} based on this date-time with the specified amount subtracted, not null 1384 * @throws DateTimeException if the subtraction cannot be made 1385 * @throws UnsupportedTemporalTypeException if the unit is not supported 1386 * @throws ArithmeticException if numeric overflow occurs 1387 */ 1388 @Override 1389 public LocalDateTime minus(long amountToSubtract, TemporalUnit unit) { 1390 return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit)); 1391 } 1392 1393 //----------------------------------------------------------------------- 1394 /** 1395 * Returns a copy of this {@code LocalDateTime} with the specified number of years subtracted. 1396 * <p> 1397 * This method subtracts the specified amount from the years field in three steps: 1398 * <ol> 1399 * <li>Subtract the input years from the year field</li> 1400 * <li>Check if the resulting date would be invalid</li> 1401 * <li>Adjust the day-of-month to the last valid day if necessary</li> 1402 * </ol> 1403 * <p> 1404 * For example, 2008-02-29 (leap year) minus one year would result in the 1405 * invalid date 2007-02-29 (standard year). Instead of returning an invalid 1406 * result, the last valid day of the month, 2007-02-28, is selected instead. 1407 * <p> 1408 * This instance is immutable and unaffected by this method call. 1409 * 1410 * @param years the years to subtract, may be negative 1411 * @return a {@code LocalDateTime} based on this date-time with the years subtracted, not null 1412 * @throws DateTimeException if the result exceeds the supported date range 1413 */ 1414 public LocalDateTime minusYears(long years) { 1415 return (years == Long.MIN_VALUE ? plusYears(Long.MAX_VALUE).plusYears(1) : plusYears(-years)); 1416 } 1417 1418 /** 1419 * Returns a copy of this {@code LocalDateTime} with the specified number of months subtracted. 1420 * <p> 1421 * This method subtracts the specified amount from the months field in three steps: 1422 * <ol> 1423 * <li>Subtract the input months from the month-of-year field</li> 1424 * <li>Check if the resulting date would be invalid</li> 1425 * <li>Adjust the day-of-month to the last valid day if necessary</li> 1426 * </ol> 1427 * <p> 1428 * For example, 2007-03-31 minus one month would result in the invalid date 1429 * 2007-02-31. Instead of returning an invalid result, the last valid day 1430 * of the month, 2007-02-28, is selected instead. 1431 * <p> 1432 * This instance is immutable and unaffected by this method call. 1433 * 1434 * @param months the months to subtract, may be negative 1435 * @return a {@code LocalDateTime} based on this date-time with the months subtracted, not null 1436 * @throws DateTimeException if the result exceeds the supported date range 1437 */ 1438 public LocalDateTime minusMonths(long months) { 1439 return (months == Long.MIN_VALUE ? plusMonths(Long.MAX_VALUE).plusMonths(1) : plusMonths(-months)); 1440 } 1441 1442 /** 1443 * Returns a copy of this {@code LocalDateTime} with the specified number of weeks subtracted. 1444 * <p> 1445 * This method subtracts the specified amount in weeks from the days field decrementing 1446 * the month and year fields as necessary to ensure the result remains valid. 1447 * The result is only invalid if the maximum/minimum year is exceeded. 1448 * <p> 1449 * For example, 2009-01-07 minus one week would result in 2008-12-31. 1450 * <p> 1451 * This instance is immutable and unaffected by this method call. 1452 * 1453 * @param weeks the weeks to subtract, may be negative 1454 * @return a {@code LocalDateTime} based on this date-time with the weeks subtracted, not null 1455 * @throws DateTimeException if the result exceeds the supported date range 1456 */ 1457 public LocalDateTime minusWeeks(long weeks) { 1458 return (weeks == Long.MIN_VALUE ? plusWeeks(Long.MAX_VALUE).plusWeeks(1) : plusWeeks(-weeks)); 1459 } 1460 1461 /** 1462 * Returns a copy of this {@code LocalDateTime} with the specified number of days subtracted. 1463 * <p> 1464 * This method subtracts the specified amount from the days field decrementing the 1465 * month and year fields as necessary to ensure the result remains valid. 1466 * The result is only invalid if the maximum/minimum year is exceeded. 1467 * <p> 1468 * For example, 2009-01-01 minus one day would result in 2008-12-31. 1469 * <p> 1470 * This instance is immutable and unaffected by this method call. 1471 * 1472 * @param days the days to subtract, may be negative 1473 * @return a {@code LocalDateTime} based on this date-time with the days subtracted, not null 1474 * @throws DateTimeException if the result exceeds the supported date range 1475 */ 1476 public LocalDateTime minusDays(long days) { 1477 return (days == Long.MIN_VALUE ? plusDays(Long.MAX_VALUE).plusDays(1) : plusDays(-days)); 1478 } 1479 1480 //----------------------------------------------------------------------- 1481 /** 1482 * Returns a copy of this {@code LocalDateTime} with the specified number of hours subtracted. 1483 * <p> 1484 * This instance is immutable and unaffected by this method call. 1485 * 1486 * @param hours the hours to subtract, may be negative 1487 * @return a {@code LocalDateTime} based on this date-time with the hours subtracted, not null 1488 * @throws DateTimeException if the result exceeds the supported date range 1489 */ 1490 public LocalDateTime minusHours(long hours) { 1491 return plusWithOverflow(date, hours, 0, 0, 0, -1); 1492 } 1493 1494 /** 1495 * Returns a copy of this {@code LocalDateTime} with the specified number of minutes subtracted. 1496 * <p> 1497 * This instance is immutable and unaffected by this method call. 1498 * 1499 * @param minutes the minutes to subtract, may be negative 1500 * @return a {@code LocalDateTime} based on this date-time with the minutes subtracted, not null 1501 * @throws DateTimeException if the result exceeds the supported date range 1502 */ 1503 public LocalDateTime minusMinutes(long minutes) { 1504 return plusWithOverflow(date, 0, minutes, 0, 0, -1); 1505 } 1506 1507 /** 1508 * Returns a copy of this {@code LocalDateTime} with the specified number of seconds subtracted. 1509 * <p> 1510 * This instance is immutable and unaffected by this method call. 1511 * 1512 * @param seconds the seconds to subtract, may be negative 1513 * @return a {@code LocalDateTime} based on this date-time with the seconds subtracted, not null 1514 * @throws DateTimeException if the result exceeds the supported date range 1515 */ 1516 public LocalDateTime minusSeconds(long seconds) { 1517 return plusWithOverflow(date, 0, 0, seconds, 0, -1); 1518 } 1519 1520 /** 1521 * Returns a copy of this {@code LocalDateTime} with the specified number of nanoseconds subtracted. 1522 * <p> 1523 * This instance is immutable and unaffected by this method call. 1524 * 1525 * @param nanos the nanos to subtract, may be negative 1526 * @return a {@code LocalDateTime} based on this date-time with the nanoseconds subtracted, not null 1527 * @throws DateTimeException if the result exceeds the supported date range 1528 */ 1529 public LocalDateTime minusNanos(long nanos) { 1530 return plusWithOverflow(date, 0, 0, 0, nanos, -1); 1531 } 1532 1533 //----------------------------------------------------------------------- 1534 /** 1535 * Returns a copy of this {@code LocalDateTime} with the specified period added. 1536 * <p> 1537 * This instance is immutable and unaffected by this method call. 1538 * 1539 * @param newDate the new date to base the calculation on, not null 1540 * @param hours the hours to add, may be negative 1541 * @param minutes the minutes to add, may be negative 1542 * @param seconds the seconds to add, may be negative 1543 * @param nanos the nanos to add, may be negative 1544 * @param sign the sign to determine add or subtract 1545 * @return the combined result, not null 1546 */ 1547 private LocalDateTime plusWithOverflow(LocalDate newDate, long hours, long minutes, long seconds, long nanos, int sign) { 1548 // 9223372036854775808 long, 2147483648 int 1549 if ((hours | minutes | seconds | nanos) == 0) { 1550 return with(newDate, time); 1551 } 1552 long totDays = nanos / NANOS_PER_DAY + // max/24*60*60*1B 1553 seconds / SECONDS_PER_DAY + // max/24*60*60 1554 minutes / MINUTES_PER_DAY + // max/24*60 1555 hours / HOURS_PER_DAY; // max/24 1556 totDays *= sign; // total max*0.4237... 1557 long totNanos = nanos % NANOS_PER_DAY + // max 86400000000000 1558 (seconds % SECONDS_PER_DAY) * NANOS_PER_SECOND + // max 86400000000000 1559 (minutes % MINUTES_PER_DAY) * NANOS_PER_MINUTE + // max 86400000000000 1560 (hours % HOURS_PER_DAY) * NANOS_PER_HOUR; // max 86400000000000 1561 long curNoD = time.toNanoOfDay(); // max 86400000000000 1562 totNanos = totNanos * sign + curNoD; // total 432000000000000 1563 totDays += Math.floorDiv(totNanos, NANOS_PER_DAY); 1564 long newNoD = Math.floorMod(totNanos, NANOS_PER_DAY); 1565 LocalTime newTime = (newNoD == curNoD ? time : LocalTime.ofNanoOfDay(newNoD)); 1566 return with(newDate.plusDays(totDays), newTime); 1567 } 1568 1569 //----------------------------------------------------------------------- 1570 /** 1571 * Queries this date-time using the specified query. 1572 * <p> 1573 * This queries this date-time using the specified query strategy object. 1574 * The {@code TemporalQuery} object defines the logic to be used to 1575 * obtain the result. Read the documentation of the query to understand 1576 * what the result of this method will be. 1577 * <p> 1578 * The result of this method is obtained by invoking the 1579 * {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the 1580 * specified query passing {@code this} as the argument. 1581 * 1582 * @param <R> the type of the result 1583 * @param query the query to invoke, not null 1584 * @return the query result, null may be returned (defined by the query) 1585 * @throws DateTimeException if unable to query (defined by the query) 1586 * @throws ArithmeticException if numeric overflow occurs (defined by the query) 1587 */ 1588 @SuppressWarnings("unchecked") 1589 @Override // override for Javadoc 1590 public <R> R query(TemporalQuery<R> query) { 1591 if (query == TemporalQueries.localDate()) { 1592 return (R) date; 1593 } 1594 return ChronoLocalDateTime.super.query(query); 1595 } 1596 1597 /** 1598 * Adjusts the specified temporal object to have the same date and time as this object. 1599 * <p> 1600 * This returns a temporal object of the same observable type as the input 1601 * with the date and time changed to be the same as this. 1602 * <p> 1603 * The adjustment is equivalent to using {@link Temporal#with(TemporalField, long)} 1604 * twice, passing {@link ChronoField#EPOCH_DAY} and 1605 * {@link ChronoField#NANO_OF_DAY} as the fields. 1606 * <p> 1607 * In most cases, it is clearer to reverse the calling pattern by using 1608 * {@link Temporal#with(TemporalAdjuster)}: 1609 * <pre> 1610 * // these two lines are equivalent, but the second approach is recommended 1611 * temporal = thisLocalDateTime.adjustInto(temporal); 1612 * temporal = temporal.with(thisLocalDateTime); 1613 * </pre> 1614 * <p> 1615 * This instance is immutable and unaffected by this method call. 1616 * 1617 * @param temporal the target object to be adjusted, not null 1618 * @return the adjusted object, not null 1619 * @throws DateTimeException if unable to make the adjustment 1620 * @throws ArithmeticException if numeric overflow occurs 1621 */ 1622 @Override // override for Javadoc 1623 public Temporal adjustInto(Temporal temporal) { 1624 return ChronoLocalDateTime.super.adjustInto(temporal); 1625 } 1626 1627 /** 1628 * Calculates the amount of time until another date-time in terms of the specified unit. 1629 * <p> 1630 * This calculates the amount of time between two {@code LocalDateTime} 1631 * objects in terms of a single {@code TemporalUnit}. 1632 * The start and end points are {@code this} and the specified date-time. 1633 * The result will be negative if the end is before the start. 1634 * The {@code Temporal} passed to this method is converted to a 1635 * {@code LocalDateTime} using {@link #from(TemporalAccessor)}. 1636 * For example, the amount in days between two date-times can be calculated 1637 * using {@code startDateTime.until(endDateTime, DAYS)}. 1638 * <p> 1639 * The calculation returns a whole number, representing the number of 1640 * complete units between the two date-times. 1641 * For example, the amount in months between 2012-06-15T00:00 and 2012-08-14T23:59 1642 * will only be one month as it is one minute short of two months. 1643 * <p> 1644 * There are two equivalent ways of using this method. 1645 * The first is to invoke this method. 1646 * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}: 1647 * <pre> 1648 * // these two lines are equivalent 1649 * amount = start.until(end, MONTHS); 1650 * amount = MONTHS.between(start, end); 1651 * </pre> 1652 * The choice should be made based on which makes the code more readable. 1653 * <p> 1654 * The calculation is implemented in this method for {@link ChronoUnit}. 1655 * The units {@code NANOS}, {@code MICROS}, {@code MILLIS}, {@code SECONDS}, 1656 * {@code MINUTES}, {@code HOURS} and {@code HALF_DAYS}, {@code DAYS}, 1657 * {@code WEEKS}, {@code MONTHS}, {@code YEARS}, {@code DECADES}, 1658 * {@code CENTURIES}, {@code MILLENNIA} and {@code ERAS} are supported. 1659 * Other {@code ChronoUnit} values will throw an exception. 1660 * <p> 1661 * If the unit is not a {@code ChronoUnit}, then the result of this method 1662 * is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)} 1663 * passing {@code this} as the first argument and the converted input temporal 1664 * as the second argument. 1665 * <p> 1666 * This instance is immutable and unaffected by this method call. 1667 * 1668 * @param endExclusive the end date, exclusive, which is converted to a {@code LocalDateTime}, not null 1669 * @param unit the unit to measure the amount in, not null 1670 * @return the amount of time between this date-time and the end date-time 1671 * @throws DateTimeException if the amount cannot be calculated, or the end 1672 * temporal cannot be converted to a {@code LocalDateTime} 1673 * @throws UnsupportedTemporalTypeException if the unit is not supported 1674 * @throws ArithmeticException if numeric overflow occurs 1675 */ 1676 @Override 1677 public long until(Temporal endExclusive, TemporalUnit unit) { 1678 LocalDateTime end = LocalDateTime.from(endExclusive); 1679 if (unit instanceof ChronoUnit chronoUnit) { 1680 if (unit.isTimeBased()) { 1681 long amount = date.daysUntil(end.date); 1682 if (amount == 0) { 1683 return time.until(end.time, unit); 1684 } 1685 long timePart = end.time.toNanoOfDay() - time.toNanoOfDay(); 1686 if (amount > 0) { 1687 amount--; // safe 1688 timePart += NANOS_PER_DAY; // safe 1689 } else { 1690 amount++; // safe 1691 timePart -= NANOS_PER_DAY; // safe 1692 } 1693 switch (chronoUnit) { 1694 case NANOS: 1695 amount = Math.multiplyExact(amount, NANOS_PER_DAY); 1696 break; 1697 case MICROS: 1698 amount = Math.multiplyExact(amount, MICROS_PER_DAY); 1699 timePart = timePart / 1000; 1700 break; 1701 case MILLIS: 1702 amount = Math.multiplyExact(amount, MILLIS_PER_DAY); 1703 timePart = timePart / 1_000_000; 1704 break; 1705 case SECONDS: 1706 amount = Math.multiplyExact(amount, SECONDS_PER_DAY); 1707 timePart = timePart / NANOS_PER_SECOND; 1708 break; 1709 case MINUTES: 1710 amount = Math.multiplyExact(amount, MINUTES_PER_DAY); 1711 timePart = timePart / NANOS_PER_MINUTE; 1712 break; 1713 case HOURS: 1714 amount = Math.multiplyExact(amount, HOURS_PER_DAY); 1715 timePart = timePart / NANOS_PER_HOUR; 1716 break; 1717 case HALF_DAYS: 1718 amount = Math.multiplyExact(amount, 2); 1719 timePart = timePart / (NANOS_PER_HOUR * 12); 1720 break; 1721 } 1722 return Math.addExact(amount, timePart); 1723 } 1724 LocalDate endDate = end.date; 1725 if (endDate.isAfter(date) && end.time.isBefore(time)) { 1726 endDate = endDate.minusDays(1); 1727 } else if (endDate.isBefore(date) && end.time.isAfter(time)) { 1728 endDate = endDate.plusDays(1); 1729 } 1730 return date.until(endDate, unit); 1731 } 1732 return unit.between(this, end); 1733 } 1734 1735 /** 1736 * Formats this date-time using the specified formatter. 1737 * <p> 1738 * This date-time will be passed to the formatter to produce a string. 1739 * 1740 * @param formatter the formatter to use, not null 1741 * @return the formatted date-time string, not null 1742 * @throws DateTimeException if an error occurs during printing 1743 */ 1744 @Override // override for Javadoc and performance 1745 public String format(DateTimeFormatter formatter) { 1746 Objects.requireNonNull(formatter, "formatter"); 1747 return formatter.format(this); 1748 } 1749 1750 //----------------------------------------------------------------------- 1751 /** 1752 * Combines this date-time with an offset to create an {@code OffsetDateTime}. 1753 * <p> 1754 * This returns an {@code OffsetDateTime} formed from this date-time at the specified offset. 1755 * All possible combinations of date-time and offset are valid. 1756 * 1757 * @param offset the offset to combine with, not null 1758 * @return the offset date-time formed from this date-time and the specified offset, not null 1759 */ 1760 public OffsetDateTime atOffset(ZoneOffset offset) { 1761 return OffsetDateTime.of(this, offset); 1762 } 1763 1764 /** 1765 * Combines this date-time with a time-zone to create a {@code ZonedDateTime}. 1766 * <p> 1767 * This returns a {@code ZonedDateTime} formed from this date-time at the 1768 * specified time-zone. The result will match this date-time as closely as possible. 1769 * Time-zone rules, such as daylight savings, mean that not every local date-time 1770 * is valid for the specified zone, thus the local date-time may be adjusted. 1771 * <p> 1772 * The local date-time is resolved to a single instant on the time-line. 1773 * This is achieved by finding a valid offset from UTC/Greenwich for the local 1774 * date-time as defined by the {@link ZoneRules rules} of the zone ID. 1775 *<p> 1776 * In most cases, there is only one valid offset for a local date-time. 1777 * In the case of an overlap, where clocks are set back, there are two valid offsets. 1778 * This method uses the earlier offset typically corresponding to "summer". 1779 * <p> 1780 * In the case of a gap, where clocks jump forward, there is no valid offset. 1781 * Instead, the local date-time is adjusted to be later by the length of the gap. 1782 * For a typical one hour daylight savings change, the local date-time will be 1783 * moved one hour later into the offset typically corresponding to "summer". 1784 * <p> 1785 * To obtain the later offset during an overlap, call 1786 * {@link ZonedDateTime#withLaterOffsetAtOverlap()} on the result of this method. 1787 * To throw an exception when there is a gap or overlap, use 1788 * {@link ZonedDateTime#ofStrict(LocalDateTime, ZoneOffset, ZoneId)}. 1789 * 1790 * @param zone the time-zone to use, not null 1791 * @return the zoned date-time formed from this date-time, not null 1792 */ 1793 @Override 1794 public ZonedDateTime atZone(ZoneId zone) { 1795 return ZonedDateTime.of(this, zone); 1796 } 1797 1798 //----------------------------------------------------------------------- 1799 /** 1800 * Compares this date-time to another date-time. 1801 * <p> 1802 * The comparison is primarily based on the date-time, from earliest to latest. 1803 * It is "consistent with equals", as defined by {@link Comparable}. 1804 * <p> 1805 * If all the date-times being compared are instances of {@code LocalDateTime}, 1806 * then the comparison will be entirely based on the date-time. 1807 * If some dates being compared are in different chronologies, then the 1808 * chronology is also considered, see {@link ChronoLocalDateTime#compareTo}. 1809 * 1810 * @param other the other date-time to compare to, not null 1811 * @return the comparator value, that is the comparison of this local date-time with 1812 * the {@code other} local date-time and this chronology with the {@code other} chronology, 1813 * in order, returning the first non-zero result, and otherwise returning zero 1814 * @see #isBefore 1815 * @see #isAfter 1816 */ 1817 @Override // override for Javadoc and performance 1818 public int compareTo(ChronoLocalDateTime<?> other) { 1819 if (other instanceof LocalDateTime) { 1820 return compareTo0((LocalDateTime) other); 1821 } 1822 return ChronoLocalDateTime.super.compareTo(other); 1823 } 1824 1825 private int compareTo0(LocalDateTime other) { 1826 int cmp = date.compareTo0(other.toLocalDate()); 1827 if (cmp == 0) { 1828 cmp = time.compareTo(other.toLocalTime()); 1829 } 1830 return cmp; 1831 } 1832 1833 /** 1834 * Checks if this date-time is after the specified date-time. 1835 * <p> 1836 * This checks to see if this date-time represents a point on the 1837 * local time-line after the other date-time. 1838 * <pre> 1839 * LocalDate a = LocalDateTime.of(2012, 6, 30, 12, 00); 1840 * LocalDate b = LocalDateTime.of(2012, 7, 1, 12, 00); 1841 * a.isAfter(b) == false 1842 * a.isAfter(a) == false 1843 * b.isAfter(a) == true 1844 * </pre> 1845 * <p> 1846 * This method only considers the position of the two date-times on the local time-line. 1847 * It does not take into account the chronology, or calendar system. 1848 * This is different from the comparison in {@link #compareTo(ChronoLocalDateTime)}, 1849 * but is the same approach as {@link ChronoLocalDateTime#timeLineOrder()}. 1850 * 1851 * @param other the other date-time to compare to, not null 1852 * @return true if this date-time is after the specified date-time 1853 */ 1854 @Override // override for Javadoc and performance 1855 public boolean isAfter(ChronoLocalDateTime<?> other) { 1856 if (other instanceof LocalDateTime) { 1857 return compareTo0((LocalDateTime) other) > 0; 1858 } 1859 return ChronoLocalDateTime.super.isAfter(other); 1860 } 1861 1862 /** 1863 * Checks if this date-time is before the specified date-time. 1864 * <p> 1865 * This checks to see if this date-time represents a point on the 1866 * local time-line before the other date-time. 1867 * <pre> 1868 * LocalDate a = LocalDateTime.of(2012, 6, 30, 12, 00); 1869 * LocalDate b = LocalDateTime.of(2012, 7, 1, 12, 00); 1870 * a.isBefore(b) == true 1871 * a.isBefore(a) == false 1872 * b.isBefore(a) == false 1873 * </pre> 1874 * <p> 1875 * This method only considers the position of the two date-times on the local time-line. 1876 * It does not take into account the chronology, or calendar system. 1877 * This is different from the comparison in {@link #compareTo(ChronoLocalDateTime)}, 1878 * but is the same approach as {@link ChronoLocalDateTime#timeLineOrder()}. 1879 * 1880 * @param other the other date-time to compare to, not null 1881 * @return true if this date-time is before the specified date-time 1882 */ 1883 @Override // override for Javadoc and performance 1884 public boolean isBefore(ChronoLocalDateTime<?> other) { 1885 if (other instanceof LocalDateTime) { 1886 return compareTo0((LocalDateTime) other) < 0; 1887 } 1888 return ChronoLocalDateTime.super.isBefore(other); 1889 } 1890 1891 /** 1892 * Checks if this date-time is equal to the specified date-time. 1893 * <p> 1894 * This checks to see if this date-time represents the same point on the 1895 * local time-line as the other date-time. 1896 * <pre> 1897 * LocalDate a = LocalDateTime.of(2012, 6, 30, 12, 00); 1898 * LocalDate b = LocalDateTime.of(2012, 7, 1, 12, 00); 1899 * a.isEqual(b) == false 1900 * a.isEqual(a) == true 1901 * b.isEqual(a) == false 1902 * </pre> 1903 * <p> 1904 * This method only considers the position of the two date-times on the local time-line. 1905 * It does not take into account the chronology, or calendar system. 1906 * This is different from the comparison in {@link #compareTo(ChronoLocalDateTime)}, 1907 * but is the same approach as {@link ChronoLocalDateTime#timeLineOrder()}. 1908 * 1909 * @param other the other date-time to compare to, not null 1910 * @return true if this date-time is equal to the specified date-time 1911 */ 1912 @Override // override for Javadoc and performance 1913 public boolean isEqual(ChronoLocalDateTime<?> other) { 1914 if (other instanceof LocalDateTime) { 1915 return compareTo0((LocalDateTime) other) == 0; 1916 } 1917 return ChronoLocalDateTime.super.isEqual(other); 1918 } 1919 1920 //----------------------------------------------------------------------- 1921 /** 1922 * Checks if this date-time is equal to another date-time. 1923 * <p> 1924 * Compares this {@code LocalDateTime} with another ensuring that the date-time is the same. 1925 * Only objects of type {@code LocalDateTime} are compared, other types return false. 1926 * 1927 * @param obj the object to check, null returns false 1928 * @return true if this is equal to the other date-time 1929 */ 1930 @Override 1931 public boolean equals(Object obj) { 1932 if (this == obj) { 1933 return true; 1934 } 1935 return (obj instanceof LocalDateTime other) 1936 && date.equals(other.date) 1937 && time.equals(other.time); 1938 } 1939 1940 /** 1941 * A hash code for this date-time. 1942 * 1943 * @return a suitable hash code 1944 */ 1945 @Override 1946 public int hashCode() { 1947 return date.hashCode() ^ time.hashCode(); 1948 } 1949 1950 //----------------------------------------------------------------------- 1951 /** 1952 * Outputs this date-time as a {@code String}, such as {@code 2007-12-03T10:15:30}. 1953 * <p> 1954 * The output will be one of the following ISO-8601 formats: 1955 * <ul> 1956 * <li>{@code uuuu-MM-dd'T'HH:mm}</li> 1957 * <li>{@code uuuu-MM-dd'T'HH:mm:ss}</li> 1958 * <li>{@code uuuu-MM-dd'T'HH:mm:ss.SSS}</li> 1959 * <li>{@code uuuu-MM-dd'T'HH:mm:ss.SSSSSS}</li> 1960 * <li>{@code uuuu-MM-dd'T'HH:mm:ss.SSSSSSSSS}</li> 1961 * </ul> 1962 * The format used will be the shortest that outputs the full value of 1963 * the time where the omitted parts are implied to be zero. 1964 * 1965 * @return a string representation of this date-time, not null 1966 */ 1967 @Override 1968 public String toString() { 1969 return date.toString() + 'T' + time.toString(); 1970 } 1971 1972 //----------------------------------------------------------------------- 1973 /** 1974 * Writes the object using a 1975 * <a href="{@docRoot}/serialized-form.html#java.time.Ser">dedicated serialized form</a>. 1976 * @serialData 1977 * <pre> 1978 * out.writeByte(5); // identifies a LocalDateTime 1979 * // the <a href="{@docRoot}/serialized-form.html#java.time.LocalDate">date</a> excluding the one byte header 1980 * // the <a href="{@docRoot}/serialized-form.html#java.time.LocalTime">time</a> excluding the one byte header 1981 * </pre> 1982 * 1983 * @return the instance of {@code Ser}, not null 1984 */ 1985 @java.io.Serial 1986 private Object writeReplace() { 1987 return new Ser(Ser.LOCAL_DATE_TIME_TYPE, this); 1988 } 1989 1990 /** 1991 * Defend against malicious streams. 1992 * 1993 * @param s the stream to read 1994 * @throws InvalidObjectException always 1995 */ 1996 @java.io.Serial 1997 private void readObject(ObjectInputStream s) throws InvalidObjectException { 1998 throw new InvalidObjectException("Deserialization via serialization delegate"); 1999 } 2000 2001 void writeExternal(DataOutput out) throws IOException { 2002 date.writeExternal(out); 2003 time.writeExternal(out); 2004 } 2005 2006 static LocalDateTime readExternal(DataInput in) throws IOException { 2007 LocalDate date = LocalDate.readExternal(in); 2008 LocalTime time = LocalTime.readExternal(in); 2009 return LocalDateTime.of(date, time); 2010 } 2011 2012 }