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

equal deleted inserted replaced

-:91f5e4399160
+:da9a41004459
 //-----------------------------------------------------------------------
 /**
 * Obtains an instance of {@code LocalDateTime} from a temporal object.
 * <p>
-* This obtains an offset time based on the specified temporal.
+* This obtains a local date-time based on the specified temporal.
 * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
 * which this factory converts to an instance of {@code LocalDateTime}.
 * <p>
 * The conversion extracts and combines the {@code LocalDate} and the
 * {@code LocalTime} from the temporal object.
 }
 /**
 * Gets the value of the specified field from this date-time as an {@code int}.
 * <p>
-* This queries this date-time for the value for the specified field.
+* This queries this date-time for the value of the specified field.
 * The returned value will always be within the valid range of values for the field.
 * If it is not possible to return the value, because the field is not supported
 * or for some other reason, an exception is thrown.
 * <p>
 * If the field is a {@link ChronoField} then the query is implemented here.
 * The {@link #isSupported(TemporalField) supported fields} will return valid
 * values based on this date-time, except {@code NANO_OF_DAY}, {@code MICRO_OF_DAY},
 * {@code EPOCH_DAY} and {@code PROLEPTIC_MONTH} which are too large to fit in
-* an {@code int} and throw a {@code DateTimeException}.
+* an {@code int} and throw a {@code UnsupportedTemporalTypeException}.
 * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.
 * <p>
 * If the field is not a {@code ChronoField}, then the result of this method
 * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}
 * passing {@code this} as the argument. Whether the value can be obtained,
 }
 /**
 * Gets the value of the specified field from this date-time as a {@code long}.
 * <p>
-* This queries this date-time for the value for the specified field.
+* This queries this date-time for the value of the specified field.
 * If it is not possible to return the value, because the field is not supported
 * or for some other reason, an exception is thrown.
 * <p>
 * If the field is a {@link ChronoField} then the query is implemented here.
 * The {@link #isSupported(TemporalField) supported fields} will return valid
 * 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 TemporalAdjuster}.
+* <p>
+* A selection of common adjustments is provided in
+* {@link java.time.temporal.TemporalAdjusters TemporalAdjusters}.
 * 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.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>
 *  import static java.time.Month.*;
-*  import static java.time.temporal.Adjusters.*;
+*  import static java.time.temporal.TemporalAdjusters.*;
 *
 *  result = localDateTime.with(JULY).with(lastDayOfMonth());
 * </pre>
 * <p>
 * The classes {@link LocalDate} and {@link LocalTime} implement {@code TemporalAdjuster},
 }
 //-----------------------------------------------------------------------
 /**
 * Returns a copy of this {@code LocalDateTime} with the year altered.
+* <p>
 * The time does not affect the calculation and will be the same in the result.
 * If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 return with(date.withYear(year), time);
 }
 /**
 * Returns a copy of this {@code LocalDateTime} with the month-of-year altered.
+* <p>
 * The time does not affect the calculation and will be the same in the result.
 * If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 return with(date.withMonth(month), time);
 }
 /**
 * Returns a copy of this {@code LocalDateTime} with the day-of-month altered.
-* If the resulting {@code LocalDateTime} is invalid, an exception is thrown.
+* <p>
+* If the resulting date-time is invalid, an exception is thrown.
 * The time does not affect the calculation and will be the same in the result.
 * <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 with(date.withDayOfMonth(dayOfMonth), time);
 }
 /**
 * Returns a copy of this {@code LocalDateTime} with the day-of-year altered.
-* If the resulting {@code LocalDateTime} is invalid, an exception is thrown.
+* <p>
+* If the resulting date-time is invalid, an exception is thrown.
 * <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
 return with(date.withDayOfYear(dayOfYear), time);
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code LocalDateTime} with the hour-of-day value altered.
+* Returns a copy of this {@code LocalDateTime} with the hour-of-day altered.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param hour  the hour-of-day to set in the result, from 0 to 23
 * @return a {@code LocalDateTime} based on this date-time with the requested hour, not null
 LocalTime newTime = time.withHour(hour);
 return with(date, newTime);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the minute-of-hour value altered.
+* Returns a copy of this {@code LocalDateTime} with the minute-of-hour altered.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param minute  the minute-of-hour to set in the result, from 0 to 59
 * @return a {@code LocalDateTime} based on this date-time with the requested minute, not null
 LocalTime newTime = time.withMinute(minute);
 return with(date, newTime);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the second-of-minute value altered.
+* Returns a copy of this {@code LocalDateTime} with the second-of-minute altered.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param second  the second-of-minute to set in the result, from 0 to 59
 * @return a {@code LocalDateTime} based on this date-time with the requested second, not null
 LocalTime newTime = time.withSecond(second);
 return with(date, newTime);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the nano-of-second value altered.
+* Returns a copy of this {@code LocalDateTime} with the nano-of-second altered.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param nanoOfSecond  the nano-of-second to set in the result, from 0 to 999,999,999
 * @return a {@code LocalDateTime} based on this date-time with the requested nanosecond, not null
 * 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
 * @throws DateTimeException if unable to truncate
-* @throws UnsupportedTemporalTypeException if the field is not supported
+* @throws UnsupportedTemporalTypeException if the unit is not supported
 */
 public LocalDateTime truncatedTo(TemporalUnit unit) {
 return with(date, time.truncatedTo(unit));
 }
 return unit.addTo(this, amountToAdd);
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in years added.
+* Returns a copy of this {@code LocalDateTime} with the specified number of years added.
 * <p>
 * This method adds the specified amount to the years field in three steps:
 * <ol>
 * <li>Add the input years to the year field</li>
 * <li>Check if the resulting date would be invalid</li>
 LocalDate newDate = date.plusYears(years);
 return with(newDate, time);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in months added.
