001/* 002 * Copyright 2001-2006 Stephen Colebourne 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package org.joda.time; 017 018import java.io.IOException; 019import java.io.ObjectInputStream; 020import java.io.ObjectOutputStream; 021import java.io.Serializable; 022import java.util.Locale; 023 024import org.joda.time.base.BaseDateTime; 025import org.joda.time.chrono.ISOChronology; 026import org.joda.time.field.AbstractReadableInstantFieldProperty; 027import org.joda.time.format.ISODateTimeFormat; 028 029/** 030 * DateTime is the standard implementation of an unmodifiable datetime class. 031 * <p> 032 * <code>DateTime</code> is the most widely used implementation of 033 * {@link ReadableInstant}. As with all instants, it represents an exact 034 * point on the time-line, but limited to the precision of milliseconds. 035 * A <code>DateTime</code> calculates its fields with respect to a 036 * {@link DateTimeZone time zone}. 037 * <p> 038 * Internally, the class holds two pieces of data. Firstly, it holds the 039 * datetime as milliseconds from the Java epoch of 1970-01-01T00:00:00Z. 040 * Secondly, it holds a {@link Chronology} which determines how the 041 * millisecond instant value is converted into the date time fields. 042 * The default Chronology is {@link ISOChronology} which is the agreed 043 * international standard and compatible with the modern Gregorian calendar. 044 * <p> 045 * Each individual field can be queried in two ways: 046 * <ul> 047 * <li><code>getHourOfDay()</code> 048 * <li><code>hourOfDay().get()</code> 049 * </ul> 050 * The second technique also provides access to other useful methods on the 051 * field: 052 * <ul> 053 * <li>numeric value 054 * <li>text value 055 * <li>short text value 056 * <li>maximum/minimum values 057 * <li>add/subtract 058 * <li>set 059 * <li>rounding 060 * </ul> 061 * <p> 062 * DateTime is thread-safe and immutable, provided that the Chronology is as well. 063 * All standard Chronology classes supplied are thread-safe and immutable. 064 * 065 * @author Stephen Colebourne 066 * @author Kandarp Shah 067 * @author Brian S O'Neill 068 * @since 1.0 069 * @see MutableDateTime 070 */ 071public final class DateTime 072 extends BaseDateTime 073 implements ReadableDateTime, Serializable { 074 075 /** Serialization lock */ 076 private static final long serialVersionUID = -5171125899451703815L; 077 078 //----------------------------------------------------------------------- 079 /** 080 * Constructs an instance set to the current system millisecond time 081 * using <code>ISOChronology</code> in the default time zone. 082 */ 083 public DateTime() { 084 super(); 085 } 086 087 /** 088 * Constructs an instance set to the current system millisecond time 089 * using <code>ISOChronology</code> in the specified time zone. 090 * <p> 091 * If the specified time zone is null, the default zone is used. 092 * 093 * @param zone the time zone, null means default zone 094 */ 095 public DateTime(DateTimeZone zone) { 096 super(zone); 097 } 098 099 /** 100 * Constructs an instance set to the current system millisecond time 101 * using the specified chronology. 102 * <p> 103 * If the chronology is null, <code>ISOChronology</code> 104 * in the default time zone is used. 105 * 106 * @param chronology the chronology, null means ISOChronology in default zone 107 */ 108 public DateTime(Chronology chronology) { 109 super(chronology); 110 } 111 112 //----------------------------------------------------------------------- 113 /** 114 * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z 115 * using <code>ISOChronology</code> in the default time zone. 116 * 117 * @param instant the milliseconds from 1970-01-01T00:00:00Z 118 */ 119 public DateTime(long instant) { 120 super(instant); 121 } 122 123 /** 124 * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z 125 * using <code>ISOChronology</code> in the specified time zone. 126 * <p> 127 * If the specified time zone is null, the default zone is used. 128 * 129 * @param instant the milliseconds from 1970-01-01T00:00:00Z 130 * @param zone the time zone, null means default zone 131 */ 132 public DateTime(long instant, DateTimeZone zone) { 133 super(instant, zone); 134 } 135 136 /** 137 * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z 138 * using the specified chronology. 139 * <p> 140 * If the chronology is null, <code>ISOChronology</code> 141 * in the default time zone is used. 142 * 143 * @param instant the milliseconds from 1970-01-01T00:00:00Z 144 * @param chronology the chronology, null means ISOChronology in default zone 145 */ 146 public DateTime(long instant, Chronology chronology) { 147 super(instant, chronology); 148 } 149 150 //----------------------------------------------------------------------- 151 /** 152 * Constructs an instance from an Object that represents a datetime. 153 * <p> 154 * If the object implies a chronology (such as GregorianCalendar does), 155 * then that chronology will be used. Otherwise, ISO default is used. 156 * Thus if a GregorianCalendar is passed in, the chronology used will 157 * be GJ, but if a Date is passed in the chronology will be ISO. 158 * <p> 159 * The recognised object types are defined in 160 * {@link org.joda.time.convert.ConverterManager ConverterManager} and 161 * include ReadableInstant, String, Calendar and Date. 162 * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}. 163 * 164 * @param instant the datetime object, null means now 165 * @throws IllegalArgumentException if the instant is invalid 166 */ 167 public DateTime(Object instant) { 168 super(instant, (Chronology) null); 169 } 170 171 /** 172 * Constructs an instance from an Object that represents a datetime, 173 * forcing the time zone to that specified. 174 * <p> 175 * If the object implies a chronology (such as GregorianCalendar does), 176 * then that chronology will be used, but with the time zone adjusted. 177 * Otherwise, ISO is used in the specified time zone. 178 * If the specified time zone is null, the default zone is used. 179 * Thus if a GregorianCalendar is passed in, the chronology used will 180 * be GJ, but if a Date is passed in the chronology will be ISO. 181 * <p> 182 * The recognised object types are defined in 183 * {@link org.joda.time.convert.ConverterManager ConverterManager} and 184 * include ReadableInstant, String, Calendar and Date. 185 * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}. 186 * 187 * @param instant the datetime object, null means now 188 * @param zone the time zone, null means default time zone 189 * @throws IllegalArgumentException if the instant is invalid 190 */ 191 public DateTime(Object instant, DateTimeZone zone) { 192 super(instant, zone); 193 } 194 195 /** 196 * Constructs an instance from an Object that represents a datetime, 197 * using the specified chronology. 198 * <p> 199 * If the chronology is null, ISO in the default time zone is used. 200 * Any chronology implied by the object (such as GregorianCalendar does) 201 * is ignored. 202 * <p> 203 * The recognised object types are defined in 204 * {@link org.joda.time.convert.ConverterManager ConverterManager} and 205 * include ReadableInstant, String, Calendar and Date. 206 * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}. 207 * 208 * @param instant the datetime object, null means now 209 * @param chronology the chronology, null means ISO in default zone 210 * @throws IllegalArgumentException if the instant is invalid 211 */ 212 public DateTime(Object instant, Chronology chronology) { 213 super(instant, DateTimeUtils.getChronology(chronology)); 214 } 215 216 //----------------------------------------------------------------------- 217 /** 218 * Constructs an instance from datetime field values 219 * using <code>ISOChronology</code> in the default time zone. 220 * 221 * @param year the year 222 * @param monthOfYear the month of the year 223 * @param dayOfMonth the day of the month 224 * @param hourOfDay the hour of the day 225 * @param minuteOfHour the minute of the hour 226 * @param secondOfMinute the second of the minute 227 * @param millisOfSecond the millisecond of the second 228 */ 229 public DateTime( 230 int year, 231 int monthOfYear, 232 int dayOfMonth, 233 int hourOfDay, 234 int minuteOfHour, 235 int secondOfMinute, 236 int millisOfSecond) { 237 super(year, monthOfYear, dayOfMonth, hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond); 238 } 239 240 /** 241 * Constructs an instance from datetime field values 242 * using <code>ISOChronology</code> in the specified time zone. 243 * <p> 244 * If the specified time zone is null, the default zone is used. 245 * 246 * @param year the year 247 * @param monthOfYear the month of the year 248 * @param dayOfMonth the day of the month 249 * @param hourOfDay the hour of the day 250 * @param minuteOfHour the minute of the hour 251 * @param secondOfMinute the second of the minute 252 * @param millisOfSecond the millisecond of the second 253 * @param zone the time zone, null means default time zone 254 */ 255 public DateTime( 256 int year, 257 int monthOfYear, 258 int dayOfMonth, 259 int hourOfDay, 260 int minuteOfHour, 261 int secondOfMinute, 262 int millisOfSecond, 263 DateTimeZone zone) { 264 super(year, monthOfYear, dayOfMonth, 265 hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond, zone); 266 } 267 268 /** 269 * Constructs an instance from datetime field values 270 * using the specified chronology. 271 * <p> 272 * If the chronology is null, <code>ISOChronology</code> 273 * in the default time zone is used. 274 * 275 * @param year the year 276 * @param monthOfYear the month of the year 277 * @param dayOfMonth the day of the month 278 * @param hourOfDay the hour of the day 279 * @param minuteOfHour the minute of the hour 280 * @param secondOfMinute the second of the minute 281 * @param millisOfSecond the millisecond of the second 282 * @param chronology the chronology, null means ISOChronology in default zone 283 */ 284 public DateTime( 285 int year, 286 int monthOfYear, 287 int dayOfMonth, 288 int hourOfDay, 289 int minuteOfHour, 290 int secondOfMinute, 291 int millisOfSecond, 292 Chronology chronology) { 293 super(year, monthOfYear, dayOfMonth, 294 hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond, chronology); 295 } 296 297 //----------------------------------------------------------------------- 298 /** 299 * Get this object as a DateTime by returning <code>this</code>. 300 * 301 * @return <code>this</code> 302 */ 303 public DateTime toDateTime() { 304 return this; 305 } 306 307 /** 308 * Get this object as a DateTime using ISOChronology in the default zone, 309 * returning <code>this</code> if possible. 310 * 311 * @return a DateTime using the same millis 312 */ 313 public DateTime toDateTimeISO() { 314 if (getChronology() == ISOChronology.getInstance()) { 315 return this; 316 } 317 return super.toDateTimeISO(); 318 } 319 320 /** 321 * Get this object as a DateTime, returning <code>this</code> if possible. 322 * 323 * @param zone time zone to apply, or default if null 324 * @return a DateTime using the same millis 325 */ 326 public DateTime toDateTime(DateTimeZone zone) { 327 zone = DateTimeUtils.getZone(zone); 328 if (getZone() == zone) { 329 return this; 330 } 331 return super.toDateTime(zone); 332 } 333 334 /** 335 * Get this object as a DateTime, returning <code>this</code> if possible. 336 * 337 * @param chronology chronology to apply, or ISOChronology if null 338 * @return a DateTime using the same millis 339 */ 340 public DateTime toDateTime(Chronology chronology) { 341 chronology = DateTimeUtils.getChronology(chronology); 342 if (getChronology() == chronology) { 343 return this; 344 } 345 return super.toDateTime(chronology); 346 } 347 348 //----------------------------------------------------------------------- 349 /** 350 * Returns a copy of this datetime with different millis. 351 * <p> 352 * The returned object will be either be a new instance or <code>this</code>. 353 * Only the millis will change, the chronology and time zone are kept. 354 * 355 * @param newMillis the new millis, from 1970-01-01T00:00:00Z 356 * @return a copy of this datetime with different millis 357 */ 358 public DateTime withMillis(long newMillis) { 359 return (newMillis == getMillis() ? this : new DateTime(newMillis, getChronology())); 360 } 361 362 /** 363 * Returns a copy of this datetime with a different chronology. 364 * <p> 365 * The returned object will be either be a new instance or <code>this</code>. 366 * Only the chronology will change, the millis are kept. 367 * 368 * @param newChronology the new chronology, null means ISO default 369 * @return a copy of this datetime with a different chronology 370 */ 371 public DateTime withChronology(Chronology newChronology) { 372 newChronology = DateTimeUtils.getChronology(newChronology); 373 return (newChronology == getChronology() ? this : new DateTime(getMillis(), newChronology)); 374 } 375 376 //----------------------------------------------------------------------- 377 /** 378 * Returns a copy of this datetime with a different time zone, preserving the 379 * millisecond instant. 380 * <p> 381 * This method is useful for finding the local time in another timezone. 382 * For example, if this instant holds 12:30 in Europe/London, the result 383 * from this method with Europe/Paris would be 13:30. 384 * <p> 385 * The returned object will be a new instance of the same implementation type. 386 * This method changes the time zone, and does not change the 387 * millisecond instant, with the effect that the field values usually change. 388 * The returned object will be either be a new instance or <code>this</code>. 389 * 390 * @param newZone the new time zone 391 * @return a copy of this datetime with a different time zone 392 * @see #withZoneRetainFields 393 */ 394 public DateTime withZone(DateTimeZone newZone) { 395 return withChronology(getChronology().withZone(newZone)); 396 } 397 398 /** 399 * Returns a copy of this datetime with a different time zone, preserving the 400 * field values. 401 * <p> 402 * This method is useful for finding the millisecond time in another timezone. 403 * For example, if this instant holds 12:30 in Europe/London (ie. 12:30Z), 404 * the result from this method with Europe/Paris would be 12:30 (ie. 11:30Z). 405 * <p> 406 * The returned object will be a new instance of the same implementation type. 407 * This method changes the time zone and the millisecond instant to keep 408 * the field values the same. 409 * The returned object will be either be a new instance or <code>this</code>. 410 * 411 * @param newZone the new time zone, null means default 412 * @return a copy of this datetime with a different time zone 413 * @see #withZone 414 */ 415 public DateTime withZoneRetainFields(DateTimeZone newZone) { 416 newZone = DateTimeUtils.getZone(newZone); 417 DateTimeZone originalZone = DateTimeUtils.getZone(getZone()); 418 if (newZone == originalZone) { 419 return this; 420 } 421 422 long millis = originalZone.getMillisKeepLocal(newZone, getMillis()); 423 return new DateTime(millis, getChronology().withZone(newZone)); 424 } 425 426 //----------------------------------------------------------------------- 427 /** 428 * Returns a copy of this datetime with the specified date, retaining the time fields. 429 * <p> 430 * If the date is already the date passed in, then <code>this</code> is returned. 431 * <p> 432 * To set a single field use the properties, for example: 433 * <pre> 434 * DateTime set = monthOfYear().setCopy(6); 435 * </pre> 436 * 437 * @param year the new year value 438 * @param monthOfYear the new monthOfYear value 439 * @param dayOfMonth the new dayOfMonth value 440 * @return a copy of this datetime with a different date 441 * @throws IllegalArgumentException if any value if invalid 442 */ 443 public DateTime withDate(int year, int monthOfYear, int dayOfMonth) { 444 Chronology chrono = getChronology(); 445 long instant = getMillis(); 446 instant = chrono.year().set(instant, year); 447 instant = chrono.monthOfYear().set(instant, monthOfYear); 448 instant = chrono.dayOfMonth().set(instant, dayOfMonth); 449 return withMillis(instant); 450 } 451 452 /** 453 * Returns a copy of this datetime with the specified time, retaining the date fields. 454 * <p> 455 * If the time is already the time passed in, then <code>this</code> is returned. 456 * <p> 457 * To set a single field use the properties, for example: 458 * <pre> 459 * DateTime set = dt.hourOfDay().setCopy(6); 460 * </pre> 461 * 462 * @param hourOfDay the hour of the day 463 * @param minuteOfHour the minute of the hour 464 * @param secondOfMinute the second of the minute 465 * @param millisOfSecond the millisecond of the second 466 * @return a copy of this datetime with a different time 467 * @throws IllegalArgumentException if any value if invalid 468 */ 469 public DateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int millisOfSecond) { 470 Chronology chrono = getChronology(); 471 long instant = getMillis(); 472 instant = chrono.hourOfDay().set(instant, hourOfDay); 473 instant = chrono.minuteOfHour().set(instant, minuteOfHour); 474 instant = chrono.secondOfMinute().set(instant, secondOfMinute); 475 instant = chrono.millisOfSecond().set(instant, millisOfSecond); 476 return withMillis(instant); 477 } 478 479 //----------------------------------------------------------------------- 480 /** 481 * Returns a copy of this datetime with the partial set of fields replacing those 482 * from this instance. 483 * <p> 484 * For example, if the partial is a <code>TimeOfDay</code> then the time fields 485 * would be changed in the returned instance. 486 * If the partial is null, then <code>this</code> is returned. 487 * 488 * @param partial the partial set of fields to apply to this datetime, null ignored 489 * @return a copy of this datetime with a different set of fields 490 * @throws IllegalArgumentException if any value is invalid 491 */ 492 public DateTime withFields(ReadablePartial partial) { 493 if (partial == null) { 494 return this; 495 } 496 return withMillis(getChronology().set(partial, getMillis())); 497 } 498 499 /** 500 * Returns a copy of this datetime with the specified field set to a new value. 501 * <p> 502 * For example, if the field type is <code>hourOfDay</code> then the hour of day 503 * field would be changed in the returned instance. 504 * If the field type is null, then <code>this</code> is returned. 505 * <p> 506 * These three lines are equivalent: 507 * <pre> 508 * DateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6); 509 * DateTime updated = dt.dayOfMonth().setCopy(6); 510 * DateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6); 511 * </pre> 512 * 513 * @param fieldType the field type to set, not null 514 * @param value the value to set 515 * @return a copy of this datetime with the field set 516 * @throws IllegalArgumentException if the value is null or invalid 517 */ 518 public DateTime withField(DateTimeFieldType fieldType, int value) { 519 if (fieldType == null) { 520 throw new IllegalArgumentException("Field must not be null"); 521 } 522 long instant = fieldType.getField(getChronology()).set(getMillis(), value); 523 return withMillis(instant); 524 } 525 526 /** 527 * Returns a copy of this datetime with the value of the specified field increased. 528 * <p> 529 * If the addition is zero or the field is null, then <code>this</code> is returned. 530 * <p> 531 * These three lines are equivalent: 532 * <pre> 533 * DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6); 534 * DateTime added = dt.plusYears(6); 535 * DateTime added = dt.plus(Period.years(6)); 536 * </pre> 537 * 538 * @param fieldType the field type to add to, not null 539 * @param amount the amount to add 540 * @return a copy of this datetime with the field updated 541 * @throws IllegalArgumentException if the value is null or invalid 542 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 543 */ 544 public DateTime withFieldAdded(DurationFieldType fieldType, int amount) { 545 if (fieldType == null) { 546 throw new IllegalArgumentException("Field must not be null"); 547 } 548 if (amount == 0) { 549 return this; 550 } 551 long instant = fieldType.getField(getChronology()).add(getMillis(), amount); 552 return withMillis(instant); 553 } 554 555 //----------------------------------------------------------------------- 556 /** 557 * Returns a copy of this datetime with the specified duration added. 558 * <p> 559 * If the addition is zero, then <code>this</code> is returned. 560 * 561 * @param durationToAdd the duration to add to this one 562 * @param scalar the amount of times to add, such as -1 to subtract once 563 * @return a copy of this datetime with the duration added 564 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 565 */ 566 public DateTime withDurationAdded(long durationToAdd, int scalar) { 567 if (durationToAdd == 0 || scalar == 0) { 568 return this; 569 } 570 long instant = getChronology().add(getMillis(), durationToAdd, scalar); 571 return withMillis(instant); 572 } 573 574 /** 575 * Returns a copy of this datetime with the specified duration added. 576 * <p> 577 * If the addition is zero, then <code>this</code> is returned. 578 * 579 * @param durationToAdd the duration to add to this one, null means zero 580 * @param scalar the amount of times to add, such as -1 to subtract once 581 * @return a copy of this datetime with the duration added 582 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 583 */ 584 public DateTime withDurationAdded(ReadableDuration durationToAdd, int scalar) { 585 if (durationToAdd == null || scalar == 0) { 586 return this; 587 } 588 return withDurationAdded(durationToAdd.getMillis(), scalar); 589 } 590 591 /** 592 * Returns a copy of this datetime with the specified period added. 593 * <p> 594 * If the addition is zero, then <code>this</code> is returned. 595 * <p> 596 * This method is typically used to add multiple copies of complex 597 * period instances. Adding one field is best achieved using methods 598 * like {@link #withFieldAdded(DurationFieldType, int)} 599 * or {@link #plusYears(int)}. 600 * 601 * @param period the period to add to this one, null means zero 602 * @param scalar the amount of times to add, such as -1 to subtract once 603 * @return a copy of this datetime with the period added 604 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 605 */ 606 public DateTime withPeriodAdded(ReadablePeriod period, int scalar) { 607 if (period == null || scalar == 0) { 608 return this; 609 } 610 long instant = getChronology().add(period, getMillis(), scalar); 611 return withMillis(instant); 612 } 613 614 //----------------------------------------------------------------------- 615 /** 616 * Returns a copy of this datetime with the specified duration added. 617 * <p> 618 * If the amount is zero or null, then <code>this</code> is returned. 619 * This datetime instance is immutable and unaffected by this method call. 620 * 621 * @param duration the duration, in millis, to add to this one 622 * @return a copy of this datetime with the duration added 623 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 624 */ 625 public DateTime plus(long duration) { 626 return withDurationAdded(duration, 1); 627 } 628 629 /** 630 * Returns a copy of this datetime with the specified duration added. 631 * <p> 632 * If the amount is zero or null, then <code>this</code> is returned. 633 * This datetime instance is immutable and unaffected by this method call. 634 * 635 * @param duration the duration to add to this one, null means zero 636 * @return a copy of this datetime with the duration added 637 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 638 */ 639 public DateTime plus(ReadableDuration duration) { 640 return withDurationAdded(duration, 1); 641 } 642 643 /** 644 * Returns a copy of this datetime with the specified period added. 645 * <p> 646 * This method will add each element of the period one by one, from largest 647 * to smallest, adjusting the datetime to be accurate between each. 648 * <p> 649 * Thus, adding a period of one month and one day to 2007-03-31 will 650 * work as follows: 651 * First add one month and adjust, resulting in 2007-04-30 652 * Then add one day and adjust, resulting in 2007-05-01. 653 * <p> 654 * This method is typically used to add complex period instances. 655 * Adding one field is best achieved using methods 656 * like {@link #plusYears(int)}. 657 * <p> 658 * If the amount is zero or null, then <code>this</code> is returned. 659 * This datetime instance is immutable and unaffected by this method call. 660 * 661 * @param period the duration to add to this one, null means zero 662 * @return a copy of this datetime with the period added 663 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 664 */ 665 public DateTime plus(ReadablePeriod period) { 666 return withPeriodAdded(period, 1); 667 } 668 669 //----------------------------------------------------------------------- 670 /** 671 * Returns a copy of this datetime plus the specified number of years. 672 * <p> 673 * The calculation will do its best to only change the year field 674 * retaining the same month of year. 675 * However, in certain circumstances, it may be necessary to alter 676 * smaller fields. For example, 2008-02-29 plus one year cannot result 677 * in 2009-02-29, so the day of month is adjusted to 2009-02-28. 678 * <p> 679 * The following three lines are identical in effect: 680 * <pre> 681 * DateTime added = dt.plusYears(6); 682 * DateTime added = dt.plus(Period.years(6)); 683 * DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6); 684 * </pre> 685 * <p> 686 * This datetime instance is immutable and unaffected by this method call. 687 * 688 * @param years the amount of years to add, may be negative 689 * @return the new datetime plus the increased years 690 * @since 1.1 691 */ 692 public DateTime plusYears(int years) { 693 if (years == 0) { 694 return this; 695 } 696 long instant = getChronology().years().add(getMillis(), years); 697 return withMillis(instant); 698 } 699 700 /** 701 * Returns a copy of this datetime plus the specified number of months. 702 * <p> 703 * The calculation will do its best to only change the month field 704 * retaining the same day of month. 705 * However, in certain circumstances, it may be necessary to alter 706 * smaller fields. For example, 2007-03-31 plus one month cannot result 707 * in 2007-04-31, so the day of month is adjusted to 2007-04-30. 708 * <p> 709 * The following three lines are identical in effect: 710 * <pre> 711 * DateTime added = dt.plusMonths(6); 712 * DateTime added = dt.plus(Period.months(6)); 713 * DateTime added = dt.withFieldAdded(DurationFieldType.months(), 6); 714 * </pre> 715 * <p> 716 * This datetime instance is immutable and unaffected by this method call. 717 * 718 * @param months the amount of months to add, may be negative 719 * @return the new datetime plus the increased months 720 * @since 1.1 721 */ 722 public DateTime plusMonths(int months) { 723 if (months == 0) { 724 return this; 725 } 726 long instant = getChronology().months().add(getMillis(), months); 727 return withMillis(instant); 728 } 729 730 /** 731 * Returns a copy of this datetime plus the specified number of weeks. 732 * <p> 733 * The calculation operates as if it were adding the equivalent in days. 734 * <p> 735 * The following three lines are identical in effect: 736 * <pre> 737 * DateTime added = dt.plusWeeks(6); 738 * DateTime added = dt.plus(Period.weeks(6)); 739 * DateTime added = dt.withFieldAdded(DurationFieldType.weeks(), 6); 740 * </pre> 741 * <p> 742 * This datetime instance is immutable and unaffected by this method call. 743 * 744 * @param weeks the amount of weeks to add, may be negative 745 * @return the new datetime plus the increased weeks 746 * @since 1.1 747 */ 748 public DateTime plusWeeks(int weeks) { 749 if (weeks == 0) { 750 return this; 751 } 752 long instant = getChronology().weeks().add(getMillis(), weeks); 753 return withMillis(instant); 754 } 755 756 /** 757 * Returns a copy of this datetime plus the specified number of days. 758 * <p> 759 * The calculation will do its best to only change the day field 760 * retaining the same time of day. 761 * However, in certain circumstances, typically daylight savings cutover, 762 * it may be necessary to alter the time fields. 763 * <p> 764 * In spring an hour is typically removed. If adding one day results in 765 * the time being within the cutover then the time is adjusted to be 766 * within summer time. For example, if the cutover is from 01:59 to 03:00 767 * and the result of this method would have been 02:30, then the result 768 * will be adjusted to 03:30. 769 * <p> 770 * The following three lines are identical in effect: 771 * <pre> 772 * DateTime added = dt.plusDays(6); 773 * DateTime added = dt.plus(Period.days(6)); 774 * DateTime added = dt.withFieldAdded(DurationFieldType.days(), 6); 775 * </pre> 776 * <p> 777 * This datetime instance is immutable and unaffected by this method call. 778 * 779 * @param days the amount of days to add, may be negative 780 * @return the new datetime plus the increased days 781 * @since 1.1 782 */ 783 public DateTime plusDays(int days) { 784 if (days == 0) { 785 return this; 786 } 787 long instant = getChronology().days().add(getMillis(), days); 788 return withMillis(instant); 789 } 790 791 /** 792 * Returns a copy of this datetime plus the specified number of hours. 793 * <p> 794 * The calculation will add a duration equivalent to the number of hours 795 * expressed in milliseconds. 796 * <p> 797 * For example, if a spring daylight savings cutover is from 01:59 to 03:00 798 * then adding one hour to 01:30 will result in 03:30. This is a duration 799 * of one hour later, even though the hour field value changed from 1 to 3. 800 * <p> 801 * The following three lines are identical in effect: 802 * <pre> 803 * DateTime added = dt.plusHours(6); 804 * DateTime added = dt.plus(Period.hours(6)); 805 * DateTime added = dt.withFieldAdded(DurationFieldType.hours(), 6); 806 * </pre> 807 * <p> 808 * This datetime instance is immutable and unaffected by this method call. 809 * 810 * @param hours the amount of hours to add, may be negative 811 * @return the new datetime plus the increased hours 812 * @since 1.1 813 */ 814 public DateTime plusHours(int hours) { 815 if (hours == 0) { 816 return this; 817 } 818 long instant = getChronology().hours().add(getMillis(), hours); 819 return withMillis(instant); 820 } 821 822 /** 823 * Returns a copy of this datetime plus the specified number of minutes. 824 * <p> 825 * The calculation will add a duration equivalent to the number of minutes 826 * expressed in milliseconds. 827 * <p> 828 * The following three lines are identical in effect: 829 * <pre> 830 * DateTime added = dt.plusMinutes(6); 831 * DateTime added = dt.plus(Period.minutes(6)); 832 * DateTime added = dt.withFieldAdded(DurationFieldType.minutes(), 6); 833 * </pre> 834 * <p> 835 * This datetime instance is immutable and unaffected by this method call. 836 * 837 * @param minutes the amount of minutes to add, may be negative 838 * @return the new datetime plus the increased minutes 839 * @since 1.1 840 */ 841 public DateTime plusMinutes(int minutes) { 842 if (minutes == 0) { 843 return this; 844 } 845 long instant = getChronology().minutes().add(getMillis(), minutes); 846 return withMillis(instant); 847 } 848 849 /** 850 * Returns a copy of this datetime plus the specified number of seconds. 851 * <p> 852 * The calculation will add a duration equivalent to the number of seconds 853 * expressed in milliseconds. 854 * <p> 855 * The following three lines are identical in effect: 856 * <pre> 857 * DateTime added = dt.plusSeconds(6); 858 * DateTime added = dt.plus(Period.seconds(6)); 859 * DateTime added = dt.withFieldAdded(DurationFieldType.seconds(), 6); 860 * </pre> 861 * <p> 862 * This datetime instance is immutable and unaffected by this method call. 863 * 864 * @param seconds the amount of seconds to add, may be negative 865 * @return the new datetime plus the increased seconds 866 * @since 1.1 867 */ 868 public DateTime plusSeconds(int seconds) { 869 if (seconds == 0) { 870 return this; 871 } 872 long instant = getChronology().seconds().add(getMillis(), seconds); 873 return withMillis(instant); 874 } 875 876 /** 877 * Returns a copy of this datetime plus the specified number of millis. 878 * <p> 879 * The calculation will add a duration equivalent to the number of milliseconds. 880 * <p> 881 * The following three lines are identical in effect: 882 * <pre> 883 * DateTime added = dt.plusMillis(6); 884 * DateTime added = dt.plus(Period.millis(6)); 885 * DateTime added = dt.withFieldAdded(DurationFieldType.millis(), 6); 886 * </pre> 887 * <p> 888 * This datetime instance is immutable and unaffected by this method call. 889 * 890 * @param millis the amount of millis to add, may be negative 891 * @return the new datetime plus the increased millis 892 * @since 1.1 893 */ 894 public DateTime plusMillis(int millis) { 895 if (millis == 0) { 896 return this; 897 } 898 long instant = getChronology().millis().add(getMillis(), millis); 899 return withMillis(instant); 900 } 901 902 //----------------------------------------------------------------------- 903 /** 904 * Returns a copy of this datetime with the specified duration taken away. 905 * <p> 906 * If the amount is zero or null, then <code>this</code> is returned. 907 * This datetime instance is immutable and unaffected by this method call. 908 * 909 * @param duration the duration, in millis, to reduce this instant by 910 * @return a copy of this datetime with the duration taken away 911 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 912 */ 913 public DateTime minus(long duration) { 914 return withDurationAdded(duration, -1); 915 } 916 917 /** 918 * Returns a copy of this datetime with the specified duration taken away. 919 * <p> 920 * If the amount is zero or null, then <code>this</code> is returned. 921 * This datetime instance is immutable and unaffected by this method call. 922 * 923 * @param duration the duration to reduce this instant by 924 * @return a copy of this datetime with the duration taken away 925 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 926 */ 927 public DateTime minus(ReadableDuration duration) { 928 return withDurationAdded(duration, -1); 929 } 930 931 /** 932 * Returns a copy of this datetime with the specified period taken away. 933 * <p> 934 * This method will subtract each element of the period one by one, from 935 * largest to smallest, adjusting the datetime to be accurate between each. 936 * <p> 937 * Thus, subtracting a period of one month and one day from 2007-05-31 will 938 * work as follows: 939 * First subtract one month and adjust, resulting in 2007-04-30 940 * Then subtract one day and adjust, resulting in 2007-04-29. 941 * Note that the day has been adjusted by two. 942 * <p> 943 * This method is typically used to subtract complex period instances. 944 * Subtracting one field is best achieved using methods 945 * like {@link #minusYears(int)}. 946 * <p> 947 * If the amount is zero or null, then <code>this</code> is returned. 948 * This datetime instance is immutable and unaffected by this method call. 949 * 950 * @param period the period to reduce this instant by 951 * @return a copy of this datetime with the period taken away 952 * @throws ArithmeticException if the new datetime exceeds the capacity of a long 953 */ 954 public DateTime minus(ReadablePeriod period) { 955 return withPeriodAdded(period, -1); 956 } 957 958 //----------------------------------------------------------------------- 959 /** 960 * Returns a copy of this datetime minus the specified number of years. 961 * <p> 962 * The calculation will do its best to only change the year field 963 * retaining the same month of year. 964 * However, in certain circumstances, it may be necessary to alter 965 * smaller fields. For example, 2008-02-29 minus one year cannot result 966 * in 2007-02-29, so the day of month is adjusted to 2007-02-28. 967 * <p> 968 * The following three lines are identical in effect: 969 * <pre> 970 * DateTime subtracted = dt.minusYears(6); 971 * DateTime subtracted = dt.minus(Period.years(6)); 972 * DateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6); 973 * </pre> 974 * <p> 975 * This datetime instance is immutable and unaffected by this method call. 976 * 977 * @param years the amount of years to subtract, may be negative 978 * @return the new datetime minus the increased years 979 * @since 1.1 980 */ 981 public DateTime minusYears(int years) { 982 if (years == 0) { 983 return this; 984 } 985 long instant = getChronology().years().subtract(getMillis(), years); 986 return withMillis(instant); 987 } 988 989 /** 990 * Returns a copy of this datetime minus the specified number of months. 991 * <p> 992 * The calculation will do its best to only change the month field 993 * retaining the same day of month. 994 * However, in certain circumstances, it may be necessary to alter 995 * smaller fields. For example, 2007-05-31 minus one month cannot result 996 * in 2007-04-31, so the day of month is adjusted to 2007-04-30. 997 * <p> 998 * The following three lines are identical in effect: 999 * <pre> 1000 * DateTime subtracted = dt.minusMonths(6); 1001 * DateTime subtracted = dt.minus(Period.months(6)); 1002 * DateTime subtracted = dt.withFieldAdded(DurationFieldType.months(), -6); 1003 * </pre> 1004 * <p> 1005 * This datetime instance is immutable and unaffected by this method call. 1006 * 1007 * @param months the amount of months to subtract, may be negative 1008 * @return the new datetime minus the increased months 1009 * @since 1.1 1010 */ 1011 public DateTime minusMonths(int months) { 1012 if (months == 0) { 1013 return this; 1014 } 1015 long instant = getChronology().months().subtract(getMillis(), months); 1016 return withMillis(instant); 1017 } 1018 1019 /** 1020 * Returns a copy of this datetime minus the specified number of weeks. 1021 * <p> 1022 * The calculation operates as if it were subtracting the equivalent in days. 1023 * <p> 1024 * The following three lines are identical in effect: 1025 * <pre> 1026 * DateTime subtracted = dt.minusWeeks(6); 1027 * DateTime subtracted = dt.minus(Period.weeks(6)); 1028 * DateTime subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6); 1029 * </pre> 1030 * <p> 1031 * This datetime instance is immutable and unaffected by this method call. 1032 * 1033 * @param weeks the amount of weeks to subtract, may be negative 1034 * @return the new datetime minus the increased weeks 1035 * @since 1.1 1036 */ 1037 public DateTime minusWeeks(int weeks) { 1038 if (weeks == 0) { 1039 return this; 1040 } 1041 long instant = getChronology().weeks().subtract(getMillis(), weeks); 1042 return withMillis(instant); 1043 } 1044 1045 /** 1046 * Returns a copy of this datetime minus the specified number of days. 1047 * <p> 1048 * The calculation will do its best to only change the day field 1049 * retaining the same time of day. 1050 * However, in certain circumstances, typically daylight savings cutover, 1051 * it may be necessary to alter the time fields. 1052 * <p> 1053 * In spring an hour is typically removed. If subtracting one day results 1054 * in the time being within the cutover then the time is adjusted to be 1055 * within summer time. For example, if the cutover is from 01:59 to 03:00 1056 * and the result of this method would have been 02:30, then the result 1057 * will be adjusted to 03:30. 1058 * <p> 1059 * The following three lines are identical in effect: 1060 * <pre> 1061 * DateTime subtracted = dt.minusDays(6); 1062 * DateTime subtracted = dt.minus(Period.days(6)); 1063 * DateTime subtracted = dt.withFieldAdded(DurationFieldType.days(), -6); 1064 * </pre> 1065 * <p> 1066 * This datetime instance is immutable and unaffected by this method call. 1067 * 1068 * @param days the amount of days to subtract, may be negative 1069 * @return the new datetime minus the increased days 1070 * @since 1.1 1071 */ 1072 public DateTime minusDays(int days) { 1073 if (days == 0) { 1074 return this; 1075 } 1076 long instant = getChronology().days().subtract(getMillis(), days); 1077 return withMillis(instant); 1078 } 1079 1080 /** 1081 * Returns a copy of this datetime minus the specified number of hours. 1082 * <p> 1083 * The calculation will subtract a duration equivalent to the number of 1084 * hours expressed in milliseconds. 1085 * <p> 1086 * For example, if a spring daylight savings cutover is from 01:59 to 03:00 1087 * then subtracting one hour from 03:30 will result in 01:30. This is a 1088 * duration of one hour earlier, even though the hour field value changed 1089 * from 3 to 1. 1090 * <p> 1091 * The following three lines are identical in effect: 1092 * <pre> 1093 * DateTime subtracted = dt.minusHours(6); 1094 * DateTime subtracted = dt.minus(Period.hours(6)); 1095 * DateTime subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6); 1096 * </pre> 1097 * <p> 1098 * This datetime instance is immutable and unaffected by this method call. 1099 * 1100 * @param hours the amount of hours to subtract, may be negative 1101 * @return the new datetime minus the increased hours 1102 * @since 1.1 1103 */ 1104 public DateTime minusHours(int hours) { 1105 if (hours == 0) { 1106 return this; 1107 } 1108 long instant = getChronology().hours().subtract(getMillis(), hours); 1109 return withMillis(instant); 1110 } 1111 1112 /** 1113 * Returns a copy of this datetime minus the specified number of minutes. 1114 * <p> 1115 * The calculation will subtract a duration equivalent to the number of 1116 * minutes expressed in milliseconds. 1117 * <p> 1118 * The following three lines are identical in effect: 1119 * <pre> 1120 * DateTime subtracted = dt.minusMinutes(6); 1121 * DateTime subtracted = dt.minus(Period.minutes(6)); 1122 * DateTime subtracted = dt.withFieldAdded(DurationFieldType.minutes(), -6); 1123 * </pre> 1124 * <p> 1125 * This datetime instance is immutable and unaffected by this method call. 1126 * 1127 * @param minutes the amount of minutes to subtract, may be negative 1128 * @return the new datetime minus the increased minutes 1129 * @since 1.1 1130 */ 1131 public DateTime minusMinutes(int minutes) { 1132 if (minutes == 0) { 1133 return this; 1134 } 1135 long instant = getChronology().minutes().subtract(getMillis(), minutes); 1136 return withMillis(instant); 1137 } 1138 1139 /** 1140 * Returns a copy of this datetime minus the specified number of seconds. 1141 * <p> 1142 * The calculation will subtract a duration equivalent to the number of 1143 * seconds expressed in milliseconds. 1144 * <p> 1145 * The following three lines are identical in effect: 1146 * <pre> 1147 * DateTime subtracted = dt.minusSeconds(6); 1148 * DateTime subtracted = dt.minus(Period.seconds(6)); 1149 * DateTime subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6); 1150 * </pre> 1151 * <p> 1152 * This datetime instance is immutable and unaffected by this method call. 1153 * 1154 * @param seconds the amount of seconds to subtract, may be negative 1155 * @return the new datetime minus the increased seconds 1156 * @since 1.1 1157 */ 1158 public DateTime minusSeconds(int seconds) { 1159 if (seconds == 0) { 1160 return this; 1161 } 1162 long instant = getChronology().seconds().subtract(getMillis(), seconds); 1163 return withMillis(instant); 1164 } 1165 1166 /** 1167 * Returns a copy of this datetime minus the specified number of millis. 1168 * <p> 1169 * The calculation will subtract a duration equivalent to the number of 1170 * milliseconds. 1171 * <p> 1172 * The following three lines are identical in effect: 1173 * <pre> 1174 * DateTime subtracted = dt.minusMillis(6); 1175 * DateTime subtracted = dt.minus(Period.millis(6)); 1176 * DateTime subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6); 1177 * </pre> 1178 * <p> 1179 * This datetime instance is immutable and unaffected by this method call. 1180 * 1181 * @param millis the amount of millis to subtract, may be negative 1182 * @return the new datetime minus the increased millis 1183 * @since 1.1 1184 */ 1185 public DateTime minusMillis(int millis) { 1186 if (millis == 0) { 1187 return this; 1188 } 1189 long instant = getChronology().millis().subtract(getMillis(), millis); 1190 return withMillis(instant); 1191 } 1192 1193 //----------------------------------------------------------------------- 1194 /** 1195 * Gets the property object for the specified type, which contains many useful methods. 1196 * 1197 * @param type the field type to get the chronology for 1198 * @return the property object 1199 * @throws IllegalArgumentException if the field is null or unsupported 1200 */ 1201 public Property property(DateTimeFieldType type) { 1202 if (type == null) { 1203 throw new IllegalArgumentException("The DateTimeFieldType must not be null"); 1204 } 1205 DateTimeField field = type.getField(getChronology()); 1206 if (field.isSupported() == false) { 1207 throw new IllegalArgumentException("Field '" + type + "' is not supported"); 1208 } 1209 return new Property(this, field); 1210 } 1211 1212 //----------------------------------------------------------------------- 1213 /** 1214 * Converts this object to a <code>DateMidnight</code> using the 1215 * same millis and chronology. 1216 * 1217 * @return a DateMidnight using the same millis and chronology 1218 */ 1219 public DateMidnight toDateMidnight() { 1220 return new DateMidnight(getMillis(), getChronology()); 1221 } 1222 1223 /** 1224 * Converts this object to a <code>YearMonthDay</code> using the 1225 * same millis and chronology. 1226 * 1227 * @return a YearMonthDay using the same millis and chronology 1228 * @deprecated Use LocalDate instead of YearMonthDay 1229 */ 1230 public YearMonthDay toYearMonthDay() { 1231 return new YearMonthDay(getMillis(), getChronology()); 1232 } 1233 1234 /** 1235 * Converts this object to a <code>TimeOfDay</code> using the 1236 * same millis and chronology. 1237 * 1238 * @return a TimeOfDay using the same millis and chronology 1239 * @deprecated Use LocalTime instead of TimeOfDay 1240 */ 1241 public TimeOfDay toTimeOfDay() { 1242 return new TimeOfDay(getMillis(), getChronology()); 1243 } 1244 1245 /** 1246 * Converts this object to a <code>LocalDateTime</code> with 1247 * the same datetime and chronology. 1248 * 1249 * @return a LocalDateTime with the same datetime and chronology 1250 * @since 1.3 1251 */ 1252 public LocalDateTime toLocalDateTime() { 1253 return new LocalDateTime(getMillis(), getChronology()); 1254 } 1255 1256 /** 1257 * Converts this object to a <code>LocalDate</code> with the 1258 * same date and chronology. 1259 * 1260 * @return a LocalDate with the same date and chronology 1261 * @since 1.3 1262 */ 1263 public LocalDate toLocalDate() { 1264 return new LocalDate(getMillis(), getChronology()); 1265 } 1266 1267 /** 1268 * Converts this object to a <code>LocalTime</code> with the 1269 * same time and chronology. 1270 * 1271 * @return a LocalTime with the same time and chronology 1272 * @since 1.3 1273 */ 1274 public LocalTime toLocalTime() { 1275 return new LocalTime(getMillis(), getChronology()); 1276 } 1277 1278 //----------------------------------------------------------------------- 1279 /** 1280 * Returns a copy of this datetime with the era field updated. 1281 * <p> 1282 * DateTime is immutable, so there are no set methods. 1283 * Instead, this method returns a new instance with the value of 1284 * era changed. 1285 * 1286 * @param era the era to set 1287 * @return a copy of this object with the field set 1288 * @throws IllegalArgumentException if the value is invalid 1289 * @since 1.3 1290 */ 1291 public DateTime withEra(int era) { 1292 return withMillis(getChronology().era().set(getMillis(), era)); 1293 } 1294 1295 /** 1296 * Returns a copy of this datetime with the century of era field updated. 1297 * <p> 1298 * DateTime is immutable, so there are no set methods. 1299 * Instead, this method returns a new instance with the value of 1300 * century of era changed. 1301 * 1302 * @param centuryOfEra the centurey of era to set 1303 * @return a copy of this object with the field set 1304 * @throws IllegalArgumentException if the value is invalid 1305 * @since 1.3 1306 */ 1307 public DateTime withCenturyOfEra(int centuryOfEra) { 1308 return withMillis(getChronology().centuryOfEra().set(getMillis(), centuryOfEra)); 1309 } 1310 1311 /** 1312 * Returns a copy of this datetime with the year of era field updated. 1313 * <p> 1314 * DateTime is immutable, so there are no set methods. 1315 * Instead, this method returns a new instance with the value of 1316 * year of era changed. 1317 * 1318 * @param yearOfEra the year of era to set 1319 * @return a copy of this object with the field set 1320 * @throws IllegalArgumentException if the value is invalid 1321 * @since 1.3 1322 */ 1323 public DateTime withYearOfEra(int yearOfEra) { 1324 return withMillis(getChronology().yearOfEra().set(getMillis(), yearOfEra)); 1325 } 1326 1327 /** 1328 * Returns a copy of this datetime with the year of century field updated. 1329 * <p> 1330 * DateTime is immutable, so there are no set methods. 1331 * Instead, this method returns a new instance with the value of 1332 * year of century changed. 1333 * 1334 * @param yearOfCentury the year of century to set 1335 * @return a copy of this object with the field set 1336 * @throws IllegalArgumentException if the value is invalid 1337 * @since 1.3 1338 */ 1339 public DateTime withYearOfCentury(int yearOfCentury) { 1340 return withMillis(getChronology().yearOfCentury().set(getMillis(), yearOfCentury)); 1341 } 1342 1343 /** 1344 * Returns a copy of this datetime with the year field updated. 1345 * <p> 1346 * DateTime is immutable, so there are no set methods. 1347 * Instead, this method returns a new instance with the value of 1348 * year changed. 1349 * 1350 * @param year the year to set 1351 * @return a copy of this object with the field set 1352 * @throws IllegalArgumentException if the value is invalid 1353 * @since 1.3 1354 */ 1355 public DateTime withYear(int year) { 1356 return withMillis(getChronology().year().set(getMillis(), year)); 1357 } 1358 1359 /** 1360 * Returns a copy of this datetime with the weekyear field updated. 1361 * <p> 1362 * DateTime is immutable, so there are no set methods. 1363 * Instead, this method returns a new instance with the value of 1364 * weekyear changed. 1365 * 1366 * @param weekyear the weekyear to set 1367 * @return a copy of this object with the field set 1368 * @throws IllegalArgumentException if the value is invalid 1369 * @since 1.3 1370 */ 1371 public DateTime withWeekyear(int weekyear) { 1372 return withMillis(getChronology().weekyear().set(getMillis(), weekyear)); 1373 } 1374 1375 /** 1376 * Returns a copy of this datetime with the month of year field updated. 1377 * <p> 1378 * DateTime is immutable, so there are no set methods. 1379 * Instead, this method returns a new instance with the value of 1380 * month of year changed. 1381 * 1382 * @param monthOfYear the month of year to set 1383 * @return a copy of this object with the field set 1384 * @throws IllegalArgumentException if the value is invalid 1385 * @since 1.3 1386 */ 1387 public DateTime withMonthOfYear(int monthOfYear) { 1388 return withMillis(getChronology().monthOfYear().set(getMillis(), monthOfYear)); 1389 } 1390 1391 /** 1392 * Returns a copy of this datetime with the week of weekyear field updated. 1393 * <p> 1394 * DateTime is immutable, so there are no set methods. 1395 * Instead, this method returns a new instance with the value of 1396 * week of weekyear changed. 1397 * 1398 * @param weekOfWeekyear the week of weekyear to set 1399 * @return a copy of this object with the field set 1400 * @throws IllegalArgumentException if the value is invalid 1401 * @since 1.3 1402 */ 1403 public DateTime withWeekOfWeekyear(int weekOfWeekyear) { 1404 return withMillis(getChronology().weekOfWeekyear().set(getMillis(), weekOfWeekyear)); 1405 } 1406 1407 /** 1408 * Returns a copy of this datetime with the day of year field updated. 1409 * <p> 1410 * DateTime is immutable, so there are no set methods. 1411 * Instead, this method returns a new instance with the value of 1412 * day of year changed. 1413 * 1414 * @param dayOfYear the day of year to set 1415 * @return a copy of this object with the field set 1416 * @throws IllegalArgumentException if the value is invalid 1417 * @since 1.3 1418 */ 1419 public DateTime withDayOfYear(int dayOfYear) { 1420 return withMillis(getChronology().dayOfYear().set(getMillis(), dayOfYear)); 1421 } 1422 1423 /** 1424 * Returns a copy of this datetime with the day of month field updated. 1425 * <p> 1426 * DateTime is immutable, so there are no set methods. 1427 * Instead, this method returns a new instance with the value of 1428 * day of month changed. 1429 * 1430 * @param dayOfMonth the day of month to set 1431 * @return a copy of this object with the field set 1432 * @throws IllegalArgumentException if the value is invalid 1433 * @since 1.3 1434 */ 1435 public DateTime withDayOfMonth(int dayOfMonth) { 1436 return withMillis(getChronology().dayOfMonth().set(getMillis(), dayOfMonth)); 1437 } 1438 1439 /** 1440 * Returns a copy of this datetime with the day of week field updated. 1441 * <p> 1442 * DateTime is immutable, so there are no set methods. 1443 * Instead, this method returns a new instance with the value of 1444 * day of week changed. 1445 * 1446 * @param dayOfWeek the day of week to set 1447 * @return a copy of this object with the field set 1448 * @throws IllegalArgumentException if the value is invalid 1449 * @since 1.3 1450 */ 1451 public DateTime withDayOfWeek(int dayOfWeek) { 1452 return withMillis(getChronology().dayOfWeek().set(getMillis(), dayOfWeek)); 1453 } 1454 1455 //----------------------------------------------------------------------- 1456 /** 1457 * Returns a copy of this datetime with the hour of day field updated. 1458 * <p> 1459 * DateTime is immutable, so there are no set methods. 1460 * Instead, this method returns a new instance with the value of 1461 * hour of day changed. 1462 * 1463 * @param hour the hour of day to set 1464 * @return a copy of this object with the field set 1465 * @throws IllegalArgumentException if the value is invalid 1466 * @since 1.3 1467 */ 1468 public DateTime withHourOfDay(int hour) { 1469 return withMillis(getChronology().hourOfDay().set(getMillis(), hour)); 1470 } 1471 1472 /** 1473 * Returns a copy of this datetime with the minute of hour updated. 1474 * <p> 1475 * DateTime is immutable, so there are no set methods. 1476 * Instead, this method returns a new instance with the value of 1477 * minute of hour changed. 1478 * 1479 * @param minute the minute of hour to set 1480 * @return a copy of this object with the field set 1481 * @throws IllegalArgumentException if the value is invalid 1482 * @since 1.3 1483 */ 1484 public DateTime withMinuteOfHour(int minute) { 1485 return withMillis(getChronology().minuteOfHour().set(getMillis(), minute)); 1486 } 1487 1488 /** 1489 * Returns a copy of this datetime with the second of minute field updated. 1490 * <p> 1491 * DateTime is immutable, so there are no set methods. 1492 * Instead, this method returns a new instance with the value of 1493 * second of minute changed. 1494 * 1495 * @param second the second of minute to set 1496 * @return a copy of this object with the field set 1497 * @throws IllegalArgumentException if the value is invalid 1498 * @since 1.3 1499 */ 1500 public DateTime withSecondOfMinute(int second) { 1501 return withMillis(getChronology().secondOfMinute().set(getMillis(), second)); 1502 } 1503 1504 /** 1505 * Returns a copy of this datetime with the millis of second field updated. 1506 * <p> 1507 * DateTime is immutable, so there are no set methods. 1508 * Instead, this method returns a new instance with the value of 1509 * millis of second changed. 1510 * 1511 * @param millis the millis of second to set 1512 * @return a copy of this object with the field set 1513 * @throws IllegalArgumentException if the value is invalid 1514 * @since 1.3 1515 */ 1516 public DateTime withMillisOfSecond(int millis) { 1517 return withMillis(getChronology().millisOfSecond().set(getMillis(), millis)); 1518 } 1519 1520 /** 1521 * Returns a copy of this datetime with the millis of day field updated. 1522 * <p> 1523 * DateTime is immutable, so there are no set methods. 1524 * Instead, this method returns a new instance with the value of 1525 * millis of day changed. 1526 * 1527 * @param millis the millis of day to set 1528 * @return a copy of this object with the field set 1529 * @throws IllegalArgumentException if the value is invalid 1530 * @since 1.3 1531 */ 1532 public DateTime withMillisOfDay(int millis) { 1533 return withMillis(getChronology().millisOfDay().set(getMillis(), millis)); 1534 } 1535 1536 // Date properties 1537 //----------------------------------------------------------------------- 1538 /** 1539 * Get the era property which provides access to advanced functionality. 1540 * 1541 * @return the era property 1542 */ 1543 public Property era() { 1544 return new Property(this, getChronology().era()); 1545 } 1546 1547 /** 1548 * Get the century of era property which provides access to advanced functionality. 1549 * 1550 * @return the year of era property 1551 */ 1552 public Property centuryOfEra() { 1553 return new Property(this, getChronology().centuryOfEra()); 1554 } 1555 1556 /** 1557 * Get the year of century property which provides access to advanced functionality. 1558 * 1559 * @return the year of era property 1560 */ 1561 public Property yearOfCentury() { 1562 return new Property(this, getChronology().yearOfCentury()); 1563 } 1564 1565 /** 1566 * Get the year of era property which provides access to advanced functionality. 1567 * 1568 * @return the year of era property 1569 */ 1570 public Property yearOfEra() { 1571 return new Property(this, getChronology().yearOfEra()); 1572 } 1573 1574 /** 1575 * Get the year property which provides access to advanced functionality. 1576 * 1577 * @return the year property 1578 */ 1579 public Property year() { 1580 return new Property(this, getChronology().year()); 1581 } 1582 1583 /** 1584 * Get the year of a week based year property which provides access to advanced functionality. 1585 * 1586 * @return the year of a week based year property 1587 */ 1588 public Property weekyear() { 1589 return new Property(this, getChronology().weekyear()); 1590 } 1591 1592 /** 1593 * Get the month of year property which provides access to advanced functionality. 1594 * 1595 * @return the month of year property 1596 */ 1597 public Property monthOfYear() { 1598 return new Property(this, getChronology().monthOfYear()); 1599 } 1600 1601 /** 1602 * Get the week of a week based year property which provides access to advanced functionality. 1603 * 1604 * @return the week of a week based year property 1605 */ 1606 public Property weekOfWeekyear() { 1607 return new Property(this, getChronology().weekOfWeekyear()); 1608 } 1609 1610 /** 1611 * Get the day of year property which provides access to advanced functionality. 1612 * 1613 * @return the day of year property 1614 */ 1615 public Property dayOfYear() { 1616 return new Property(this, getChronology().dayOfYear()); 1617 } 1618 1619 /** 1620 * Get the day of month property which provides access to advanced functionality. 1621 * 1622 * @return the day of month property 1623 */ 1624 public Property dayOfMonth() { 1625 return new Property(this, getChronology().dayOfMonth()); 1626 } 1627 1628 /** 1629 * Get the day of week property which provides access to advanced functionality. 1630 * 1631 * @return the day of week property 1632 */ 1633 public Property dayOfWeek() { 1634 return new Property(this, getChronology().dayOfWeek()); 1635 } 1636 1637 // Time properties 1638 //----------------------------------------------------------------------- 1639 /** 1640 * Get the hour of day field property which provides access to advanced functionality. 1641 * 1642 * @return the hour of day property 1643 */ 1644 public Property hourOfDay() { 1645 return new Property(this, getChronology().hourOfDay()); 1646 } 1647 1648 /** 1649 * Get the minute of day property which provides access to advanced functionality. 1650 * 1651 * @return the minute of day property 1652 */ 1653 public Property minuteOfDay() { 1654 return new Property(this, getChronology().minuteOfDay()); 1655 } 1656 1657 /** 1658 * Get the minute of hour field property which provides access to advanced functionality. 1659 * 1660 * @return the minute of hour property 1661 */ 1662 public Property minuteOfHour() { 1663 return new Property(this, getChronology().minuteOfHour()); 1664 } 1665 1666 /** 1667 * Get the second of day property which provides access to advanced functionality. 1668 * 1669 * @return the second of day property 1670 */ 1671 public Property secondOfDay() { 1672 return new Property(this, getChronology().secondOfDay()); 1673 } 1674 1675 /** 1676 * Get the second of minute field property which provides access to advanced functionality. 1677 * 1678 * @return the second of minute property 1679 */ 1680 public Property secondOfMinute() { 1681 return new Property(this, getChronology().secondOfMinute()); 1682 } 1683 1684 /** 1685 * Get the millis of day property which provides access to advanced functionality. 1686 * 1687 * @return the millis of day property 1688 */ 1689 public Property millisOfDay() { 1690 return new Property(this, getChronology().millisOfDay()); 1691 } 1692 1693 /** 1694 * Get the millis of second property which provides access to advanced functionality. 1695 * 1696 * @return the millis of second property 1697 */ 1698 public Property millisOfSecond() { 1699 return new Property(this, getChronology().millisOfSecond()); 1700 } 1701 1702 //----------------------------------------------------------------------- 1703 /** 1704 * DateTime.Property binds a DateTime to a DateTimeField allowing powerful 1705 * datetime functionality to be easily accessed. 1706 * <p> 1707 * The simplest use of this class is as an alternative get method, here used to 1708 * get the year '1972' (as an int) and the month 'December' (as a String). 1709 * <pre> 1710 * DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0); 1711 * int year = dt.year().get(); 1712 * String monthStr = dt.month().getAsText(); 1713 * </pre> 1714 * <p> 1715 * Methods are also provided that allow date modification. These return new instances 1716 * of DateTime - they do not modify the original. The example below yields two 1717 * independent immutable date objects 20 years apart. 1718 * <pre> 1719 * DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0); 1720 * DateTime dt20 = dt.year().addToCopy(20); 1721 * </pre> 1722 * Serious modification of dates (ie. more than just changing one or two fields) 1723 * should use the {@link org.joda.time.MutableDateTime MutableDateTime} class. 1724 * <p> 1725 * DateTime.Propery itself is thread-safe and immutable, as well as the 1726 * DateTime being operated on. 1727 * 1728 * @author Stephen Colebourne 1729 * @author Brian S O'Neill 1730 * @since 1.0 1731 */ 1732 public static final class Property extends AbstractReadableInstantFieldProperty { 1733 1734 /** Serialization version */ 1735 private static final long serialVersionUID = -6983323811635733510L; 1736 1737 /** The instant this property is working against */ 1738 private DateTime iInstant; 1739 /** The field this property is working against */ 1740 private DateTimeField iField; 1741 1742 /** 1743 * Constructor. 1744 * 1745 * @param instant the instant to set 1746 * @param field the field to use 1747 */ 1748 Property(DateTime instant, DateTimeField field) { 1749 super(); 1750 iInstant = instant; 1751 iField = field; 1752 } 1753 1754 /** 1755 * Writes the property in a safe serialization format. 1756 */ 1757 private void writeObject(ObjectOutputStream oos) throws IOException { 1758 oos.writeObject(iInstant); 1759 oos.writeObject(iField.getType()); 1760 } 1761 1762 /** 1763 * Reads the property from a safe serialization format. 1764 */ 1765 private void readObject(ObjectInputStream oos) throws IOException, ClassNotFoundException { 1766 iInstant = (DateTime) oos.readObject(); 1767 DateTimeFieldType type = (DateTimeFieldType) oos.readObject(); 1768 iField = type.getField(iInstant.getChronology()); 1769 } 1770 1771 //----------------------------------------------------------------------- 1772 /** 1773 * Gets the field being used. 1774 * 1775 * @return the field 1776 */ 1777 public DateTimeField getField() { 1778 return iField; 1779 } 1780 1781 /** 1782 * Gets the milliseconds of the datetime that this property is linked to. 1783 * 1784 * @return the milliseconds 1785 */ 1786 protected long getMillis() { 1787 return iInstant.getMillis(); 1788 } 1789 1790 /** 1791 * Gets the chronology of the datetime that this property is linked to. 1792 * 1793 * @return the chronology 1794 * @since 1.4 1795 */ 1796 protected Chronology getChronology() { 1797 return iInstant.getChronology(); 1798 } 1799 1800 /** 1801 * Gets the datetime being used. 1802 * 1803 * @return the datetime 1804 */ 1805 public DateTime getDateTime() { 1806 return iInstant; 1807 } 1808 1809 //----------------------------------------------------------------------- 1810 /** 1811 * Adds to this field in a copy of this DateTime. 1812 * <p> 1813 * The DateTime attached to this property is unchanged by this call. 1814 * This operation is faster than converting a DateTime to a MutableDateTime 1815 * and back again when setting one field. When setting multiple fields, 1816 * it is generally quicker to make the conversion to MutableDateTime. 1817 * 1818 * @param value the value to add to the field in the copy 1819 * @return a copy of the DateTime with the field value changed 1820 * @throws IllegalArgumentException if the value isn't valid 1821 */ 1822 public DateTime addToCopy(int value) { 1823 return iInstant.withMillis(iField.add(iInstant.getMillis(), value)); 1824 } 1825 1826 /** 1827 * Adds to this field in a copy of this DateTime. 1828 * <p> 1829 * The DateTime attached to this property is unchanged by this call. 1830 * This operation is faster than converting a DateTime to a MutableDateTime 1831 * and back again when setting one field. When setting multiple fields, 1832 * it is generally quicker to make the conversion to MutableDateTime. 1833 * 1834 * @param value the value to add to the field in the copy 1835 * @return a copy of the DateTime with the field value changed 1836 * @throws IllegalArgumentException if the value isn't valid 1837 */ 1838 public DateTime addToCopy(long value) { 1839 return iInstant.withMillis(iField.add(iInstant.getMillis(), value)); 1840 } 1841 1842 /** 1843 * Adds to this field, possibly wrapped, in a copy of this DateTime. 1844 * A wrapped operation only changes this field. 1845 * Thus 31st January addWrapField one day goes to the 1st January. 1846 * <p> 1847 * The DateTime attached to this property is unchanged by this call. 1848 * This operation is faster than converting a DateTime to a MutableDateTime 1849 * and back again when setting one field. When setting multiple fields, 1850 * it is generally quicker to make the conversion to MutableDateTime. 1851 * 1852 * @param value the value to add to the field in the copy 1853 * @return a copy of the DateTime with the field value changed 1854 * @throws IllegalArgumentException if the value isn't valid 1855 */ 1856 public DateTime addWrapFieldToCopy(int value) { 1857 return iInstant.withMillis(iField.addWrapField(iInstant.getMillis(), value)); 1858 } 1859 1860 //----------------------------------------------------------------------- 1861 /** 1862 * Sets this field in a copy of the DateTime. 1863 * <p> 1864 * The DateTime attached to this property is unchanged by this call. 1865 * This operation is faster than converting a DateTime to a MutableDateTime 1866 * and back again when setting one field. When setting multiple fields, 1867 * it is generally quicker to make the conversion to MutableDateTime. 1868 * 1869 * @param value the value to set the field in the copy to 1870 * @return a copy of the DateTime with the field value changed 1871 * @throws IllegalArgumentException if the value isn't valid 1872 */ 1873 public DateTime setCopy(int value) { 1874 return iInstant.withMillis(iField.set(iInstant.getMillis(), value)); 1875 } 1876 1877 /** 1878 * Sets this field in a copy of the DateTime to a parsed text value. 1879 * <p> 1880 * The DateTime attached to this property is unchanged by this call. 1881 * This operation is faster than converting a DateTime to a MutableDateTime 1882 * and back again when setting one field. When setting multiple fields, 1883 * it is generally quicker to make the conversion to MutableDateTime. 1884 * 1885 * @param text the text value to set 1886 * @param locale optional locale to use for selecting a text symbol 1887 * @return a copy of the DateTime with the field value changed 1888 * @throws IllegalArgumentException if the text value isn't valid 1889 */ 1890 public DateTime setCopy(String text, Locale locale) { 1891 return iInstant.withMillis(iField.set(iInstant.getMillis(), text, locale)); 1892 } 1893 1894 /** 1895 * Sets this field in a copy of the DateTime to a parsed text value. 1896 * <p> 1897 * The DateTime attached to this property is unchanged by this call. 1898 * This operation is faster than converting a DateTime to a MutableDateTime 1899 * and back again when setting one field. When setting multiple fields, 1900 * it is generally quicker to make the conversion to MutableDateTime. 1901 * 1902 * @param text the text value to set 1903 * @return a copy of the DateTime with the field value changed 1904 * @throws IllegalArgumentException if the text value isn't valid 1905 */ 1906 public DateTime setCopy(String text) { 1907 return setCopy(text, null); 1908 } 1909 1910 //----------------------------------------------------------------------- 1911 /** 1912 * Returns a new DateTime with this field set to the maximum value 1913 * for this field. 1914 * <p> 1915 * This operation is useful for obtaining a DateTime on the last day 1916 * of the month, as month lengths vary. 1917 * <pre> 1918 * DateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue(); 1919 * </pre> 1920 * <p> 1921 * The DateTime attached to this property is unchanged by this call. 1922 * 1923 * @return a copy of the DateTime with this field set to its maximum 1924 * @since 1.2 1925 */ 1926 public DateTime withMaximumValue() { 1927 return setCopy(getMaximumValue()); 1928 } 1929 1930 /** 1931 * Returns a new DateTime with this field set to the minimum value 1932 * for this field. 1933 * <p> 1934 * The DateTime attached to this property is unchanged by this call. 1935 * 1936 * @return a copy of the DateTime with this field set to its minimum 1937 * @since 1.2 1938 */ 1939 public DateTime withMinimumValue() { 1940 return setCopy(getMinimumValue()); 1941 } 1942 1943 //----------------------------------------------------------------------- 1944 /** 1945 * Rounds to the lowest whole unit of this field on a copy of this DateTime. 1946 * 1947 * @return a copy of the DateTime with the field value changed 1948 */ 1949 public DateTime roundFloorCopy() { 1950 return iInstant.withMillis(iField.roundFloor(iInstant.getMillis())); 1951 } 1952 1953 /** 1954 * Rounds to the highest whole unit of this field on a copy of this DateTime. 1955 * 1956 * @return a copy of the DateTime with the field value changed 1957 */ 1958 public DateTime roundCeilingCopy() { 1959 return iInstant.withMillis(iField.roundCeiling(iInstant.getMillis())); 1960 } 1961 1962 /** 1963 * Rounds to the nearest whole unit of this field on a copy of this DateTime, 1964 * favoring the floor if halfway. 1965 * 1966 * @return a copy of the DateTime with the field value changed 1967 */ 1968 public DateTime roundHalfFloorCopy() { 1969 return iInstant.withMillis(iField.roundHalfFloor(iInstant.getMillis())); 1970 } 1971 1972 /** 1973 * Rounds to the nearest whole unit of this field on a copy of this DateTime, 1974 * favoring the ceiling if halfway. 1975 * 1976 * @return a copy of the DateTime with the field value changed 1977 */ 1978 public DateTime roundHalfCeilingCopy() { 1979 return iInstant.withMillis(iField.roundHalfCeiling(iInstant.getMillis())); 1980 } 1981 1982 /** 1983 * Rounds to the nearest whole unit of this field on a copy of this 1984 * DateTime. If halfway, the ceiling is favored over the floor only if 1985 * it makes this field's value even. 1986 * 1987 * @return a copy of the DateTime with the field value changed 1988 */ 1989 public DateTime roundHalfEvenCopy() { 1990 return iInstant.withMillis(iField.roundHalfEven(iInstant.getMillis())); 1991 } 1992 } 1993 1994}