117 * system, in which today's rules for leap years are applied for all time. |
117 * system, in which today's rules for leap years are applied for all time. |
118 * For most applications written today, the ISO-8601 rules are entirely suitable. |
118 * For most applications written today, the ISO-8601 rules are entirely suitable. |
119 * However, any application that makes use of historical dates, and requires them |
119 * However, any application that makes use of historical dates, and requires them |
120 * to be accurate will find the ISO-8601 approach unsuitable. |
120 * to be accurate will find the ISO-8601 approach unsuitable. |
121 * |
121 * |
122 * <h3>Specification for implementors</h3> |
122 * @implSpec |
123 * This class is immutable and thread-safe. |
123 * This class is immutable and thread-safe. |
124 * |
124 * |
125 * @since 1.8 |
125 * @since 1.8 |
126 */ |
126 */ |
127 public final class LocalDateTime |
127 public final class LocalDateTime |
1560 public Temporal adjustInto(Temporal temporal) { |
1560 public Temporal adjustInto(Temporal temporal) { |
1561 return ChronoLocalDateTime.super.adjustInto(temporal); |
1561 return ChronoLocalDateTime.super.adjustInto(temporal); |
1562 } |
1562 } |
1563 |
1563 |
1564 /** |
1564 /** |
1565 * Calculates the period between this date-time and another date-time in |
1565 * Calculates the amount of time until another date-time in terms of the specified unit. |
1566 * terms of the specified unit. |
1566 * <p> |
1567 * <p> |
1567 * This calculates the amount of time between two {@code LocalDateTime} |
1568 * This calculates the period between two date-times in terms of a single unit. |
1568 * objects in terms of a single {@code TemporalUnit}. |
1569 * The start and end points are {@code this} and the specified date-time. |
1569 * The start and end points are {@code this} and the specified date-time. |
1570 * The result will be negative if the end is before the start. |
1570 * The result will be negative if the end is before the start. |
1571 * The {@code Temporal} passed to this method must be a {@code LocalDateTime}. |
1571 * The {@code Temporal} passed to this method must be a {@code LocalDateTime}. |
1572 * For example, the period in days between two date-times can be calculated |
1572 * For example, the amount in days between two date-times can be calculated |
1573 * using {@code startDateTime.periodUntil(endDateTime, DAYS)}. |
1573 * using {@code startDateTime.periodUntil(endDateTime, DAYS)}. |
1574 * <p> |
1574 * <p> |
1575 * The calculation returns a whole number, representing the number of |
1575 * The calculation returns a whole number, representing the number of |
1576 * complete units between the two date-times. |
1576 * complete units between the two date-times. |
1577 * For example, the period in months between 2012-06-15T00:00 and 2012-08-14T23:59 |
1577 * For example, the amount in months between 2012-06-15T00:00 and 2012-08-14T23:59 |
1578 * will only be one month as it is one minute short of two months. |
1578 * will only be one month as it is one minute short of two months. |
1579 * <p> |
1579 * <p> |
1580 * There are two equivalent ways of using this method. |
1580 * There are two equivalent ways of using this method. |
1581 * The first is to invoke this method. |
1581 * The first is to invoke this method. |
1582 * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}: |
1582 * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}: |
1600 * the second argument. |
1600 * the second argument. |
1601 * <p> |
1601 * <p> |
1602 * This instance is immutable and unaffected by this method call. |
1602 * This instance is immutable and unaffected by this method call. |
1603 * |
1603 * |
1604 * @param endDateTime the end date-time, which must be a {@code LocalDateTime}, not null |
1604 * @param endDateTime the end date-time, which must be a {@code LocalDateTime}, not null |
1605 * @param unit the unit to measure the period in, not null |
1605 * @param unit the unit to measure the amount in, not null |
1606 * @return the amount of the period between this date-time and the end date-time |
1606 * @return the amount of time between this date-time and the end date-time |
1607 * @throws DateTimeException if the period cannot be calculated |
1607 * @throws DateTimeException if the amount cannot be calculated |
1608 * @throws UnsupportedTemporalTypeException if the unit is not supported |
1608 * @throws UnsupportedTemporalTypeException if the unit is not supported |
1609 * @throws ArithmeticException if numeric overflow occurs |
1609 * @throws ArithmeticException if numeric overflow occurs |
1610 */ |
1610 */ |
1611 @Override |
1611 @Override |
1612 public long periodUntil(Temporal endDateTime, TemporalUnit unit) { |
1612 public long periodUntil(Temporal endDateTime, TemporalUnit unit) { |
1613 if (endDateTime instanceof LocalDateTime == false) { |
1613 if (endDateTime instanceof LocalDateTime == false) { |
1614 Objects.requireNonNull(endDateTime, "endDateTime"); |
1614 Objects.requireNonNull(endDateTime, "endDateTime"); |
1615 throw new DateTimeException("Unable to calculate period between objects of two different types"); |
1615 throw new DateTimeException("Unable to calculate amount as objects are of two different types"); |
1616 } |
1616 } |
1617 LocalDateTime end = (LocalDateTime) endDateTime; |
1617 LocalDateTime end = (LocalDateTime) endDateTime; |
1618 if (unit instanceof ChronoUnit) { |
1618 if (unit instanceof ChronoUnit) { |
1619 ChronoUnit f = (ChronoUnit) unit; |
1619 ChronoUnit f = (ChronoUnit) unit; |
1620 if (f.isTimeUnit()) { |
1620 if (f.isTimeUnit()) { |