+* Returns a copy of this {@code LocalDateTime} with the specified number of months added.
 * <p>
 * This method adds the specified amount to the months field in three steps:
 * <ol>
 * <li>Add the input months to the month-of-year field</li>
 * <li>Check if the resulting date would be invalid</li>
 LocalDate newDate = date.plusMonths(months);
 return with(newDate, time);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in weeks added.
+* Returns a copy of this {@code LocalDateTime} with the specified number of weeks added.
 * <p>
 * This method adds the specified amount in weeks to the days field incrementing
 * the month and year fields as necessary to ensure the result remains valid.
 * The result is only invalid if the maximum/minimum year is exceeded.
 * <p>
 LocalDate newDate = date.plusWeeks(weeks);
 return with(newDate, time);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in days added.
+* Returns a copy of this {@code LocalDateTime} with the specified number of days added.
 * <p>
 * This method adds the specified amount to the days field incrementing the
 * month and year fields as necessary to ensure the result remains valid.
 * The result is only invalid if the maximum/minimum year is exceeded.
 * <p>
 return with(newDate, time);
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in hours added.
+* Returns a copy of this {@code LocalDateTime} with the specified number of hours added.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param hours  the hours to add, may be negative
 * @return a {@code LocalDateTime} based on this date-time with the hours added, not null
 public LocalDateTime plusHours(long hours) {
 return plusWithOverflow(date, hours, 0, 0, 0, 1);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in minutes added.
+* Returns a copy of this {@code LocalDateTime} with the specified number of minutes added.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param minutes  the minutes to add, may be negative
 * @return a {@code LocalDateTime} based on this date-time with the minutes added, not null
 public LocalDateTime plusMinutes(long minutes) {
 return plusWithOverflow(date, 0, minutes, 0, 0, 1);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in seconds added.
+* Returns a copy of this {@code LocalDateTime} with the specified number of seconds added.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param seconds  the seconds to add, may be negative
 * @return a {@code LocalDateTime} based on this date-time with the seconds added, not null
 public LocalDateTime plusSeconds(long seconds) {
 return plusWithOverflow(date, 0, 0, seconds, 0, 1);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in nanoseconds added.
+* Returns a copy of this {@code LocalDateTime} with the specified number of nanoseconds added.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param nanos  the nanos to add, may be negative
 * @return a {@code LocalDateTime} based on this date-time with the nanoseconds added, not null
 return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in years subtracted.
+* Returns a copy of this {@code LocalDateTime} with the specified number of years subtracted.
 * <p>
 * This method subtracts the specified amount from the years field in three steps:
 * <ol>
 * <li>Subtract the input years from the year field</li>
 * <li>Check if the resulting date would be invalid</li>
 public LocalDateTime minusYears(long years) {
 return (years == Long.MIN_VALUE ? plusYears(Long.MAX_VALUE).plusYears(1) : plusYears(-years));
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in months subtracted.
+* Returns a copy of this {@code LocalDateTime} with the specified number of months subtracted.
 * <p>
 * This method subtracts the specified amount from the months field in three steps:
 * <ol>
 * <li>Subtract the input months from the month-of-year field</li>
 * <li>Check if the resulting date would be invalid</li>
 public LocalDateTime minusMonths(long months) {
 return (months == Long.MIN_VALUE ? plusMonths(Long.MAX_VALUE).plusMonths(1) : plusMonths(-months));
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in weeks subtracted.
+* Returns a copy of this {@code LocalDateTime} with the specified number of weeks subtracted.
 * <p>
 * This method subtracts the specified amount in weeks from the days field decrementing
 * the month and year fields as necessary to ensure the result remains valid.
 * The result is only invalid if the maximum/minimum year is exceeded.
 * <p>
 public LocalDateTime minusWeeks(long weeks) {
 return (weeks == Long.MIN_VALUE ? plusWeeks(Long.MAX_VALUE).plusWeeks(1) : plusWeeks(-weeks));
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in days subtracted.
+* Returns a copy of this {@code LocalDateTime} with the specified number of days subtracted.
 * <p>
-* This method subtracts the specified amount from the days field incrementing the
+* This method subtracts the specified amount from the days field decrementing the
 * month and year fields as necessary to ensure the result remains valid.
 * The result is only invalid if the maximum/minimum year is exceeded.
 * <p>
 * For example, 2009-01-01 minus one day would result in 2008-12-31.
 * <p>
 return (days == Long.MIN_VALUE ? plusDays(Long.MAX_VALUE).plusDays(1) : plusDays(-days));
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in hours subtracted.
+* Returns a copy of this {@code LocalDateTime} with the specified number of hours subtracted.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param hours  the hours to subtract, may be negative
 * @return a {@code LocalDateTime} based on this date-time with the hours subtracted, not null
 public LocalDateTime minusHours(long hours) {
 return plusWithOverflow(date, hours, 0, 0, 0, -1);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in minutes subtracted.
+* Returns a copy of this {@code LocalDateTime} with the specified number of minutes subtracted.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param minutes  the minutes to subtract, may be negative
 * @return a {@code LocalDateTime} based on this date-time with the minutes subtracted, not null
 public LocalDateTime minusMinutes(long minutes) {
 return plusWithOverflow(date, 0, minutes, 0, 0, -1);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in seconds subtracted.
+* Returns a copy of this {@code LocalDateTime} with the specified number of seconds subtracted.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param seconds  the seconds to subtract, may be negative
 * @return a {@code LocalDateTime} based on this date-time with the seconds subtracted, not null
 public LocalDateTime minusSeconds(long seconds) {
 return plusWithOverflow(date, 0, 0, seconds, 0, -1);
 }
 /**
-* Returns a copy of this {@code LocalDateTime} with the specified period in nanoseconds subtracted.
+* Returns a copy of this {@code LocalDateTime} with the specified number of nanoseconds subtracted.
 * <p>
 * This instance is immutable and unaffected by this method call.
 *
 * @param nanos  the nanos to subtract, may be negative
 * @return a {@code LocalDateTime} based on this date-time with the nanoseconds subtracted, not null
 * The {@code TemporalQuery} object defines the logic to be used to
 * obtain the result. Read the documentation of the query to understand
 * what the result of this method will be.
 * <p>
 * The result of this method is obtained by invoking the
-* {@link java.time.temporal.TemporalQuery#queryFrom(TemporalAccessor)} method on the
+* {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the
 * specified query passing {@code this} as the argument.
 *
 * @param <R> the type of the result
 * @param query  the query to invoke, not null
 * @return the query result, null may be returned (defined by the query)

changeset 24256	da9a41004459
parent 22566	4ebe53dd7814