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