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