Your browser does not support JavaScript and this site utilizes JavaScript to build content and provide links to additional information. You should either enable JavaScript in your browser settings or use a browser that supports JavaScript in order to take full advantage of this site.

1 /*2 * Copyright 2001-2006 Stephen Colebourne3 *4 * Licensed under the Apache License, Version 2.0 (the "License");5 * you may not use this file except in compliance with the License.6 * You may obtain a copy of the License at7 *8 * http://www.apache.org/licenses/LICENSE-2.09 *10 * Unless required by applicable law or agreed to in writing, software11 * distributed under the License is distributed on an "AS IS" BASIS,12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.13 * See the License for the specific language governing permissions and14 * limitations under the License.15 */16 package org.joda.time;17 18 importjava.io.IOException;19 importjava.io.ObjectInputStream;20 importjava.io.ObjectOutputStream;21 importjava.io.Serializable;22 importjava.util.Calendar;23 importjava.util.Date;24 importjava.util.Locale;25 26 importorg.joda.time.base.AbstractPartial;27 importorg.joda.time.chrono.ISOChronology;28 importorg.joda.time.convert.ConverterManager;29 importorg.joda.time.convert.PartialConverter;30 importorg.joda.time.field.AbstractReadableInstantFieldProperty;31 importorg.joda.time.format.DateTimeFormat;32 importorg.joda.time.format.ISODateTimeFormat;33 34 /**35 * LocalDateTime is an unmodifiable datetime class representing a36 * datetime without a time zone.37 * <p>38 * LocalDateTime implements the {@link ReadablePartial} interface.39 * To do this, certain methods focus on key fields Year, MonthOfYear,40 * DayOfYear and MillisOfDay.41 * However, <b>all</b> fields may in fact be queried.42 * <p>43 * Internally, LocalDateTime holds the datetime as milliseconds44 * from 1970-01-01T00:00:00. This represents the <i>local</i> millisecond45 * count which differs from the epoch-based millisecond value in a46 * <code>ReadableInstant</code> implementation by the amount of the zone offset.47 * <p>48 * Calculations on LocalDateTime are performed using a {@link Chronology}.49 * This chronology will be set internally to be in the UTC time zone50 * for all calculations.51 *52 * <p>Each individual field can be queried in two ways:53 * <ul>54 * <li><code>getHourOfDay()</code>55 * <li><code>hourOfDay().get()</code>56 * </ul>57 * The second technique also provides access to other useful methods on the58 * field:59 * <ul>60 * <li>numeric value61 * <li>text value62 * <li>short text value63 * <li>maximum/minimum values64 * <li>add/subtract65 * <li>set66 * <li>rounding67 * </ul>68 *69 * <p>70 * LocalDateTime is thread-safe and immutable, provided that the Chronology is as well.71 * All standard Chronology classes supplied are thread-safe and immutable.72 *73 * @author Stephen Colebourne74 * @since 1.375 */76 publicfinalclass LocalDateTime77 extendsAbstractPartial78 implementsReadablePartial, Serializable {79 80 /** Serialization lock */81 privatestaticfinallong serialVersionUID = -268716875315837168L;82 83 /** The index of the year field in the field array */84 privatestaticfinalint YEAR = 0;85 /** The index of the monthOfYear field in the field array */86 privatestaticfinalint MONTH_OF_YEAR = 1;87 /** The index of the dayOfMonth field in the field array */88 privatestaticfinalint DAY_OF_MONTH = 2;89 /** The index of the millis field in the field array */90 privatestaticfinalint MILLIS_OF_DAY = 3;91 92 /** The local millis from 1970-01-01T00:00:00 */93 privatelong iLocalMillis;94 /** The chronology to use in UTC */95 privateChronology iChronology;96 97 //-----------------------------------------------------------------------98 /**99 * Constructs a LocalDateTime from a <code>java.util.Calendar</code>100 * using exactly the same field values avoiding any time zone effects.101 * <p>102 * Each field is queried from the Calendar and assigned to the LocalDateTime.103 * This is useful if you have been using the Calendar as a local date,104 * ignoing the zone.105 * <p>106 * This factory method ignores the type of the calendar and always107 * creates a LocalDateTime with ISO chronology. It is expected that you108 * will only pass in instances of <code>GregorianCalendar</code> however109 * this is not validated.110 *111 * @param calendar the Calendar to extract fields from112 * @return the created LocalDateTime113 * @throws IllegalArgumentException if the calendar is null114 * @throws IllegalArgumentException if the date is invalid for the ISO chronology115 */116 publicstaticLocalDateTime fromCalendarFields(Calendar calendar) {117 if (calendar == null) {118 thrownewIllegalArgumentException("The calendar must not be null");119 }120 returnnewLocalDateTime(121 calendar.get(Calendar.YEAR),122 calendar.get(Calendar.MONTH) + 1,123 calendar.get(Calendar.DAY_OF_MONTH),124 calendar.get(Calendar.HOUR_OF_DAY),125 calendar.get(Calendar.MINUTE),126 calendar.get(Calendar.SECOND),127 calendar.get(Calendar.MILLISECOND)128 );129 }130 131 /**132 * Constructs a LocalDateTime from a <code>java.util.Date</code>133 * using exactly the same field values avoiding any time zone effects.134 * <p>135 * Each field is queried from the Date and assigned to the LocalDateTime.136 * This is useful if you have been using the Date as a local date,137 * ignoing the zone.138 * <p>139 * This factory method always creates a LocalDateTime with ISO chronology.140 *141 * @param date the Date to extract fields from142 * @return the created LocalDateTime143 * @throws IllegalArgumentException if the calendar is null144 * @throws IllegalArgumentException if the date is invalid for the ISO chronology145 */146 publicstaticLocalDateTime fromDateFields(Date date) {147 if (date == null) {148 thrownewIllegalArgumentException("The date must not be null");149 }150 returnnewLocalDateTime(151 date.getYear() + 1900,152 date.getMonth() + 1,153 date.getDate(),154 date.getHours(),155 date.getMinutes(),156 date.getSeconds(),157 (int) (date.getTime() % 1000)158 );159 }160 161 //-----------------------------------------------------------------------162 /**163 * Constructs an instance set to the current local time evaluated using164 * ISO chronology in the default zone.165 * <p>166 * Once the constructor is completed, the zone is no longer used.167 */168 public LocalDateTime() {169 this(DateTimeUtils.currentTimeMillis(), ISOChronology.getInstance());170 }171 172 /**173 * Constructs an instance set to the current local time evaluated using174 * ISO chronology in the specified zone.175 * <p>176 * If the specified time zone is null, the default zone is used.177 * Once the constructor is completed, the zone is no longer used.178 *179 * @param zone the time zone, null means default zone180 */181 public LocalDateTime(DateTimeZone zone) {182 this(DateTimeUtils.currentTimeMillis(), ISOChronology.getInstance(zone));183 }184 185 /**186 * Constructs an instance set to the current local time evaluated using187 * specified chronology.188 * <p>189 * If the chronology is null, ISO chronology in the default time zone is used.190 * Once the constructor is completed, the zone is no longer used.191 *192 * @param chronology the chronology, null means ISOChronology in default zone193 */194 public LocalDateTime(Chronology chronology) {195 this(DateTimeUtils.currentTimeMillis(), chronology);196 }197 198 //-----------------------------------------------------------------------199 /**200 * Constructs an instance set to the local time defined by the specified201 * instant evaluated using ISO chronology in the default zone.202 * <p>203 * Once the constructor is completed, the zone is no longer used.204 *205 * @param instant the milliseconds from 1970-01-01T00:00:00Z206 */207 public LocalDateTime(long instant) {208 this(instant, ISOChronology.getInstance());209 }210 211 /**212 * Constructs an instance set to the local time defined by the specified213 * instant evaluated using ISO chronology in the specified zone.214 * <p>215 * If the specified time zone is null, the default zone is used.216 * Once the constructor is completed, the zone is no longer used.217 *218 * @param instant the milliseconds from 1970-01-01T00:00:00Z219 * @param zone the time zone, null means default zone220 */221 public LocalDateTime(long instant, DateTimeZone zone) {222 this(instant, ISOChronology.getInstance(zone));223 }224 225 /**226 * Constructs an instance set to the local time defined by the specified227 * instant evaluated using the specified chronology.228 * <p>229 * If the chronology is null, ISO chronology in the default zone is used.230 * Once the constructor is completed, the zone is no longer used.231 *232 * @param instant the milliseconds from 1970-01-01T00:00:00Z233 * @param chronology the chronology, null means ISOChronology in default zone234 */235 public LocalDateTime(long instant, Chronology chronology) {236 chronology = DateTimeUtils.getChronology(chronology);237 238 long localMillis = chronology.getZone().getMillisKeepLocal(DateTimeZone.UTC, instant);239 iLocalMillis = localMillis;240 iChronology = chronology.withUTC();241 }242 243 //-----------------------------------------------------------------------244 /**245 * Constructs an instance from an Object that represents a datetime.246 * <p>247 * If the object contains no chronology, <code>ISOChronology</code> is used.248 * If the object contains no time zone, the default zone is used.249 * Once the constructor is completed, the zone is no longer used.250 * <p>251 * The recognised object types are defined in252 * {@link org.joda.time.convert.ConverterManager ConverterManager} and253 * include ReadablePartial, ReadableInstant, String, Calendar and Date.254 * The String formats are described by {@link ISODateTimeFormat#localDateOptionalTimeParser()}.255 * The default String converter ignores the zone and only parses the field values.256 *257 * @param instant the datetime object258 * @throws IllegalArgumentException if the instant is invalid259 */260 public LocalDateTime(Object instant) {261 this(instant, (Chronology) null);262 }263 264 /**265 * Constructs an instance from an Object that represents a datetime,266 * forcing the time zone to that specified.267 * <p>268 * If the object contains no chronology, <code>ISOChronology</code> is used.269 * If the specified time zone is null, the default zone is used.270 * Once the constructor is completed, the zone is no longer used.271 * <p>272 * The recognised object types are defined in273 * {@link org.joda.time.convert.ConverterManager ConverterManager} and274 * include ReadablePartial, ReadableInstant, String, Calendar and Date.275 * The String formats are described by {@link ISODateTimeFormat#localDateOptionalTimeParser()}.276 * The default String converter ignores the zone and only parses the field values.277 *278 * @param instant the datetime object279 * @param zone the time zone280 * @throws IllegalArgumentException if the instant is invalid281 */282 public LocalDateTime(Object instant, DateTimeZone zone) {283 PartialConverter converter = ConverterManager.getInstance().getPartialConverter(instant);284 Chronology chronology = converter.getChronology(instant, zone);285 chronology = DateTimeUtils.getChronology(chronology);286 iChronology = chronology.withUTC();287 int[] values = converter.getPartialValues(this, instant, chronology, ISODateTimeFormat.localDateOptionalTimeParser());288 iLocalMillis = iChronology.getDateTimeMillis(values[0], values[1], values[2], values[3]);289 }290 291 /**292 * Constructs an instance from an Object that represents a datetime,293 * using the specified chronology.294 * <p>295 * If the chronology is null, ISO in the default time zone is used.296 * Once the constructor is completed, the zone is no longer used.297 * <p>298 * The recognised object types are defined in299 * {@link org.joda.time.convert.ConverterManager ConverterManager} and300 * include ReadablePartial, ReadableInstant, String, Calendar and Date.301 * The String formats are described by {@link ISODateTimeFormat#localDateOptionalTimeParser()}.302 * The default String converter ignores the zone and only parses the field values.303 *304 * @param instant the datetime object305 * @param chronology the chronology306 * @throws IllegalArgumentException if the instant is invalid307 */308 public LocalDateTime(Object instant, Chronology chronology) {309 PartialConverter converter = ConverterManager.getInstance().getPartialConverter(instant);310 chronology = converter.getChronology(instant, chronology);311 chronology = DateTimeUtils.getChronology(chronology);312 iChronology = chronology.withUTC();313 int[] values = converter.getPartialValues(this, instant, chronology, ISODateTimeFormat.localDateOptionalTimeParser());314 iLocalMillis = iChronology.getDateTimeMillis(values[0], values[1], values[2], values[3]);315 }316 317 //-----------------------------------------------------------------------318 /**319 * Constructs an instance set to the specified date and time320 * using <code>ISOChronology</code>.321 *322 * @param year the year323 * @param monthOfYear the month of the year324 * @param dayOfMonth the day of the month325 * @param hourOfDay the hour of the day326 * @param minuteOfHour the minute of the hour327 */328 public LocalDateTime(329 int year,330 int monthOfYear,331 int dayOfMonth,332 int hourOfDay,333 int minuteOfHour) {334 this(year, monthOfYear, dayOfMonth, hourOfDay,335 minuteOfHour, 0, 0, ISOChronology.getInstanceUTC());336 }337 338 /**339 * Constructs an instance set to the specified date and time340 * using <code>ISOChronology</code>.341 *342 * @param year the year343 * @param monthOfYear the month of the year344 * @param dayOfMonth the day of the month345 * @param hourOfDay the hour of the day346 * @param minuteOfHour the minute of the hour347 * @param secondOfMinute the second of the minute348 */349 public LocalDateTime(350 int year,351 int monthOfYear,352 int dayOfMonth,353 int hourOfDay,354 int minuteOfHour,355 int secondOfMinute) {356 this(year, monthOfYear, dayOfMonth, hourOfDay,357 minuteOfHour, secondOfMinute, 0, ISOChronology.getInstanceUTC());358 }359 360 /**361 * Constructs an instance set to the specified date and time362 * using <code>ISOChronology</code>.363 *364 * @param year the year365 * @param monthOfYear the month of the year366 * @param dayOfMonth the day of the month367 * @param hourOfDay the hour of the day368 * @param minuteOfHour the minute of the hour369 * @param secondOfMinute the second of the minute370 * @param millisOfSecond the millisecond of the second371 */372 public LocalDateTime(373 int year,374 int monthOfYear,375 int dayOfMonth,376 int hourOfDay,377 int minuteOfHour,378 int secondOfMinute,379 int millisOfSecond) {380 this(year, monthOfYear, dayOfMonth, hourOfDay,381 minuteOfHour, secondOfMinute, millisOfSecond, ISOChronology.getInstanceUTC());382 }383 384 /**385 * Constructs an instance set to the specified date and time386 * using the specified chronology, whose zone is ignored.387 * <p>388 * If the chronology is null, <code>ISOChronology</code> is used.389 *390 * @param year the year391 * @param monthOfYear the month of the year392 * @param dayOfMonth the day of the month393 * @param hourOfDay the hour of the day394 * @param minuteOfHour the minute of the hour395 * @param secondOfMinute the second of the minute396 * @param millisOfSecond the millisecond of the second397 * @param chronology the chronology, null means ISOChronology in default zone398 */399 public LocalDateTime(400 int year,401 int monthOfYear,402 int dayOfMonth,403 int hourOfDay,404 int minuteOfHour,405 int secondOfMinute,406 int millisOfSecond,407 Chronology chronology) {408 super();409 chronology = DateTimeUtils.getChronology(chronology).withUTC();410 long instant = chronology.getDateTimeMillis(year, monthOfYear, dayOfMonth,411 hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond);412 iChronology = chronology;413 iLocalMillis = instant;414 }415 416 //-----------------------------------------------------------------------417 /**418 * Gets the number of fields in this partial, which is four.419 * The supported fields are Year, MonthOfDay, DayOfMonth and MillisOfDay.420 *421 * @return the field count, four422 */423 publicint size() {424 return4;425 }426 427 /**428 * Gets the field for a specific index in the chronology specified.429 * <p>430 * This method must not use any instance variables.431 *432 * @param index the index to retrieve433 * @param chrono the chronology to use434 * @return the field435 */436 protectedDateTimeField getField(int index, Chronology chrono) {437 switch (index) {438 case YEAR:439 return chrono.year();440 case MONTH_OF_YEAR:441 return chrono.monthOfYear();442 case DAY_OF_MONTH:443 return chrono.dayOfMonth();444 case MILLIS_OF_DAY:445 return chrono.millisOfDay();446 default:447 thrownewIndexOutOfBoundsException("Invalid index: " + index);448 }449 }450 451 /**452 * Gets the value of the field at the specifed index.453 * <p>454 * This method is required to support the <code>ReadablePartial</code>455 * interface. The supported fields are Year, MonthOfDay, DayOfMonth and MillisOfDay.456 *457 * @param index the index, zero to two458 * @return the value459 * @throws IndexOutOfBoundsException if the index is invalid460 */461 publicint getValue(int index) {462 switch (index) {463 case YEAR:464 return getChronology().year().get(getLocalMillis());465 case MONTH_OF_YEAR:466 return getChronology().monthOfYear().get(getLocalMillis());467 case DAY_OF_MONTH:468 return getChronology().dayOfMonth().get(getLocalMillis());469 case MILLIS_OF_DAY:470 return getChronology().millisOfDay().get(getLocalMillis());471 default:472 thrownewIndexOutOfBoundsException("Invalid index: " + index);473 }474 }475 476 //-----------------------------------------------------------------------477 /**478 * Get the value of one of the fields of a datetime.479 * <p>480 * This method gets the value of the specified field.481 * For example:482 * <pre>483 * DateTime dt = new DateTime();484 * int year = dt.get(DateTimeFieldType.year());485 * </pre>486 *487 * @param type a field type, usually obtained from DateTimeFieldType, not null488 * @return the value of that field489 * @throws IllegalArgumentException if the field type is null490 */491 publicint get(DateTimeFieldType type) {492 if (type == null) {493 thrownewIllegalArgumentException("The DateTimeFieldType must not be null");494 }495 return type.getField(getChronology()).get(getLocalMillis());496 }497 498 /**499 * Checks if the field type specified is supported by this500 * local datetime and chronology.501 * This can be used to avoid exceptions in {@link #get(DateTimeFieldType)}.502 *503 * @param type a field type, usually obtained from DateTimeFieldType504 * @return true if the field type is supported505 */506 publicboolean isSupported(DateTimeFieldType type) {507 if (type == null) {508 returnfalse;509 }510 return type.getField(getChronology()).isSupported();511 }512 513 /**514 * Checks if the duration type specified is supported by this515 * local datetime and chronology.516 *517 * @param type a duration type, usually obtained from DurationFieldType518 * @return true if the field type is supported519 */520 publicboolean isSupported(DurationFieldType type) {521 if (type == null) {522 returnfalse;523 }524 return type.getField(getChronology()).isSupported();525 }526 527 //-----------------------------------------------------------------------528 /**529 * Gets the milliseconds of the datetime instant from the Java epoch530 * of 1970-01-01T00:00:00 (not fixed to any specific time zone).531 *532 * @return the number of milliseconds since 1970-01-01T00:00:00533 */534 long getLocalMillis() {535 return iLocalMillis;536 }537 538 /**539 * Gets the chronology of the datetime.540 *541 * @return the Chronology that the datetime is using542 */543 publicChronology getChronology() {544 return iChronology;545 }546 547 //-----------------------------------------------------------------------548 /**549 * Converts this object to a DateTime using the default zone.550 * 551 * @return <code>this</code>552 */553 publicDateTime toDateTime() {554 return toDateTime((DateTimeZone) null);555 }556 557 /**558 * Converts this object to a DateTime using the specified zone.559 * 560 * @param zone time zone to apply, or default if null561 * @return a DateTime using the same millis562 */563 publicDateTime toDateTime(DateTimeZone zone) {564 zone = DateTimeUtils.getZone(zone);565 Chronology chrono = iChronology.withZone(zone);566 returnnewDateTime(567 getYear(), getMonthOfYear(), getDayOfMonth(),568 getHourOfDay(), getMinuteOfHour(),569 getSecondOfMinute(), getMillisOfSecond(), chrono);570 }571 572 //-----------------------------------------------------------------------573 /**574 * Converts this object to a LocalDate with the same date and chronology.575 *576 * @return a LocalDate with the same date and chronology577 */578 publicLocalDate toLocalDate() {579 returnnewLocalDate(getLocalMillis(), getChronology());580 }581 582 /**583 * Converts this object to a LocalTime with the same time and chronology.584 *585 * @return a LocalTime with the same time and chronology586 */587 publicLocalTime toLocalTime() {588 returnnewLocalTime(getLocalMillis(), getChronology());589 }590 591 //-----------------------------------------------------------------------592 /**593 * Returns a copy of this datetime with different local millis.594 * <p>595 * The returned object will be a new instance of the same type.596 * Only the millis will change, the chronology is kept.597 * The returned object will be either be a new instance or <code>this</code>.598 *599 * @param newMillis the new millis, from 1970-01-01T00:00:00600 * @return a copy of this datetime with different millis601 */602 LocalDateTime withLocalMillis(long newMillis) {603 return (newMillis == getLocalMillis() ? this : newLocalDateTime(newMillis, getChronology()));604 }605 606 //-----------------------------------------------------------------------607 /**608 * Returns a copy of this datetime with the specified date,609 * retaining the time fields.610 * <p>611 * If the date is already the date passed in, then <code>this</code> is returned.612 * <p>613 * To set a single field use the properties, for example:614 * <pre>615 * DateTime set = dt.monthOfYear().setCopy(6);616 * </pre>617 *618 * @param year the new year value619 * @param monthOfYear the new monthOfYear value620 * @param dayOfMonth the new dayOfMonth value621 * @return a copy of this datetime with a different date622 * @throws IllegalArgumentException if any value if invalid623 */624 publicLocalDateTime withDate(int year, int monthOfYear, int dayOfMonth) {625 Chronology chrono = getChronology();626 long instant = getLocalMillis();627 instant = chrono.year().set(instant, year);628 instant = chrono.monthOfYear().set(instant, monthOfYear);629 instant = chrono.dayOfMonth().set(instant, dayOfMonth);630 return withLocalMillis(instant);631 }632 633 /**634 * Returns a copy of this datetime with the specified time,635 * retaining the date fields.636 * <p>637 * If the time is already the time passed in, then <code>this</code> is returned.638 * <p>639 * To set a single field use the properties, for example:640 * <pre>641 * LocalDateTime set = dt.hourOfDay().setCopy(6);642 * </pre>643 *644 * @param hourOfDay the hour of the day645 * @param minuteOfHour the minute of the hour646 * @param secondOfMinute the second of the minute647 * @param millisOfSecond the millisecond of the second648 * @return a copy of this datetime with a different time649 * @throws IllegalArgumentException if any value if invalid650 */651 publicLocalDateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int millisOfSecond) {652 Chronology chrono = getChronology();653 long instant = getLocalMillis();654 instant = chrono.hourOfDay().set(instant, hourOfDay);655 instant = chrono.minuteOfHour().set(instant, minuteOfHour);656 instant = chrono.secondOfMinute().set(instant, secondOfMinute);657 instant = chrono.millisOfSecond().set(instant, millisOfSecond);658 return withLocalMillis(instant);659 }660 661 //-----------------------------------------------------------------------662 /**663 * Returns a copy of this datetime with the partial set of fields664 * replacing those from this instance.665 * <p>666 * For example, if the partial is a <code>TimeOfDay</code> then the time fields667 * would be changed in the returned instance.668 * If the partial is null, then <code>this</code> is returned.669 *670 * @param partial the partial set of fields to apply to this datetime, null ignored671 * @return a copy of this datetime with a different set of fields672 * @throws IllegalArgumentException if any value is invalid673 */674 publicLocalDateTime withFields(ReadablePartial partial) {675 if (partial == null) {676 returnthis;677 }678 return withLocalMillis(getChronology().set(partial, getLocalMillis()));679 }680 681 /**682 * Returns a copy of this datetime with the specified field set to a new value.683 * <p>684 * For example, if the field type is <code>hourOfDay</code> then the hour of day685 * field would be changed in the returned instance.686 * If the field type is null, then <code>this</code> is returned.687 * <p>688 * These three lines are equivalent:689 * <pre>690 * LocalDateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6);691 * LocalDateTime updated = dt.dayOfMonth().setCopy(6);692 * LocalDateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6);693 * </pre>694 *695 * @param fieldType the field type to set, not null696 * @param value the value to set697 * @return a copy of this datetime with the field set698 * @throws IllegalArgumentException if the value is null or invalid699 */700 publicLocalDateTime withField(DateTimeFieldType fieldType, int value) {701 if (fieldType == null) {702 thrownewIllegalArgumentException("Field must not be null");703 }704 long instant = fieldType.getField(getChronology()).set(getLocalMillis(), value);705 return withLocalMillis(instant);706 }707 708 /**709 * Returns a copy of this datetime with the value of the specified710 * field increased.711 * <p>712 * If the addition is zero or the field is null, then <code>this</code> is returned.713 * <p>714 * These three lines are equivalent:715 * <pre>716 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);717 * LocalDateTime added = dt.plusYears(6);718 * LocalDateTime added = dt.plus(Period.years(6));719 * </pre>720 *721 * @param fieldType the field type to add to, not null722 * @param amount the amount to add723 * @return a copy of this datetime with the field updated724 * @throws IllegalArgumentException if the value is null or invalid725 * @throws ArithmeticException if the result exceeds the internal capacity726 */727 publicLocalDateTime withFieldAdded(DurationFieldType fieldType, int amount) {728 if (fieldType == null) {729 thrownewIllegalArgumentException("Field must not be null");730 }731 if (amount == 0) {732 returnthis;733 }734 long instant = fieldType.getField(getChronology()).add(getLocalMillis(), amount);735 return withLocalMillis(instant);736 }737 738 //-----------------------------------------------------------------------739 /**740 * Returns a copy of this datetime with the specified duration added.741 * <p>742 * If the addition is zero, then <code>this</code> is returned.743 *744 * @param durationToAdd the duration to add to this one, null means zero745 * @param scalar the amount of times to add, such as -1 to subtract once746 * @return a copy of this datetime with the duration added747 * @throws ArithmeticException if the result exceeds the internal capacity748 */749 publicLocalDateTime withDurationAdded(ReadableDuration durationToAdd, int scalar) {750 if (durationToAdd == null || scalar == 0) {751 returnthis;752 }753 long instant = getChronology().add(getLocalMillis(), durationToAdd.getMillis(), scalar);754 return withLocalMillis(instant);755 }756 757 /**758 * Returns a copy of this datetime with the specified period added.759 * <p>760 * If the addition is zero, then <code>this</code> is returned.761 * <p>762 * This method is typically used to add multiple copies of complex763 * period instances. Adding one field is best achieved using methods764 * like {@link #withFieldAdded(DurationFieldType, int)}765 * or {@link #plusYears(int)}.766 *767 * @param period the period to add to this one, null means zero768 * @param scalar the amount of times to add, such as -1 to subtract once769 * @return a copy of this datetime with the period added770 * @throws ArithmeticException if the result exceeds the internal capacity771 */772 publicLocalDateTime withPeriodAdded(ReadablePeriod period, int scalar) {773 if (period == null || scalar == 0) {774 returnthis;775 }776 long instant = getChronology().add(period, getLocalMillis(), scalar);777 return withLocalMillis(instant);778 }779 780 //-----------------------------------------------------------------------781 /**782 * Returns a copy of this datetime with the specified duration added.783 * <p>784 * If the amount is zero or null, then <code>this</code> is returned.785 *786 * @param duration the duration to add to this one, null means zero787 * @return a copy of this datetime with the duration added788 * @throws ArithmeticException if the result exceeds the internal capacity789 */790 publicLocalDateTime plus(ReadableDuration duration) {791 return withDurationAdded(duration, 1);792 }793 794 /**795 * Returns a copy of this datetime with the specified period added.796 * <p>797 * If the amount is zero or null, then <code>this</code> is returned.798 * <p>799 * This method is typically used to add complex period instances.800 * Adding one field is best achieved using methods801 * like {@link #plusYears(int)}.802 *803 * @param period the period to add to this one, null means zero804 * @return a copy of this datetime with the period added805 * @throws ArithmeticException if the result exceeds the internal capacity806 */807 publicLocalDateTime plus(ReadablePeriod period) {808 return withPeriodAdded(period, 1);809 }810 811 //-----------------------------------------------------------------------812 /**813 * Returns a copy of this datetime plus the specified number of years.814 * <p>815 * This LocalDateTime instance is immutable and unaffected by this method call.816 * <p>817 * The following three lines are identical in effect:818 * <pre>819 * LocalDateTime added = dt.plusYears(6);820 * LocalDateTime added = dt.plus(Period.years(6));821 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);822 * </pre>823 *824 * @param years the amount of years to add, may be negative825 * @return the new LocalDateTime plus the increased years826 */827 publicLocalDateTime plusYears(int years) {828 if (years == 0) {829 returnthis;830 }831 long instant = getChronology().years().add(getLocalMillis(), years);832 return withLocalMillis(instant);833 }834 835 /**836 * Returns a copy of this datetime plus the specified number of months.837 * <p>838 * This LocalDateTime instance is immutable and unaffected by this method call.839 * <p>840 * The following three lines are identical in effect:841 * <pre>842 * LocalDateTime added = dt.plusMonths(6);843 * LocalDateTime added = dt.plus(Period.months(6));844 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.months(), 6);845 * </pre>846 *847 * @param months the amount of months to add, may be negative848 * @return the new LocalDateTime plus the increased months849 */850 publicLocalDateTime plusMonths(int months) {851 if (months == 0) {852 returnthis;853 }854 long instant = getChronology().months().add(getLocalMillis(), months);855 return withLocalMillis(instant);856 }857 858 /**859 * Returns a copy of this datetime plus the specified number of weeks.860 * <p>861 * This LocalDateTime instance is immutable and unaffected by this method call.862 * <p>863 * The following three lines are identical in effect:864 * <pre>865 * LocalDateTime added = dt.plusWeeks(6);866 * LocalDateTime added = dt.plus(Period.weeks(6));867 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.weeks(), 6);868 * </pre>869 *870 * @param weeks the amount of weeks to add, may be negative871 * @return the new LocalDateTime plus the increased weeks872 */873 publicLocalDateTime plusWeeks(int weeks) {874 if (weeks == 0) {875 returnthis;876 }877 long instant = getChronology().weeks().add(getLocalMillis(), weeks);878 return withLocalMillis(instant);879 }880 881 /**882 * Returns a copy of this datetime plus the specified number of days.883 * <p>884 * This LocalDateTime instance is immutable and unaffected by this method call.885 * <p>886 * The following three lines are identical in effect:887 * <pre>888 * LocalDateTime added = dt.plusDays(6);889 * LocalDateTime added = dt.plus(Period.days(6));890 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.days(), 6);891 * </pre>892 *893 * @param days the amount of days to add, may be negative894 * @return the new LocalDateTime plus the increased days895 */896 publicLocalDateTime plusDays(int days) {897 if (days == 0) {898 returnthis;899 }900 long instant = getChronology().days().add(getLocalMillis(), days);901 return withLocalMillis(instant);902 }903 904 //-----------------------------------------------------------------------905 /**906 * Returns a copy of this datetime plus the specified number of hours.907 * <p>908 * This LocalDateTime instance is immutable and unaffected by this method call.909 * <p>910 * The following three lines are identical in effect:911 * <pre>912 * LocalDateTime added = dt.plusHours(6);913 * LocalDateTime added = dt.plus(Period.hours(6));914 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.hours(), 6);915 * </pre>916 *917 * @param hours the amount of hours to add, may be negative918 * @return the new LocalDateTime plus the increased hours919 */920 publicLocalDateTime plusHours(int hours) {921 if (hours == 0) {922 returnthis;923 }924 long instant = getChronology().hours().add(getLocalMillis(), hours);925 return withLocalMillis(instant);926 }927 928 /**929 * Returns a copy of this datetime plus the specified number of minutes.930 * <p>931 * This LocalDateTime instance is immutable and unaffected by this method call.932 * <p>933 * The following three lines are identical in effect:934 * <pre>935 * LocalDateTime added = dt.plusMinutes(6);936 * LocalDateTime added = dt.plus(Period.minutes(6));937 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.minutes(), 6);938 * </pre>939 *940 * @param minutes the amount of minutes to add, may be negative941 * @return the new LocalDateTime plus the increased minutes942 */943 publicLocalDateTime plusMinutes(int minutes) {944 if (minutes == 0) {945 returnthis;946 }947 long instant = getChronology().minutes().add(getLocalMillis(), minutes);948 return withLocalMillis(instant);949 }950 951 /**952 * Returns a copy of this datetime plus the specified number of seconds.953 * <p>954 * This LocalDateTime instance is immutable and unaffected by this method call.955 * <p>956 * The following three lines are identical in effect:957 * <pre>958 * LocalDateTime added = dt.plusSeconds(6);959 * LocalDateTime added = dt.plus(Period.seconds(6));960 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.seconds(), 6);961 * </pre>962 *963 * @param seconds the amount of seconds to add, may be negative964 * @return the new LocalDateTime plus the increased seconds965 */966 publicLocalDateTime plusSeconds(int seconds) {967 if (seconds == 0) {968 returnthis;969 }970 long instant = getChronology().seconds().add(getLocalMillis(), seconds);971 return withLocalMillis(instant);972 }973 974 /**975 * Returns a copy of this datetime plus the specified number of millis.976 * <p>977 * This LocalDateTime instance is immutable and unaffected by this method call.978 * <p>979 * The following three lines are identical in effect:980 * <pre>981 * LocalDateTime added = dt.plusMillis(6);982 * LocalDateTime added = dt.plus(Period.millis(6));983 * LocalDateTime added = dt.withFieldAdded(DurationFieldType.millis(), 6);984 * </pre>985 *986 * @param millis the amount of millis to add, may be negative987 * @return the new LocalDateTime plus the increased millis988 */989 publicLocalDateTime plusMillis(int millis) {990 if (millis == 0) {991 returnthis;992 }993 long instant = getChronology().millis().add(getLocalMillis(), millis);994 return withLocalMillis(instant);995 }996 997 //-----------------------------------------------------------------------998 /**999 * Returns a copy of this datetime with the specified duration taken away.1000 * <p>1001 * If the amount is zero or null, then <code>this</code> is returned.1002 *1003 * @param duration the duration to reduce this instant by1004 * @return a copy of this datetime with the duration taken away1005 * @throws ArithmeticException if the result exceeds the internal capacity1006 */1007publicLocalDateTime minus(ReadableDuration duration) {1008return withDurationAdded(duration, -1);1009 }10101011/**1012 * Returns a copy of this datetime with the specified period taken away.1013 * <p>1014 * If the amount is zero or null, then <code>this</code> is returned.1015 * <p>1016 * This method is typically used to subtract complex period instances.1017 * Subtracting one field is best achieved using methods1018 * like {@link #minusYears(int)}.1019 *1020 * @param period the period to reduce this instant by1021 * @return a copy of this datetime with the period taken away1022 * @throws ArithmeticException if the result exceeds the internal capacity1023 */1024publicLocalDateTime minus(ReadablePeriod period) {1025return withPeriodAdded(period, -1);1026 }10271028//-----------------------------------------------------------------------1029/**1030 * Returns a copy of this datetime minus the specified number of years.1031 * <p>1032 * This LocalDateTime instance is immutable and unaffected by this method call.1033 * <p>1034 * The following three lines are identical in effect:1035 * <pre>1036 * LocalDateTime subtracted = dt.minusYears(6);1037 * LocalDateTime subtracted = dt.minus(Period.years(6));1038 * LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);1039 * </pre>1040 *1041 * @param years the amount of years to subtract, may be negative1042 * @return the new LocalDateTime minus the increased years1043 */1044publicLocalDateTime minusYears(int years) {1045if (years == 0) {1046returnthis;1047 }1048long instant = getChronology().years().subtract(getLocalMillis(), years);1049return withLocalMillis(instant);1050 }10511052/**1053 * Returns a copy of this datetime minus the specified number of months.1054 * <p>1055 * This LocalDateTime instance is immutable and unaffected by this method call.1056 * <p>1057 * The following three lines are identical in effect:1058 * <pre>1059 * LocalDateTime subtracted = dt.minusMonths(6);1060 * LocalDateTime subtracted = dt.minus(Period.months(6));1061 * LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);1062 * </pre>1063 *1064 * @param months the amount of months to subtract, may be negative1065 * @return the new LocalDateTime minus the increased months1066 */1067publicLocalDateTime minusMonths(int months) {1068if (months == 0) {1069returnthis;1070 }1071long instant = getChronology().months().subtract(getLocalMillis(), months);1072return withLocalMillis(instant);1073 }10741075/**1076 * Returns a copy of this datetime minus the specified number of weeks.1077 * <p>1078 * This LocalDateTime instance is immutable and unaffected by this method call.1079 * <p>1080 * The following three lines are identical in effect:1081 * <pre>1082 * LocalDateTime subtracted = dt.minusWeeks(6);1083 * LocalDateTime subtracted = dt.minus(Period.weeks(6));1084 * LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6);1085 * </pre>1086 *1087 * @param weeks the amount of weeks to subtract, may be negative1088 * @return the new LocalDateTime minus the increased weeks1089 */1090publicLocalDateTime minusWeeks(int weeks) {1091if (weeks == 0) {1092returnthis;1093 }1094long instant = getChronology().weeks().subtract(getLocalMillis(), weeks);1095return withLocalMillis(instant);1096 }10971098/**1099 * Returns a copy of this datetime minus the specified number of days.1100 * <p>1101 * This LocalDateTime instance is immutable and unaffected by this method call.1102 * <p>1103 * The following three lines are identical in effect:1104 * <pre>1105 * LocalDateTime subtracted = dt.minusDays(6);1106 * LocalDateTime subtracted = dt.minus(Period.days(6));1107 * LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);1108 * </pre>1109 *1110 * @param days the amount of days to subtract, may be negative1111 * @return the new LocalDateTime minus the increased days1112 */1113publicLocalDateTime minusDays(int days) {1114if (days == 0) {1115returnthis;1116 }1117long instant = getChronology().days().subtract(getLocalMillis(), days);1118return withLocalMillis(instant);1119 }11201121//-----------------------------------------------------------------------1122/**1123 * Returns a copy of this datetime minus the specified number of hours.1124 * <p>1125 * This LocalDateTime instance is immutable and unaffected by this method call.1126 * <p>1127 * The following three lines are identical in effect:1128 * <pre>1129 * LocalDateTime subtracted = dt.minusHours(6);1130 * LocalDateTime subtracted = dt.minus(Period.hours(6));1131 * LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6);1132 * </pre>1133 *1134 * @param hours the amount of hours to subtract, may be negative1135 * @return the new LocalDateTime minus the increased hours1136 */1137publicLocalDateTime minusHours(int hours) {1138if (hours == 0) {1139returnthis;1140 }1141long instant = getChronology().hours().subtract(getLocalMillis(), hours);1142return withLocalMillis(instant);1143 }11441145/**1146 * Returns a copy of this datetime minus the specified number of minutes.1147 * <p>1148 * This LocalDateTime instance is immutable and unaffected by this method call.1149 * <p>1150 * The following three lines are identical in effect:1151 * <pre>1152 * LocalDateTime subtracted = dt.minusMinutes(6);1153 * LocalDateTime subtracted = dt.minus(Period.minutes(6));1154 * LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.minutes(), -6);1155 * </pre>1156 *1157 * @param minutes the amount of minutes to subtract, may be negative1158 * @return the new LocalDateTime minus the increased minutes1159 */1160publicLocalDateTime minusMinutes(int minutes) {1161if (minutes == 0) {1162returnthis;1163 }1164long instant = getChronology().minutes().subtract(getLocalMillis(), minutes);1165return withLocalMillis(instant);1166 }11671168/**1169 * Returns a copy of this datetime minus the specified number of seconds.1170 * <p>1171 * This LocalDateTime instance is immutable and unaffected by this method call.1172 * <p>1173 * The following three lines are identical in effect:1174 * <pre>1175 * LocalDateTime subtracted = dt.minusSeconds(6);1176 * LocalDateTime subtracted = dt.minus(Period.seconds(6));1177 * LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6);1178 * </pre>1179 *1180 * @param seconds the amount of seconds to subtract, may be negative1181 * @return the new LocalDateTime minus the increased seconds1182 */1183publicLocalDateTime minusSeconds(int seconds) {1184if (seconds == 0) {1185returnthis;1186 }1187long instant = getChronology().seconds().subtract(getLocalMillis(), seconds);1188return withLocalMillis(instant);1189 }11901191/**1192 * Returns a copy of this datetime minus the specified number of millis.1193 * <p>1194 * This LocalDateTime instance is immutable and unaffected by this method call.1195 * <p>1196 * The following three lines are identical in effect:1197 * <pre>1198 * LocalDateTime subtracted = dt.minusMillis(6);1199 * LocalDateTime subtracted = dt.minus(Period.millis(6));1200 * LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6);1201 * </pre>1202 *1203 * @param millis the amount of millis to subtract, may be negative1204 * @return the new LocalDateTime minus the increased millis1205 */1206publicLocalDateTime minusMillis(int millis) {1207if (millis == 0) {1208returnthis;1209 }1210long instant = getChronology().millis().subtract(getLocalMillis(), millis);1211return withLocalMillis(instant);1212 }12131214//-----------------------------------------------------------------------1215/**1216 * Gets the property object for the specified type, which contains many1217 * useful methods.1218 *1219 * @param fieldType the field type to get the chronology for1220 * @return the property object1221 * @throws IllegalArgumentException if the field is null or unsupported1222 */1223publicProperty property(DateTimeFieldType fieldType) {1224if (fieldType == null) {1225thrownewIllegalArgumentException("The DateTimeFieldType must not be null");1226 }1227if (isSupported(fieldType) == false) {1228thrownewIllegalArgumentException("Field '" + fieldType + "' is not supported");1229 }1230returnnewProperty(this, fieldType.getField(getChronology()));1231 }12321233//-----------------------------------------------------------------------1234/**1235 * Get the era field value.1236 *1237 * @return the era1238 */1239publicint getEra() {1240return getChronology().era().get(getLocalMillis());1241 }12421243/**1244 * Get the year of era field value.1245 *1246 * @return the year of era1247 */1248publicint getCenturyOfEra() {1249return getChronology().centuryOfEra().get(getLocalMillis());1250 }12511252/**1253 * Get the year of era field value.1254 *1255 * @return the year of era1256 */1257publicint getYearOfEra() {1258return getChronology().yearOfEra().get(getLocalMillis());1259 }12601261/**1262 * Get the year of century field value.1263 *1264 * @return the year of century1265 */1266publicint getYearOfCentury() {1267return getChronology().yearOfCentury().get(getLocalMillis());1268 }12691270/**1271 * Get the year field value.1272 *1273 * @return the year1274 */1275publicint getYear() {1276return getChronology().year().get(getLocalMillis());1277 }12781279/**1280 * Get the weekyear field value.1281 * <p>1282 * The weekyear is the year that matches with the weekOfWeekyear field.1283 * In the standard ISO8601 week algorithm, the first week of the year1284 * is that in which at least 4 days are in the year. As a result of this1285 * definition, day 1 of the first week may be in the previous year.1286 * The weekyear allows you to query the effective year for that day.1287 *1288 * @return the weekyear1289 */1290publicint getWeekyear() {1291return getChronology().weekyear().get(getLocalMillis());1292 }12931294/**1295 * Get the month of year field value.1296 *1297 * @return the month of year1298 */1299publicint getMonthOfYear() {1300return getChronology().monthOfYear().get(getLocalMillis());1301 }13021303/**1304 * Get the week of weekyear field value.1305 *1306 * @return the week of a week based year1307 */1308publicint getWeekOfWeekyear() {1309return getChronology().weekOfWeekyear().get(getLocalMillis());1310 }13111312/**1313 * Get the day of year field value.1314 *1315 * @return the day of year1316 */1317publicint getDayOfYear() {1318return getChronology().dayOfYear().get(getLocalMillis());1319 }13201321/**1322 * Get the day of month field value.1323 * <p>1324 * The values for the day of month are defined in {@link org.joda.time.DateTimeConstants}.1325 *1326 * @return the day of month1327 */1328publicint getDayOfMonth() {1329return getChronology().dayOfMonth().get(getLocalMillis());1330 }13311332/**1333 * Get the day of week field value.1334 * <p>1335 * The values for the day of week are defined in {@link org.joda.time.DateTimeConstants}.1336 *1337 * @return the day of week1338 */1339publicint getDayOfWeek() {1340return getChronology().dayOfWeek().get(getLocalMillis());1341 }13421343//-----------------------------------------------------------------------1344/**1345 * Get the hour of day field value.1346 *1347 * @return the hour of day1348 */1349publicint getHourOfDay() {1350return getChronology().hourOfDay().get(getLocalMillis());1351 }13521353/**1354 * Get the minute of hour field value.1355 *1356 * @return the minute of hour1357 */1358publicint getMinuteOfHour() {1359return getChronology().minuteOfHour().get(getLocalMillis());1360 }13611362/**1363 * Get the second of minute field value.1364 *1365 * @return the second of minute1366 */1367publicint getSecondOfMinute() {1368return getChronology().secondOfMinute().get(getLocalMillis());1369 }13701371/**1372 * Get the millis of second field value.1373 *1374 * @return the millis of second1375 */1376publicint getMillisOfSecond() {1377return getChronology().millisOfSecond().get(getLocalMillis());1378 }13791380/**1381 * Get the millis of day field value.1382 *1383 * @return the millis of day1384 */1385publicint getMillisOfDay() {1386return getChronology().millisOfDay().get(getLocalMillis());1387 }13881389//-----------------------------------------------------------------------1390/**1391 * Returns a copy of this datetime with the era field updated.1392 * <p>1393 * LocalDateTime is immutable, so there are no set methods.1394 * Instead, this method returns a new instance with the value of1395 * era changed.1396 *1397 * @param era the era to set1398 * @return a copy of this object with the field set1399 * @throws IllegalArgumentException if the value is invalid1400 */1401publicLocalDateTime withEra(int era) {1402return withLocalMillis(getChronology().era().set(getLocalMillis(), era));1403 }14041405/**1406 * Returns a copy of this datetime with the century of era field updated.1407 * <p>1408 * LocalDateTime is immutable, so there are no set methods.1409 * Instead, this method returns a new instance with the value of1410 * century of era changed.1411 *1412 * @param centuryOfEra the centurey of era to set1413 * @return a copy of this object with the field set1414 * @throws IllegalArgumentException if the value is invalid1415 */1416publicLocalDateTime withCenturyOfEra(int centuryOfEra) {1417return withLocalMillis(getChronology().centuryOfEra().set(getLocalMillis(), centuryOfEra));1418 }14191420/**1421 * Returns a copy of this datetime with the year of era field updated.1422 * <p>1423 * LocalDateTime is immutable, so there are no set methods.1424 * Instead, this method returns a new instance with the value of1425 * year of era changed.1426 *1427 * @param yearOfEra the year of era to set1428 * @return a copy of this object with the field set1429 * @throws IllegalArgumentException if the value is invalid1430 */1431publicLocalDateTime withYearOfEra(int yearOfEra) {1432return withLocalMillis(getChronology().yearOfEra().set(getLocalMillis(), yearOfEra));1433 }14341435/**1436 * Returns a copy of this datetime with the year of century field updated.1437 * <p>1438 * LocalDateTime is immutable, so there are no set methods.1439 * Instead, this method returns a new instance with the value of1440 * year of century changed.1441 *1442 * @param yearOfCentury the year of century to set1443 * @return a copy of this object with the field set1444 * @throws IllegalArgumentException if the value is invalid1445 */1446publicLocalDateTime withYearOfCentury(int yearOfCentury) {1447return withLocalMillis(getChronology().yearOfCentury().set(getLocalMillis(), yearOfCentury));1448 }14491450/**1451 * Returns a copy of this datetime with the year field updated.1452 * <p>1453 * LocalDateTime is immutable, so there are no set methods.1454 * Instead, this method returns a new instance with the value of1455 * year changed.1456 *1457 * @param year the year to set1458 * @return a copy of this object with the field set1459 * @throws IllegalArgumentException if the value is invalid1460 */1461publicLocalDateTime withYear(int year) {1462return withLocalMillis(getChronology().year().set(getLocalMillis(), year));1463 }14641465/**1466 * Returns a copy of this datetime with the weekyear field updated.1467 * <p>1468 * LocalDateTime is immutable, so there are no set methods.1469 * Instead, this method returns a new instance with the value of1470 * weekyear changed.1471 *1472 * @param weekyear the weekyear to set1473 * @return a copy of this object with the field set1474 * @throws IllegalArgumentException if the value is invalid1475 */1476publicLocalDateTime withWeekyear(int weekyear) {1477return withLocalMillis(getChronology().weekyear().set(getLocalMillis(), weekyear));1478 }14791480/**1481 * Returns a copy of this datetime with the month of year field updated.1482 * <p>1483 * LocalDateTime is immutable, so there are no set methods.1484 * Instead, this method returns a new instance with the value of1485 * month of year changed.1486 *1487 * @param monthOfYear the month of year to set1488 * @return a copy of this object with the field set1489 * @throws IllegalArgumentException if the value is invalid1490 */1491publicLocalDateTime withMonthOfYear(int monthOfYear) {1492return withLocalMillis(getChronology().monthOfYear().set(getLocalMillis(), monthOfYear));1493 }14941495/**1496 * Returns a copy of this datetime with the week of weekyear field updated.1497 * <p>1498 * LocalDateTime is immutable, so there are no set methods.1499 * Instead, this method returns a new instance with the value of1500 * week of weekyear changed.1501 *1502 * @param weekOfWeekyear the week of weekyear to set1503 * @return a copy of this object with the field set1504 * @throws IllegalArgumentException if the value is invalid1505 */1506publicLocalDateTime withWeekOfWeekyear(int weekOfWeekyear) {1507return withLocalMillis(getChronology().weekOfWeekyear().set(getLocalMillis(), weekOfWeekyear));1508 }15091510/**1511 * Returns a copy of this datetime with the day of year field updated.1512 * <p>1513 * LocalDateTime is immutable, so there are no set methods.1514 * Instead, this method returns a new instance with the value of1515 * day of year changed.1516 *1517 * @param dayOfYear the day of year to set1518 * @return a copy of this object with the field set1519 * @throws IllegalArgumentException if the value is invalid1520 */1521publicLocalDateTime withDayOfYear(int dayOfYear) {1522return withLocalMillis(getChronology().dayOfYear().set(getLocalMillis(), dayOfYear));1523 }15241525/**1526 * Returns a copy of this datetime with the day of month field updated.1527 * <p>1528 * LocalDateTime is immutable, so there are no set methods.1529 * Instead, this method returns a new instance with the value of1530 * day of month changed.1531 *1532 * @param dayOfMonth the day of month to set1533 * @return a copy of this object with the field set1534 * @throws IllegalArgumentException if the value is invalid1535 */1536publicLocalDateTime withDayOfMonth(int dayOfMonth) {1537return withLocalMillis(getChronology().dayOfMonth().set(getLocalMillis(), dayOfMonth));1538 }15391540/**1541 * Returns a copy of this datetime with the day of week field updated.1542 * <p>1543 * LocalDateTime is immutable, so there are no set methods.1544 * Instead, this method returns a new instance with the value of1545 * day of week changed.1546 *1547 * @param dayOfWeek the day of week to set1548 * @return a copy of this object with the field set1549 * @throws IllegalArgumentException if the value is invalid1550 */1551publicLocalDateTime withDayOfWeek(int dayOfWeek) {1552return withLocalMillis(getChronology().dayOfWeek().set(getLocalMillis(), dayOfWeek));1553 }15541555//-----------------------------------------------------------------------1556/**1557 * Returns a copy of this datetime with the hour of day field updated.1558 * <p>1559 * LocalDateTime is immutable, so there are no set methods.1560 * Instead, this method returns a new instance with the value of1561 * hour of day changed.1562 *1563 * @param hour the hour of day to set1564 * @return a copy of this object with the field set1565 * @throws IllegalArgumentException if the value is invalid1566 */1567publicLocalDateTime withHourOfDay(int hour) {1568return withLocalMillis(getChronology().hourOfDay().set(getLocalMillis(), hour));1569 }15701571/**1572 * Returns a copy of this datetime with the minute of hour field updated.1573 * <p>1574 * LocalDateTime is immutable, so there are no set methods.1575 * Instead, this method returns a new instance with the value of1576 * minute of hour changed.1577 *1578 * @param minute the minute of hour to set1579 * @return a copy of this object with the field set1580 * @throws IllegalArgumentException if the value is invalid1581 */1582publicLocalDateTime withMinuteOfHour(int minute) {1583return withLocalMillis(getChronology().minuteOfHour().set(getLocalMillis(), minute));1584 }15851586/**1587 * Returns a copy of this datetime with the second of minute field updated.1588 * <p>1589 * LocalDateTime is immutable, so there are no set methods.1590 * Instead, this method returns a new instance with the value of1591 * second of minute changed.1592 *1593 * @param second the second of minute to set1594 * @return a copy of this object with the field set1595 * @throws IllegalArgumentException if the value is invalid1596 */1597publicLocalDateTime withSecondOfMinute(int second) {1598return withLocalMillis(getChronology().secondOfMinute().set(getLocalMillis(), second));1599 }16001601/**1602 * Returns a copy of this datetime with the millis of second field updated.1603 * <p>1604 * LocalDateTime is immutable, so there are no set methods.1605 * Instead, this method returns a new instance with the value of1606 * millis of second changed.1607 *1608 * @param millis the millis of second to set1609 * @return a copy of this object with the field set1610 * @throws IllegalArgumentException if the value is invalid1611 */1612publicLocalDateTime withMillisOfSecond(int millis) {1613return withLocalMillis(getChronology().millisOfSecond().set(getLocalMillis(), millis));1614 }16151616/**1617 * Returns a copy of this datetime with the millis of day field updated.1618 * <p>1619 * LocalDateTime is immutable, so there are no set methods.1620 * Instead, this method returns a new instance with the value of1621 * millis of day changed.1622 *1623 * @param millis the millis of day to set1624 * @return a copy of this object with the field set1625 * @throws IllegalArgumentException if the value is invalid1626 */1627publicLocalDateTime withMillisOfDay(int millis) {1628return withLocalMillis(getChronology().millisOfDay().set(getLocalMillis(), millis));1629 }16301631//-----------------------------------------------------------------------1632/**1633 * Get the era property which provides access to advanced functionality.1634 *1635 * @return the era property1636 */1637publicProperty era() {1638returnnewProperty(this, getChronology().era());1639 }16401641/**1642 * Get the century of era property which provides access to advanced functionality.1643 *1644 * @return the year of era property1645 */1646publicProperty centuryOfEra() {1647returnnewProperty(this, getChronology().centuryOfEra());1648 }16491650/**1651 * Get the year of century property which provides access to advanced functionality.1652 *1653 * @return the year of era property1654 */1655publicProperty yearOfCentury() {1656returnnewProperty(this, getChronology().yearOfCentury());1657 }16581659/**1660 * Get the year of era property which provides access to advanced functionality.1661 *1662 * @return the year of era property1663 */1664publicProperty yearOfEra() {1665returnnewProperty(this, getChronology().yearOfEra());1666 }16671668/**1669 * Get the year property which provides access to advanced functionality.1670 *1671 * @return the year property1672 */1673publicProperty year() {1674returnnewProperty(this, getChronology().year());1675 }16761677/**1678 * Get the weekyear property which provides access to advanced functionality.1679 *1680 * @return the weekyear property1681 */1682publicProperty weekyear() {1683returnnewProperty(this, getChronology().weekyear());1684 }16851686/**1687 * Get the month of year property which provides access to advanced functionality.1688 *1689 * @return the month of year property1690 */1691publicProperty monthOfYear() {1692returnnewProperty(this, getChronology().monthOfYear());1693 }16941695/**1696 * Get the week of a week based year property which provides access to advanced functionality.1697 *1698 * @return the week of a week based year property1699 */1700publicProperty weekOfWeekyear() {1701returnnewProperty(this, getChronology().weekOfWeekyear());1702 }17031704/**1705 * Get the day of year property which provides access to advanced functionality.1706 *1707 * @return the day of year property1708 */1709publicProperty dayOfYear() {1710returnnewProperty(this, getChronology().dayOfYear());1711 }17121713/**1714 * Get the day of month property which provides access to advanced functionality.1715 *1716 * @return the day of month property1717 */1718publicProperty dayOfMonth() {1719returnnewProperty(this, getChronology().dayOfMonth());1720 }17211722/**1723 * Get the day of week property which provides access to advanced functionality.1724 *1725 * @return the day of week property1726 */1727publicProperty dayOfWeek() {1728returnnewProperty(this, getChronology().dayOfWeek());1729 }17301731//-----------------------------------------------------------------------1732/**1733 * Get the hour of day field property which provides access to advanced functionality.1734 * 1735 * @return the hour of day property1736 */1737publicProperty hourOfDay() {1738returnnewProperty(this, getChronology().hourOfDay());1739 }17401741/**1742 * Get the minute of hour field property which provides access to advanced functionality.1743 * 1744 * @return the minute of hour property1745 */1746publicProperty minuteOfHour() {1747returnnewProperty(this, getChronology().minuteOfHour());1748 }17491750/**1751 * Get the second of minute field property which provides access to advanced functionality.1752 * 1753 * @return the second of minute property1754 */1755publicProperty secondOfMinute() {1756returnnewProperty(this, getChronology().secondOfMinute());1757 }17581759/**1760 * Get the millis of second property which provides access to advanced functionality.1761 * 1762 * @return the millis of second property1763 */1764publicProperty millisOfSecond() {1765returnnewProperty(this, getChronology().millisOfSecond());1766 }17671768/**1769 * Get the millis of day property which provides access to advanced functionality.1770 * 1771 * @return the millis of day property1772 */1773publicProperty millisOfDay() {1774returnnewProperty(this, getChronology().millisOfDay());1775 }17761777//-----------------------------------------------------------------------1778/**1779 * Output the date time in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSS).1780 * 1781 * @return ISO8601 time formatted string.1782 */1783publicString toString() {1784return ISODateTimeFormat.dateTime().print(this);1785 }17861787/**1788 * Output the date using the specified format pattern.1789 *1790 * @param pattern the pattern specification, null means use <code>toString</code>1791 * @see org.joda.time.format.DateTimeFormat1792 */1793publicString toString(String pattern) {1794if (pattern == null) {1795return toString();1796 }1797return DateTimeFormat.forPattern(pattern).print(this);1798 }17991800/**1801 * Output the date using the specified format pattern.1802 *1803 * @param pattern the pattern specification, null means use <code>toString</code>1804 * @param locale Locale to use, null means default1805 * @see org.joda.time.format.DateTimeFormat1806 */1807publicString toString(String pattern, Locale locale) throwsIllegalArgumentException {1808if (pattern == null) {1809return toString();1810 }1811return DateTimeFormat.forPattern(pattern).withLocale(locale).print(this);1812 }18131814//-----------------------------------------------------------------------1815/**1816 * LocalDateTime.Property binds a LocalDateTime to a DateTimeField allowing1817 * powerful datetime functionality to be easily accessed.1818 * <p>1819 * The simplest use of this class is as an alternative get method, here used to1820 * get the year '1972' (as an int) and the month 'December' (as a String).1821 * <pre>1822 * LocalDateTime dt = new LocalDateTime(1972, 12, 3, 0, 0);1823 * int year = dt.year().get();1824 * String monthStr = dt.month().getAsText();1825 * </pre>1826 * <p>1827 * Methods are also provided that allow date modification. These return1828 * new instances of LocalDateTime - they do not modify the original.1829 * The example below yields two independent immutable date objects1830 * 20 years apart.1831 * <pre>1832 * LocalDateTime dt = new LocalDateTime(1972, 12, 3, 0, 0);1833 * LocalDateTime dt1920 = dt.year().setCopy(1920);1834 * </pre>1835 * <p>1836 * LocalDateTime.Property itself is thread-safe and immutable, as well as the1837 * LocalDateTime being operated on.1838 *1839 * @author Stephen Colebourne1840 * @author Brian S O'Neill1841 * @since 1.31842 */1843publicstaticfinalclass Property extendsAbstractReadableInstantFieldProperty {18441845/** Serialization version */1846privatestaticfinallong serialVersionUID = -358138762846288L;18471848/** The instant this property is working against */1849privatetransientLocalDateTime iInstant;1850/** The field this property is working against */1851privatetransientDateTimeField iField;18521853/**1854 * Constructor.1855 * 1856 * @param instant the instant to set1857 * @param field the field to use1858 */1859 Property(LocalDateTime instant, DateTimeField field) {1860super();1861 iInstant = instant;1862 iField = field;1863 }18641865/**1866 * Writes the property in a safe serialization format.1867 */1868privatevoid writeObject(ObjectOutputStream oos) throwsIOException {1869 oos.writeObject(iInstant);1870 oos.writeObject(iField.getType());1871 }18721873/**1874 * Reads the property from a safe serialization format.1875 */1876privatevoid readObject(ObjectInputStream oos) throwsIOException, ClassNotFoundException {1877 iInstant = (LocalDateTime) oos.readObject();1878DateTimeFieldType type = (DateTimeFieldType) oos.readObject();1879 iField = type.getField(iInstant.getChronology());1880 }18811882//-----------------------------------------------------------------------1883/**1884 * Gets the field being used.1885 * 1886 * @return the field1887 */1888publicDateTimeField getField() {1889return iField;1890 }18911892/**1893 * Gets the milliseconds of the datetime that this property is linked to.1894 * 1895 * @return the milliseconds1896 */1897protectedlong getMillis() {1898return iInstant.getLocalMillis();1899 }19001901/**1902 * Gets the chronology of the datetime that this property is linked to.1903 * 1904 * @return the chronology1905 * @since 1.41906 */1907protectedChronology getChronology() {1908return iInstant.getChronology();1909 }19101911/**1912 * Gets the LocalDateTime object linked to this property.1913 * 1914 * @return the linked LocalDateTime1915 */1916publicLocalDateTime getLocalDateTime() {1917return iInstant;1918 }19191920//-----------------------------------------------------------------------1921/**1922 * Adds to this field in a copy of this LocalDateTime.1923 * <p>1924 * The LocalDateTime attached to this property is unchanged by this call.1925 *1926 * @param value the value to add to the field in the copy1927 * @return a copy of the LocalDateTime with the field value changed1928 * @throws IllegalArgumentException if the value isn't valid1929 */1930publicLocalDateTime addToCopy(int value) {1931return iInstant.withLocalMillis(iField.add(iInstant.getLocalMillis(), value));1932 }19331934/**1935 * Adds to this field in a copy of this LocalDateTime.1936 * <p>1937 * The LocalDateTime attached to this property is unchanged by this call.1938 *1939 * @param value the value to add to the field in the copy1940 * @return a copy of the LocalDateTime with the field value changed1941 * @throws IllegalArgumentException if the value isn't valid1942 */1943publicLocalDateTime addToCopy(long value) {1944return iInstant.withLocalMillis(iField.add(iInstant.getLocalMillis(), value));1945 }19461947/**1948 * Adds to this field, possibly wrapped, in a copy of this LocalDateTime.1949 * A field wrapped operation only changes this field.1950 * Thus 31st January addWrapField one day goes to the 1st January.1951 * <p>1952 * The LocalDateTime attached to this property is unchanged by this call.1953 *1954 * @param value the value to add to the field in the copy1955 * @return a copy of the LocalDateTime with the field value changed1956 * @throws IllegalArgumentException if the value isn't valid1957 */1958publicLocalDateTime addWrapFieldToCopy(int value) {1959return iInstant.withLocalMillis(iField.addWrapField(iInstant.getLocalMillis(), value));1960 }19611962//-----------------------------------------------------------------------1963/**1964 * Sets this field in a copy of the LocalDateTime.1965 * <p>1966 * The LocalDateTime attached to this property is unchanged by this call.1967 *1968 * @param value the value to set the field in the copy to1969 * @return a copy of the LocalDateTime with the field value changed1970 * @throws IllegalArgumentException if the value isn't valid1971 */1972publicLocalDateTime setCopy(int value) {1973return iInstant.withLocalMillis(iField.set(iInstant.getLocalMillis(), value));1974 }19751976/**1977 * Sets this field in a copy of the LocalDateTime to a parsed text value.1978 * <p>1979 * The LocalDateTime attached to this property is unchanged by this call.1980 *1981 * @param text the text value to set1982 * @param locale optional locale to use for selecting a text symbol1983 * @return a copy of the LocalDateTime with the field value changed1984 * @throws IllegalArgumentException if the text value isn't valid1985 */1986publicLocalDateTime setCopy(String text, Locale locale) {1987return iInstant.withLocalMillis(iField.set(iInstant.getLocalMillis(), text, locale));1988 }19891990/**1991 * Sets this field in a copy of the LocalDateTime to a parsed text value.1992 * <p>1993 * The LocalDateTime attached to this property is unchanged by this call.1994 *1995 * @param text the text value to set1996 * @return a copy of the LocalDateTime with the field value changed1997 * @throws IllegalArgumentException if the text value isn't valid1998 */1999publicLocalDateTime setCopy(String text) {2000return setCopy(text, null);2001 }20022003//-----------------------------------------------------------------------2004/**2005 * Returns a new LocalDateTime with this field set to the maximum value2006 * for this field.2007 * <p>2008 * This operation is useful for obtaining a LocalDateTime on the last day2009 * of the month, as month lengths vary.2010 * <pre>2011 * LocalDateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();2012 * </pre>2013 * <p>2014 * The LocalDateTime attached to this property is unchanged by this call.2015 *2016 * @return a copy of the LocalDateTime with this field set to its maximum2017 */2018publicLocalDateTime withMaximumValue() {2019return setCopy(getMaximumValue());2020 }20212022/**2023 * Returns a new LocalDateTime with this field set to the minimum value2024 * for this field.2025 * <p>2026 * The LocalDateTime attached to this property is unchanged by this call.2027 *2028 * @return a copy of the LocalDateTime with this field set to its minimum2029 */2030publicLocalDateTime withMinimumValue() {2031return setCopy(getMinimumValue());2032 }20332034//-----------------------------------------------------------------------2035/**2036 * Rounds to the lowest whole unit of this field on a copy of this2037 * LocalDateTime.2038 * <p>2039 * For example, rounding floor on the hourOfDay field of a LocalDateTime2040 * where the time is 10:30 would result in new LocalDateTime with the2041 * time of 10:00.2042 *2043 * @return a copy of the LocalDateTime with the field value changed2044 */2045publicLocalDateTime roundFloorCopy() {2046return iInstant.withLocalMillis(iField.roundFloor(iInstant.getLocalMillis()));2047 }20482049/**2050 * Rounds to the highest whole unit of this field on a copy of this2051 * LocalDateTime.2052 * <p>2053 * For example, rounding floor on the hourOfDay field of a LocalDateTime2054 * where the time is 10:30 would result in new LocalDateTime with the2055 * time of 11:00.2056 *2057 * @return a copy of the LocalDateTime with the field value changed2058 */2059publicLocalDateTime roundCeilingCopy() {2060return iInstant.withLocalMillis(iField.roundCeiling(iInstant.getLocalMillis()));2061 }20622063/**2064 * Rounds to the nearest whole unit of this field on a copy of this2065 * LocalDateTime, favoring the floor if halfway.2066 *2067 * @return a copy of the LocalDateTime with the field value changed2068 */2069publicLocalDateTime roundHalfFloorCopy() {2070return iInstant.withLocalMillis(iField.roundHalfFloor(iInstant.getLocalMillis()));2071 }20722073/**2074 * Rounds to the nearest whole unit of this field on a copy of this2075 * LocalDateTime, favoring the ceiling if halfway.2076 *2077 * @return a copy of the LocalDateTime with the field value changed2078 */2079publicLocalDateTime roundHalfCeilingCopy() {2080return iInstant.withLocalMillis(iField.roundHalfCeiling(iInstant.getLocalMillis()));2081 }20822083/**2084 * Rounds to the nearest whole unit of this field on a copy of this2085 * LocalDateTime. If halfway, the ceiling is favored over the floor2086 * only if it makes this field's value even.2087 *2088 * @return a copy of the LocalDateTime with the field value changed2089 */2090publicLocalDateTime roundHalfEvenCopy() {2091return iInstant.withLocalMillis(iField.roundHalfEven(iInstant.getLocalMillis()));2092 }2093 }20942095}2096