jdk-sandbox: comparison jdk/src/share/classes/java/time/LocalDateTime.java

equal deleted inserted replaced

-:c588664d547e
+:55b829ca2334
 import static java.time.LocalTime.NANOS_PER_DAY;
 import static java.time.LocalTime.NANOS_PER_HOUR;
 import static java.time.LocalTime.NANOS_PER_MINUTE;
 import static java.time.LocalTime.NANOS_PER_SECOND;
 import static java.time.LocalTime.SECONDS_PER_DAY;
+import static java.time.temporal.ChronoField.NANO_OF_SECOND;
 import java.io.DataInput;
 import java.io.DataOutput;
 import java.io.IOException;
 import java.io.InvalidObjectException;
 import java.io.ObjectStreamException;
 import java.io.Serializable;
+import java.time.chrono.ChronoLocalDateTime;
+import java.time.chrono.IsoChronology;
 import java.time.format.DateTimeFormatter;
-import java.time.format.DateTimeFormatters;
 import java.time.format.DateTimeParseException;
 import java.time.temporal.ChronoField;
-import java.time.temporal.ChronoLocalDateTime;
 import java.time.temporal.ChronoUnit;
-import java.time.temporal.ISOChrono;
+import java.time.temporal.Queries;
-import java.time.temporal.OffsetDateTime;
 import java.time.temporal.Temporal;
 import java.time.temporal.TemporalAccessor;
-import java.time.temporal.TemporalAdder;
 import java.time.temporal.TemporalAdjuster;
+import java.time.temporal.TemporalAmount;
 import java.time.temporal.TemporalField;
 import java.time.temporal.TemporalQuery;
-import java.time.temporal.TemporalSubtractor;
 import java.time.temporal.TemporalUnit;
 import java.time.temporal.ValueRange;
 import java.time.zone.ZoneRules;
 import java.util.Objects;
 * This class is immutable and thread-safe.
 *
 * @since 1.8
 */
 public final class LocalDateTime
