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