-implements Temporal, TemporalAdjuster, ChronoLocalDateTime<ISOChrono>, Serializable {
+implements Temporal, TemporalAdjuster, ChronoLocalDateTime<LocalDate>, Serializable {
 /**
 * The minimum supported {@code LocalDateTime}, '-999999999-01-01T00:00:00'.
 * This is the local date-time of midnight at the start of the minimum date.
 * This combines {@link LocalDate#MIN} and {@link LocalTime#MIN}.
 //-----------------------------------------------------------------------
 /**
 * Obtains an instance of {@code LocalDateTime} from year, month,
 * day, hour and minute, setting the second and nanosecond to zero.
 * <p>
+* This returns a {@code LocalDateTime} with the specified year, month,
+* day-of-month, hour and minute.
 * The day must be valid for the year and month, otherwise an exception will be thrown.
 * The second and nanosecond fields will be set to zero.
 *
 * @param year  the year to represent, from MIN_YEAR to MAX_YEAR
 * @param month  the month-of-year to represent, not null
 * @param dayOfMonth  the day-of-month to represent, from 1 to 31
 * @param hour  the hour-of-day to represent, from 0 to 23
 * @param minute  the minute-of-hour to represent, from 0 to 59
 * @return the local date-time, not null
-* @throws DateTimeException if the value of any field is out of range
+* @throws DateTimeException if the value of any field is out of range,
-* @throws DateTimeException if the day-of-month is invalid for the month-year
+*  or if the day-of-month is invalid for the month-year
 */
 public static LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute) {
 LocalDate date = LocalDate.of(year, month, dayOfMonth);
 LocalTime time = LocalTime.of(hour, minute);
 return new LocalDateTime(date, time);
 /**
 * Obtains an instance of {@code LocalDateTime} from year, month,
 * day, hour, minute and second, setting the nanosecond to zero.
 * <p>
+* This returns a {@code LocalDateTime} with the specified year, month,
+* day-of-month, hour, minute and second.
 * The day must be valid for the year and month, otherwise an exception will be thrown.
 * The nanosecond field will be set to zero.
 *
 * @param year  the year to represent, from MIN_YEAR to MAX_YEAR
 * @param month  the month-of-year to represent, not null
 * @param dayOfMonth  the day-of-month to represent, from 1 to 31
 * @param hour  the hour-of-day to represent, from 0 to 23
 * @param minute  the minute-of-hour to represent, from 0 to 59
 * @param second  the second-of-minute to represent, from 0 to 59
 * @return the local date-time, not null
-* @throws DateTimeException if the value of any field is out of range
+* @throws DateTimeException if the value of any field is out of range,
-* @throws DateTimeException if the day-of-month is invalid for the month-year
+*  or if the day-of-month is invalid for the month-year
 */
 public static LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second) {
 LocalDate date = LocalDate.of(year, month, dayOfMonth);
 LocalTime time = LocalTime.of(hour, minute, second);
 return new LocalDateTime(date, time);
 /**
 * Obtains an instance of {@code LocalDateTime} from year, month,
 * day, hour, minute, second and nanosecond.
 * <p>
+* This returns a {@code LocalDateTime} with the specified year, month,
+* day-of-month, hour, minute, second and nanosecond.
 * The day must be valid for the year and month, otherwise an exception will be thrown.
 *
 * @param year  the year to represent, from MIN_YEAR to MAX_YEAR
 * @param month  the month-of-year to represent, not null
 * @param dayOfMonth  the day-of-month to represent, from 1 to 31
 * @param hour  the hour-of-day to represent, from 0 to 23
 * @param minute  the minute-of-hour to represent, from 0 to 59
 * @param second  the second-of-minute to represent, from 0 to 59
 * @param nanoOfSecond  the nano-of-second to represent, from 0 to 999,999,999
 * @return the local date-time, not null
-* @throws DateTimeException if the value of any field is out of range
+* @throws DateTimeException if the value of any field is out of range,
-* @throws DateTimeException if the day-of-month is invalid for the month-year
+*  or if the day-of-month is invalid for the month-year
 */
 public static LocalDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond) {
 LocalDate date = LocalDate.of(year, month, dayOfMonth);
 LocalTime time = LocalTime.of(hour, minute, second, nanoOfSecond);
 return new LocalDateTime(date, time);
 //-----------------------------------------------------------------------
 /**
 * Obtains an instance of {@code LocalDateTime} from year, month,
 * day, hour and minute, setting the second and nanosecond to zero.
 * <p>
+* This returns a {@code LocalDateTime} with the specified year, month,
+* day-of-month, hour and minute.
 * The day must be valid for the year and month, otherwise an exception will be thrown.
 * The second and nanosecond fields will be set to zero.
 *
 * @param year  the year to represent, from MIN_YEAR to MAX_YEAR
 * @param month  the month-of-year to represent, from 1 (January) to 12 (December)
 * @param dayOfMonth  the day-of-month to represent, from 1 to 31
 * @param hour  the hour-of-day to represent, from 0 to 23
 * @param minute  the minute-of-hour to represent, from 0 to 59
 * @return the local date-time, not null
-* @throws DateTimeException if the value of any field is out of range
+* @throws DateTimeException if the value of any field is out of range,
-* @throws DateTimeException if the day-of-month is invalid for the month-year
+*  or if the day-of-month is invalid for the month-year
 */
 public static LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute) {
 LocalDate date = LocalDate.of(year, month, dayOfMonth);
 LocalTime time = LocalTime.of(hour, minute);
 return new LocalDateTime(date, time);
 /**
 * Obtains an instance of {@code LocalDateTime} from year, month,
 * day, hour, minute and second, setting the nanosecond to zero.
 * <p>
+* This returns a {@code LocalDateTime} with the specified year, month,
+* day-of-month, hour, minute and second.
 * The day must be valid for the year and month, otherwise an exception will be thrown.
 * The nanosecond field will be set to zero.
 *
 * @param year  the year to represent, from MIN_YEAR to MAX_YEAR
 * @param month  the month-of-year to represent, from 1 (January) to 12 (December)
 * @param dayOfMonth  the day-of-month to represent, from 1 to 31
 * @param hour  the hour-of-day to represent, from 0 to 23
 * @param minute  the minute-of-hour to represent, from 0 to 59
 * @param second  the second-of-minute to represent, from 0 to 59
 * @return the local date-time, not null
-* @throws DateTimeException if the value of any field is out of range
+* @throws DateTimeException if the value of any field is out of range,
-* @throws DateTimeException if the day-of-month is invalid for the month-year
+*  or if the day-of-month is invalid for the month-year
 */
 public static LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second) {
 LocalDate date = LocalDate.of(year, month, dayOfMonth);
 LocalTime time = LocalTime.of(hour, minute, second);
 return new LocalDateTime(date, time);
 /**
 * Obtains an instance of {@code LocalDateTime} from year, month,
 * day, hour, minute, second and nanosecond.
 * <p>
+* This returns a {@code LocalDateTime} with the specified year, month,
+* day-of-month, hour, minute, second and nanosecond.
 * The day must be valid for the year and month, otherwise an exception will be thrown.
 *
 * @param year  the year to represent, from MIN_YEAR to MAX_YEAR
 * @param month  the month-of-year to represent, from 1 (January) to 12 (December)
 * @param dayOfMonth  the day-of-month to represent, from 1 to 31
 * @param hour  the hour-of-day to represent, from 0 to 23
 * @param minute  the minute-of-hour to represent, from 0 to 59
 * @param second  the second-of-minute to represent, from 0 to 59
 * @param nanoOfSecond  the nano-of-second to represent, from 0 to 999,999,999
 * @return the local date-time, not null
-* @throws DateTimeException if the value of any field is out of range
+* @throws DateTimeException if the value of any field is out of range,
-* @throws DateTimeException if the day-of-month is invalid for the month-year
+*  or if the day-of-month is invalid for the month-year
 */
 public static LocalDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond) {
 LocalDate date = LocalDate.of(year, month, dayOfMonth);
 LocalTime time = LocalTime.of(hour, minute, second, nanoOfSecond);
 return new LocalDateTime(date, time);
 *
 * @param epochSecond  the number of seconds from the epoch of 1970-01-01T00:00:00Z
 * @param nanoOfSecond  the nanosecond within the second, from 0 to 999,999,999
 * @param offset  the zone offset, not null
 * @return the local date-time, not null
-* @throws DateTimeException if the result exceeds the supported range
+* @throws DateTimeException if the result exceeds the supported range,
+*  or if the nano-of-second is invalid
 */
 public static LocalDateTime ofEpochSecond(long epochSecond, int nanoOfSecond, ZoneOffset offset) {
 Objects.requireNonNull(offset, "offset");
+NANO_OF_SECOND.checkValidValue(nanoOfSecond);
 long localSecond = epochSecond + offset.getTotalSeconds();  // overflow caught later
 long localEpochDay = Math.floorDiv(localSecond, SECONDS_PER_DAY);
 int secsOfDay = (int)Math.floorMod(localSecond, SECONDS_PER_DAY);
 LocalDate date = LocalDate.ofEpochDay(localEpochDay);
-LocalTime time = LocalTime.ofSecondOfDay(secsOfDay, nanoOfSecond);
+LocalTime time = LocalTime.ofNanoOfDay(secsOfDay * NANOS_PER_SECOND + nanoOfSecond);
 return new LocalDateTime(date, time);
 }
 //-----------------------------------------------------------------------
 /**
 * Obtains an instance of {@code LocalDateTime} from a temporal object.
 * <p>
-* A {@code TemporalAccessor} represents some form of date and time information.
+* This obtains an offset time based on the specified temporal.
-* This factory converts the arbitrary temporal object to an instance of {@code LocalDateTime}.
+* A {@code TemporalAccessor} represents an arbitrary set of date and time information,
-* <p>
+* which this factory converts to an instance of {@code LocalDateTime}.
-* The conversion extracts and combines {@code LocalDate} and {@code LocalTime}.
+* <p>
+* The conversion extracts and combines the {@code LocalDate} and the
+* {@code LocalTime} from the temporal object.
+* Implementations are permitted to perform optimizations such as accessing
+* those fields that are equivalent to the relevant objects.
 * <p>
 * This method matches the signature of the functional interface {@link TemporalQuery}
 * allowing it to be used as a query via method reference, {@code LocalDateTime::from}.
 *
 * @param temporal  the temporal object to convert, not null
 */
 public static LocalDateTime from(TemporalAccessor temporal) {
 if (temporal instanceof LocalDateTime) {
 return (LocalDateTime) temporal;
 } else if (temporal instanceof ZonedDateTime) {
-return ((ZonedDateTime) temporal).getDateTime();
+return ((ZonedDateTime) temporal).toLocalDateTime();
+} else if (temporal instanceof OffsetDateTime) {
+return ((OffsetDateTime) temporal).toLocalDateTime();
 }
 try {
 LocalDate date = LocalDate.from(temporal);
 LocalTime time = LocalTime.from(temporal);
 return new LocalDateTime(date, time);
 //-----------------------------------------------------------------------
 /**
 * Obtains an instance of {@code LocalDateTime} from a text string such as {@code 2007-12-03T10:15:30}.
 * <p>
 * The string must represent a valid date-time and is parsed using
-* {@link java.time.format.DateTimeFormatters#isoLocalDateTime()}.
+* {@link java.time.format.DateTimeFormatter#ISO_LOCAL_DATE_TIME}.
 *
 * @param text  the text to parse such as "2007-12-03T10:15:30", not null
 * @return the parsed local date-time, not null
 * @throws DateTimeParseException if the text cannot be parsed
 */
 public static LocalDateTime parse(CharSequence text) {
-return parse(text, DateTimeFormatters.isoLocalDateTime());
+return parse(text, DateTimeFormatter.ISO_LOCAL_DATE_TIME);
 }
 /**
 * Obtains an instance of {@code LocalDateTime} from a text string using a specific formatter.
 * <p>
 * <li>{@code ERA}
 * </ul>
 * All other {@code ChronoField} instances will return false.
 * <p>
 * If the field is not a {@code ChronoField}, then the result of this method
-* is obtained by invoking {@code TemporalField.doIsSupported(TemporalAccessor)}
+* is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)}
 * passing {@code this} as the argument.
 * Whether the field is supported is determined by the field.
 *
 * @param field  the field to check, null returns false
 * @return true if the field is supported on this date-time, false if not
 public boolean isSupported(TemporalField field) {
 if (field instanceof ChronoField) {
 ChronoField f = (ChronoField) field;
 return f.isDateField() || f.isTimeField();
 }
-return field != null && field.doIsSupported(this);
+return field != null && field.isSupportedBy(this);
 }
 /**
 * Gets the range of valid values for the specified field.
 * <p>
 * The {@link #isSupported(TemporalField) supported fields} will return
 * appropriate range instances.
 * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 * <p>
 * If the field is not a {@code ChronoField}, then the result of this method
-* is obtained by invoking {@code TemporalField.doRange(TemporalAccessor)}
+* is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)}
 * passing {@code this} as the argument.
 * Whether the range can be obtained is determined by the field.
 *
 * @param field  the field to query the range for, not null
 * @return the range of valid values for the field, not null
 public ValueRange range(TemporalField field) {
 if (field instanceof ChronoField) {
 ChronoField f = (ChronoField) field;
 return (f.isTimeField() ? time.range(field) : date.range(field));
 }
-return field.doRange(this);
+return field.rangeRefinedBy(this);
 }
 /**
 * Gets the value of the specified field from this date-time as an {@code int}.
 * <p>
 * {@code EPOCH_DAY} and {@code EPOCH_MONTH} which are too large to fit in
 * an {@code int} and throw a {@code DateTimeException}.
 * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 * <p>
 * If the field is not a {@code ChronoField}, then the result of this method
-* is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)}
+* is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}
 * passing {@code this} as the argument. Whether the value can be obtained,
 * and what the value represents, is determined by the field.
 *
 * @param field  the field to get, not null
 * @return the value for the field
 * The {@link #isSupported(TemporalField) supported fields} will return valid
 * values based on this date-time.
 * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 * <p>
 * If the field is not a {@code ChronoField}, then the result of this method
-* is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)}
+* is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}
 * passing {@code this} as the argument. Whether the value can be obtained,
 * and what the value represents, is determined by the field.
 *
 * @param field  the field to get, not null
 * @return the value for the field
 public long getLong(TemporalField field) {
 if (field instanceof ChronoField) {
 ChronoField f = (ChronoField) field;
 return (f.isTimeField() ? time.getLong(field) : date.getLong(field));
 }
-return field.doGet(this);
+return field.getFrom(this);
 }
 //-----------------------------------------------------------------------
 /**
 * Gets the {@code LocalDate} part of this date-time.
 * as this date-time.
 *
 * @return the date part of this date-time, not null
 */
 @Override
-public LocalDate getDate() {
+public LocalDate toLocalDate() {
 return date;
 }
 /**
 * Gets the year field.
 * <p>
 * This method returns the primitive {@code int} value for the year.
 * <p>
 * The year returned by this method is proleptic as per {@code get(YEAR)}.
-* To obtain the year-of-era, use {@code get(YEAR_OF_ERA}.
+* To obtain the year-of-era, use {@code get(YEAR_OF_ERA)}.
 *
 * @return the year, from MIN_YEAR to MAX_YEAR
 */
 public int getYear() {
 return date.getYear();
 * nanosecond as this date-time.
 *
 * @return the time part of this date-time, not null
 */
 @Override
-public LocalTime getTime() {
+public LocalTime toLocalTime() {
 return time;
 }
 /**
 * Gets the hour-of-day field.
 //-----------------------------------------------------------------------
 /**
 * Returns an adjusted copy of this date-time.
 * <p>
-* This returns a new {@code LocalDateTime}, based on this one, with the date-time adjusted.
+* This returns a {@code LocalDateTime}, based on this one, with the date-time adjusted.
 * The adjustment takes place using the specified adjuster strategy object.
 * Read the documentation of the adjuster to understand what adjustment will be made.
 * <p>
 * A simple adjuster might simply set the one of the fields, such as the year field.
 * A more complex adjuster might set the date to the last day of the month.
 * A selection of common adjustments is provided in {@link java.time.temporal.Adjusters}.
 * These include finding the "last day of the month" and "next Wednesday".
 * Key date-time classes also implement the {@code TemporalAdjuster} interface,
-* such as {@link Month} and {@link java.time.temporal.MonthDay MonthDay}.
+* such as {@link Month} and {@link java.time.MonthDay MonthDay}.
 * The adjuster is responsible for handling special cases, such as the varying
 * lengths of month and leap years.
 * <p>
 * For example this code returns a date on the last day of July:
 * <pre>
 }
 /**
 * Returns a copy of this date-time with the specified field set to a new value.
 * <p>
-* This returns a new {@code LocalDateTime}, based on this one, with the value
+* This returns a {@code LocalDateTime}, based on this one, with the value
 * for the specified field changed.
 * This can be used to change any supported field, such as the year, month or day-of-month.
 * If it is not possible to set the value, because the field is not supported or for
 * some other reason, an exception is thrown.
 * <p>
 * the matching method on {@link LocalDate#with(TemporalField, long) LocalDate}
 * or {@link LocalTime#with(TemporalField, long) LocalTime}.
 * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 * <p>
 * If the field is not a {@code ChronoField}, then the result of this method
-* is obtained by invoking {@code TemporalField.doWith(Temporal, long)}
+* is obtained by invoking {@code TemporalField.adjustInto(Temporal, long)}
 * passing {@code this} as the argument. In this case, the field determines
 * whether and how to adjust the instant.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 return with(date, time.with(field, newValue));
 } else {
 return with(date.with(field, newValue), time);
 }
 }
-return field.doWith(this, newValue);
+return field.adjustInto(this, newValue);
 }
 //-----------------------------------------------------------------------
 /**
 * Returns a copy of this {@code LocalDateTime} with the year altered.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param dayOfMonth  the day-of-month to set in the result, from 1 to 28-31
 * @return a {@code LocalDateTime} based on this date-time with the requested day, not null
-* @throws DateTimeException if the day-of-month value is invalid
+* @throws DateTimeException if the day-of-month value is invalid,
-* @throws DateTimeException if the day-of-month is invalid for the month-year
+*  or if the day-of-month is invalid for the month-year
 */
 public LocalDateTime withDayOfMonth(int dayOfMonth) {
 return with(date.withDayOfMonth(dayOfMonth), time);
 }
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param dayOfYear  the day-of-year to set in the result, from 1 to 365-366
 * @return a {@code LocalDateTime} based on this date with the requested day, not null
-* @throws DateTimeException if the day-of-year value is invalid
+* @throws DateTimeException if the day-of-year value is invalid,
-* @throws DateTimeException if the day-of-year is invalid for the year
+*  or if the day-of-year is invalid for the year
 */
 public LocalDateTime withDayOfYear(int dayOfYear) {
 return with(date.withDayOfYear(dayOfYear), time);
 }
 * Truncation returns a copy of the original date-time with fields
 * smaller than the specified unit set to zero.
 * For example, truncating with the {@link ChronoUnit#MINUTES minutes} unit
 * will set the second-of-minute and nano-of-second field to zero.
 * <p>
-* Not all units are accepted. The {@link ChronoUnit#DAYS days} unit and time
+* The unit must have a {@linkplain TemporalUnit#getDuration() duration}
-* units with an exact duration can be used, other units throw an exception.
+* that divides into the length of a standard day without remainder.
+* This includes all supplied time units on {@link ChronoUnit} and
+* {@link ChronoUnit#DAYS DAYS}. Other units throw an exception.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param unit  the unit to truncate to, not null
 * @return a {@code LocalDateTime} based on this date-time with the time truncated, not null
 return with(date, time.truncatedTo(unit));
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this date-time with the specified period added.
+* Returns a copy of this date-time with the specified amount added.
 * <p>
-* This method returns a new date-time based on this time with the specified period added.
+* This returns a {@code LocalDateTime}, based on this one, with the specified amount added.
-* The adder is typically {@link Period} but may be any other type implementing
+* The amount is typically {@link Period} or {@link Duration} but may be
-* the {@link TemporalAdder} interface.
+* any other type implementing the {@link TemporalAmount} interface.
-* The calculation is delegated to the specified adjuster, which typically calls
+* <p>
-* back to {@link #plus(long, TemporalUnit)}.
+* The calculation is delegated to the amount object by calling
-* <p>
+* {@link TemporalAmount#addTo(Temporal)}. The amount implementation is free
-* This instance is immutable and unaffected by this method call.
+* to implement the addition in any way it wishes, however it typically
-*
+* calls back to {@link #plus(long, TemporalUnit)}. Consult the documentation
-* @param adder  the adder to use, not null
+* of the amount implementation to determine if it can be successfully added.
+* <p>
+* This instance is immutable and unaffected by this method call.
+*
+* @param amountToAdd  the amount to add, not null
 * @return a {@code LocalDateTime} based on this date-time with the addition made, not null
 * @throws DateTimeException if the addition cannot be made
 * @throws ArithmeticException if numeric overflow occurs
 */
 @Override
-public LocalDateTime plus(TemporalAdder adder) {
+public LocalDateTime plus(TemporalAmount amountToAdd) {
-return (LocalDateTime) adder.addTo(this);
+return (LocalDateTime) amountToAdd.addTo(this);
 }
 /**
-* Returns a copy of this date-time with the specified period added.
+* Returns a copy of this date-time with the specified amount added.
 * <p>
-* This method returns a new date-time based on this date-time with the specified period added.
+* This returns a {@code LocalDateTime}, based on this one, with the amount
-* This can be used to add any period that is defined by a unit, for example to add years, months or days.
+* in terms of the unit added. If it is not possible to add the amount, because the
-* The unit is responsible for the details of the calculation, including the resolution
+* unit is not supported or for some other reason, an exception is thrown.
-* of any edge cases in the calculation.
+* <p>
+* If the field is a {@link ChronoUnit} then the addition is implemented here.
+* Date units are added as per {@link LocalDate#plus(long, TemporalUnit)}.
+* Time units are added as per {@link LocalTime#plus(long, TemporalUnit)} with
+* any overflow in days added equivalent to using {@link #plusDays(long)}.
+* <p>
+* If the field is not a {@code ChronoUnit}, then the result of this method
+* is obtained by invoking {@code TemporalUnit.addTo(Temporal, long)}
+* passing {@code this} as the argument. In this case, the unit determines
+* whether and how to perform the addition.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param amountToAdd  the amount of the unit to add to the result, may be negative
-* @param unit  the unit of the period to add, not null
+* @param unit  the unit of the amount to add, not null
-* @return a {@code LocalDateTime} based on this date-time with the specified period added, not null
+* @return a {@code LocalDateTime} based on this date-time with the specified amount added, not null
-* @throws DateTimeException if the unit cannot be added to this type
+* @throws DateTimeException if the addition cannot be made
+* @throws ArithmeticException if numeric overflow occurs
 */
 @Override
 public LocalDateTime plus(long amountToAdd, TemporalUnit unit) {
 if (unit instanceof ChronoUnit) {
 ChronoUnit f = (ChronoUnit) unit;
 case HOURS: return plusHours(amountToAdd);
 case HALF_DAYS: return plusDays(amountToAdd / 256).plusHours((amountToAdd % 256) * 12);  // no overflow (256 is multiple of 2)
 }
 return with(date.plus(amountToAdd, unit), time);
 }
-return unit.doPlus(this, amountToAdd);
+return unit.addTo(this, amountToAdd);
 }
 //-----------------------------------------------------------------------
 /**
 * Returns a copy of this {@code LocalDateTime} with the specified period in years added.
 return plusWithOverflow(date, 0, 0, 0, nanos, 1);
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this date-time with the specified period subtracted.
+* Returns a copy of this date-time with the specified amount subtracted.
 * <p>
-* This method returns a new date-time based on this time with the specified period subtracted.
+* This returns a {@code LocalDateTime}, based on this one, with the specified amount subtracted.
-* The subtractor is typically {@link Period} but may be any other type implementing
+* The amount is typically {@link Period} or {@link Duration} but may be
-* the {@link TemporalSubtractor} interface.
+* any other type implementing the {@link TemporalAmount} interface.
-* The calculation is delegated to the specified adjuster, which typically calls
+* <p>
-* back to {@link #minus(long, TemporalUnit)}.
+* The calculation is delegated to the amount object by calling
-* <p>
+* {@link TemporalAmount#subtractFrom(Temporal)}. The amount implementation is free
-* This instance is immutable and unaffected by this method call.
+* to implement the subtraction in any way it wishes, however it typically
-*
+* calls back to {@link #minus(long, TemporalUnit)}. Consult the documentation
-* @param subtractor  the subtractor to use, not null
+* of the amount implementation to determine if it can be successfully subtracted.
+* <p>
+* This instance is immutable and unaffected by this method call.
+*
+* @param amountToSubtract  the amount to subtract, not null
 * @return a {@code LocalDateTime} based on this date-time with the subtraction made, not null
 * @throws DateTimeException if the subtraction cannot be made
 * @throws ArithmeticException if numeric overflow occurs
 */
 @Override
-public LocalDateTime minus(TemporalSubtractor subtractor) {
+public LocalDateTime minus(TemporalAmount amountToSubtract) {
-return (LocalDateTime) subtractor.subtractFrom(this);
+return (LocalDateTime) amountToSubtract.subtractFrom(this);
 }
 /**
-* Returns a copy of this date-time with the specified period subtracted.
+* Returns a copy of this date-time with the specified amount subtracted.
 * <p>
-* This method returns a new date-time based on this date-time with the specified period subtracted.
+* This returns a {@code LocalDateTime}, based on this one, with the amount
-* This can be used to subtract any period that is defined by a unit, for example to subtract years, months or days.
+* in terms of the unit subtracted. If it is not possible to subtract the amount,
-* The unit is responsible for the details of the calculation, including the resolution
+* because the unit is not supported or for some other reason, an exception is thrown.
-* of any edge cases in the calculation.
+* <p>
+* This method is equivalent to {@link #plus(long, TemporalUnit)} with the amount negated.
+* See that method for a full description of how addition, and thus subtraction, works.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param amountToSubtract  the amount of the unit to subtract from the result, may be negative
-* @param unit  the unit of the period to subtract, not null
+* @param unit  the unit of the amount to subtract, not null
-* @return a {@code LocalDateTime} based on this date-time with the specified period subtracted, not null
+* @return a {@code LocalDateTime} based on this date-time with the specified amount subtracted, not null
-* @throws DateTimeException if the unit cannot be added to this type
+* @throws DateTimeException if the subtraction cannot be made
+* @throws ArithmeticException if numeric overflow occurs
 */
 @Override
 public LocalDateTime minus(long amountToSubtract, TemporalUnit unit) {
 return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
 }
 * @param query  the query to invoke, not null
 * @return the query result, null may be returned (defined by the query)
 * @throws DateTimeException if unable to query (defined by the query)
 * @throws ArithmeticException if numeric overflow occurs (defined by the query)
 */
+@SuppressWarnings("unchecked")
 @Override  // override for Javadoc
 public <R> R query(TemporalQuery<R> query) {
+if (query == Queries.localDate()) {
+return (R) date;
+}
 return ChronoLocalDateTime.super.query(query);
 }
 /**
 * Adjusts the specified temporal object to have the same date and time as this object.
 * The calculation returns a whole number, representing the number of
 * complete units between the two date-times.
 * For example, the period in months between 2012-06-15T00:00 and 2012-08-14T23:59
 * will only be one month as it is one minute short of two months.
 * <p>
-* This method operates in association with {@link TemporalUnit#between}.
+* There are two equivalent ways of using this method.
-* The result of this method is a {@code long} representing the amount of
+* The first is to invoke this method.
-* the specified unit. By contrast, the result of {@code between} is an
+* The second is to use {@link TemporalUnit#between(Temporal, Temporal)}:
-* object that can be used directly in addition/subtraction:
 * <pre>
-*   long period = start.periodUntil(end, MONTHS);   // this method
+*   // these two lines are equivalent
-*   dateTime.plus(MONTHS.between(start, end));      // use in plus/minus
+*   amount = start.periodUntil(end, MONTHS);
+*   amount = MONTHS.between(start, end);
 * </pre>
+* The choice should be made based on which makes the code more readable.
 * <p>
 * The calculation is implemented in this method for {@link ChronoUnit}.
 * The units {@code NANOS}, {@code MICROS}, {@code MILLIS}, {@code SECONDS},
 * {@code MINUTES}, {@code HOURS} and {@code HALF_DAYS}, {@code DAYS},
 * {@code WEEKS}, {@code MONTHS}, {@code YEARS}, {@code DECADES},
 if (end.time.isBefore(time)) {
 endDate = endDate.minusDays(1);
 }
 return date.periodUntil(endDate, unit);
 }
-return unit.between(this, endDateTime).getAmount();
+return unit.between(this, endDateTime);
 }
 //-----------------------------------------------------------------------
 /**
-* Returns an offset date-time formed from this date-time and the specified offset.
+* Combines this time with a date to create an {@code OffsetTime}.
 * <p>
-* This combines this date-time with the specified offset to form an {@code OffsetDateTime}.
+* This returns an {@code OffsetTime} formed from this time at the specified offset.
 * All possible combinations of date-time and offset are valid.
-* <p>
-* This instance is immutable and unaffected by this method call.
 *
 * @param offset  the offset to combine with, not null
 * @return the offset date-time formed from this date-time and the specified offset, not null
 */
 public OffsetDateTime atOffset(ZoneOffset offset) {
 return OffsetDateTime.of(this, offset);
 }
 /**
-* Returns a zoned date-time formed from this date-time and the specified time-zone.
+* Combines this time with a time-zone to create a {@code ZonedDateTime}.
 * <p>
-* This creates a zoned date-time matching the input date-time as closely as possible.
+* This returns a {@code ZonedDateTime} formed from this date-time at the
+* specified time-zone. The result will match this date-time as closely as possible.
 * Time-zone rules, such as daylight savings, mean that not every local date-time
 * is valid for the specified zone, thus the local date-time may be adjusted.
 * <p>
 * The local date-time is resolved to a single instant on the time-line.
 * This is achieved by finding a valid offset from UTC/Greenwich for the local
 * <p>
 * To obtain the later offset during an overlap, call
 * {@link ZonedDateTime#withLaterOffsetAtOverlap()} on the result of this method.
 * To throw an exception when there is a gap or overlap, use
 * {@link ZonedDateTime#ofStrict(LocalDateTime, ZoneOffset, ZoneId)}.
-* <p>
-* This instance is immutable and unaffected by this method call.
 *
 * @param zone  the time-zone to use, not null
 * @return the zoned date-time formed from this date-time, not null
 */
 @Override
 }
 return ChronoLocalDateTime.super.compareTo(other);
 }
 private int compareTo0(LocalDateTime other) {
-int cmp = date.compareTo0(other.getDate());
+int cmp = date.compareTo0(other.toLocalDate());
 if (cmp == 0) {
-cmp = time.compareTo(other.getTime());
+cmp = time.compareTo(other.toLocalTime());
 }
 return cmp;
 }
 /**
 /**
 * Outputs this date-time as a {@code String} using the formatter.
 * <p>
 * This date-time will be passed to the formatter
-* {@link DateTimeFormatter#print(TemporalAccessor) print method}.
+* {@link DateTimeFormatter#format(TemporalAccessor) format method}.
 *
 * @param formatter  the formatter to use, not null
 * @return the formatted date-time string, not null
 * @throws DateTimeException if an error occurs during printing
 */

changeset 15658	55b829ca2334
parent 15289	3ac550392e43
child 16852	60207b2b4b42