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

equal deleted inserted replaced

-:91f5e4399160
+:da9a41004459
 * the {@code LocalDateTime} and {@code ZoneOffset}.
 * This combination uniquely specifies an instant without ambiguity.
 * <p>
 * Converting an instant to a zoned date-time is simple as there is only one valid
 * offset for each instant. If the valid offset is different to the offset specified,
-* the the date-time and offset of the zoned date-time will differ from those specified.
+* then the date-time and offset of the zoned date-time will differ from those specified.
 * <p>
 * If the {@code ZoneId} to be used is a {@code ZoneOffset}, this method is equivalent
 * to {@link #of(LocalDateTime, ZoneId)}.
 *
 * @param localDateTime  the local date-time, not null
 *
 * @param localDateTime  the local date-time, not null
 * @param offset  the zone offset, not null
 * @param zone  the time-zone, not null
 * @return the zoned date-time, not null
+* @throws DateTimeException if the combination of arguments is invalid
 */
 public static ZonedDateTime ofStrict(LocalDateTime localDateTime, ZoneOffset offset, ZoneId zone) {
 Objects.requireNonNull(localDateTime, "localDateTime");
 Objects.requireNonNull(offset, "offset");
 Objects.requireNonNull(zone, "zone");
 * with {@code Instant} or {@code LocalDateTime}.
 * 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 in queries via method reference, {@code ZonedDateTime::from}.
+* allowing it to be used as a query via method reference, {@code ZonedDateTime::from}.
 *
 * @param temporal  the temporal object to convert, not null
 * @return the zoned date-time, not null
 * @throws DateTimeException if unable to convert to an {@code ZonedDateTime}
 */
 }
 /**
 * 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}, {@code PROLEPTIC_MONTH} and {@code INSTANT_SECONDS} which are too
-* large to fit in an {@code int} and throw a {@code DateTimeException}.
+* large to fit in 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}.
+* 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 = zonedDateTime.with(JULY).with(lastDayOfMonth());
 * </pre>
 * <p>
 * The classes {@link LocalDate} and {@link LocalTime} implement {@code TemporalAdjuster},
 return field.adjustInto(this, newValue);
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code ZonedDateTime} with the year value altered.
+* Returns a copy of this {@code ZonedDateTime} with the year altered.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#withYear(int) changing the year} of the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime withYear(int year) {
 return resolveLocal(dateTime.withYear(year));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the month-of-year value altered.
+* Returns a copy of this {@code ZonedDateTime} with the month-of-year altered.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#withMonth(int) changing the month} of the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime withMonth(int month) {
 return resolveLocal(dateTime.withMonth(month));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the day-of-month value altered.
+* Returns a copy of this {@code ZonedDateTime} with the day-of-month altered.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#withDayOfMonth(int) changing the day-of-month} of the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 return resolveLocal(dateTime.withDayOfYear(dayOfYear));
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code ZonedDateTime} with the hour-of-day value altered.
+* Returns a copy of this {@code ZonedDateTime} with the hour-of-day altered.
 * <p>
 * This operates on the local time-line,
 * {@linkplain LocalDateTime#withHour(int) changing the time} of the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime withHour(int hour) {
 return resolveLocal(dateTime.withHour(hour));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the minute-of-hour value altered.
+* Returns a copy of this {@code ZonedDateTime} with the minute-of-hour altered.
 * <p>
 * This operates on the local time-line,
 * {@linkplain LocalDateTime#withMinute(int) changing the time} of the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime withMinute(int minute) {
 return resolveLocal(dateTime.withMinute(minute));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the second-of-minute value altered.
+* Returns a copy of this {@code ZonedDateTime} with the second-of-minute altered.
 * <p>
 * This operates on the local time-line,
 * {@linkplain LocalDateTime#withSecond(int) changing the time} of the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime withSecond(int second) {
 return resolveLocal(dateTime.withSecond(second));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the nano-of-second value altered.
+* Returns a copy of this {@code ZonedDateTime} with the nano-of-second altered.
 * <p>
 * This operates on the local time-line,
 * {@linkplain LocalDateTime#withNano(int) changing the time} of the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 * 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 operates on the local time-line,
-* {@link LocalDateTime#truncatedTo(java.time.temporal.TemporalUnit) truncating}
+* {@link LocalDateTime#truncatedTo(TemporalUnit) truncating}
 * the underlying local date-time. This is then converted back to a
 * {@code ZonedDateTime}, using the zone ID to obtain the offset.
 * <p>
 * When converting back to {@code ZonedDateTime}, if the local date-time is in an overlap,
 * then the offset will be retained if possible, otherwise the earlier offset will be used.
 return unit.addTo(this, amountToAdd);
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in years added.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of years added.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#plusYears(long) adding years} to the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime plusYears(long years) {
 return resolveLocal(dateTime.plusYears(years));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in months added.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of months added.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#plusMonths(long) adding months} to the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime plusMonths(long months) {
 return resolveLocal(dateTime.plusMonths(months));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in weeks added.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of weeks added.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#plusWeeks(long) adding weeks} to the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime plusWeeks(long weeks) {
 return resolveLocal(dateTime.plusWeeks(weeks));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in days added.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of days added.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#plusDays(long) adding days} to the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 return resolveLocal(dateTime.plusDays(days));
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in hours added.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of hours added.
 * <p>
 * This operates on the instant time-line, such that adding one hour will
 * always be a duration of one hour later.
 * This may cause the local date-time to change by an amount other than one hour.
 * Note that this is a different approach to that used by days, months and years,
 public ZonedDateTime plusHours(long hours) {
 return resolveInstant(dateTime.plusHours(hours));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in minutes added.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of minutes added.
 * <p>
 * This operates on the instant time-line, such that adding one minute will
 * always be a duration of one minute later.
 * This may cause the local date-time to change by an amount other than one minute.
 * Note that this is a different approach to that used by days, months and years.
 public ZonedDateTime plusMinutes(long minutes) {
 return resolveInstant(dateTime.plusMinutes(minutes));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in seconds added.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of seconds added.
 * <p>
 * This operates on the instant time-line, such that adding one second will
 * always be a duration of one second later.
 * This may cause the local date-time to change by an amount other than one second.
 * Note that this is a different approach to that used by days, months and years.
 public ZonedDateTime plusSeconds(long seconds) {
 return resolveInstant(dateTime.plusSeconds(seconds));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in nanoseconds added.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of nanoseconds added.
 * <p>
 * This operates on the instant time-line, such that adding one nano will
 * always be a duration of one nano later.
 * This may cause the local date-time to change by an amount other than one nano.
 * Note that this is a different approach to that used by days, months and years.
 return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in years subtracted.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of years subtracted.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#minusYears(long) subtracting years} to the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime minusYears(long years) {
 return (years == Long.MIN_VALUE ? plusYears(Long.MAX_VALUE).plusYears(1) : plusYears(-years));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in months subtracted.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of months subtracted.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#minusMonths(long) subtracting months} to the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime minusMonths(long months) {
 return (months == Long.MIN_VALUE ? plusMonths(Long.MAX_VALUE).plusMonths(1) : plusMonths(-months));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in weeks subtracted.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of weeks subtracted.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#minusWeeks(long) subtracting weeks} to the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 public ZonedDateTime minusWeeks(long weeks) {
 return (weeks == Long.MIN_VALUE ? plusWeeks(Long.MAX_VALUE).plusWeeks(1) : plusWeeks(-weeks));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in days subtracted.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of days subtracted.
 * <p>
 * This operates on the local time-line,
 * {@link LocalDateTime#minusDays(long) subtracting days} to the local date-time.
 * This is then converted back to a {@code ZonedDateTime}, using the zone ID
 * to obtain the offset.
 return (days == Long.MIN_VALUE ? plusDays(Long.MAX_VALUE).plusDays(1) : plusDays(-days));
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in hours subtracted.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of hours subtracted.
 * <p>
 * This operates on the instant time-line, such that subtracting one hour will
 * always be a duration of one hour earlier.
 * This may cause the local date-time to change by an amount other than one hour.
 * Note that this is a different approach to that used by days, months and years,
 public ZonedDateTime minusHours(long hours) {
 return (hours == Long.MIN_VALUE ? plusHours(Long.MAX_VALUE).plusHours(1) : plusHours(-hours));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in minutes subtracted.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of minutes subtracted.
 * <p>
 * This operates on the instant time-line, such that subtracting one minute will
 * always be a duration of one minute earlier.
 * This may cause the local date-time to change by an amount other than one minute.
 * Note that this is a different approach to that used by days, months and years.
 public ZonedDateTime minusMinutes(long minutes) {
 return (minutes == Long.MIN_VALUE ? plusMinutes(Long.MAX_VALUE).plusMinutes(1) : plusMinutes(-minutes));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in seconds subtracted.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of seconds subtracted.
 * <p>
 * This operates on the instant time-line, such that subtracting one second will
 * always be a duration of one second earlier.
 * This may cause the local date-time to change by an amount other than one second.
 * Note that this is a different approach to that used by days, months and years.
 public ZonedDateTime minusSeconds(long seconds) {
 return (seconds == Long.MIN_VALUE ? plusSeconds(Long.MAX_VALUE).plusSeconds(1) : plusSeconds(-seconds));
 }
 /**
-* Returns a copy of this {@code ZonedDateTime} with the specified period in nanoseconds subtracted.
+* Returns a copy of this {@code ZonedDateTime} with the specified number of nanoseconds subtracted.
 * <p>
 * This operates on the instant time-line, such that subtracting one nano will
 * always be a duration of one nano earlier.
 * This may cause the local date-time to change by an amount other than one nano.
 * Note that this is a different approach to that used by days, months and years.
 * 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)
 * <p>
 * This calculates the amount of time between two {@code ZonedDateTime}
 * objects in terms of a single {@code TemporalUnit}.
 * The start and end points are {@code this} and the specified date-time.
 * The result will be negative if the end is before the start.
-* For example, the period in days between two date-times can be calculated
+* For example, the amount in days between two date-times can be calculated
 * using {@code startDateTime.until(endDateTime, DAYS)}.
 * <p>
 * The {@code Temporal} passed to this method is converted to a
 * {@code ZonedDateTime} using {@link #from(TemporalAccessor)}.
 * If the time-zone differs between the two zoned date-times, the specified
 * end date-time is normalized to have the same zone as this date-time.
 * <p>
 * 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:00Z and 2012-08-14T23:59Z
+* For example, the amount in months between 2012-06-15T00:00Z and 2012-08-14T23:59Z
 * will only be one month as it is one minute short of two months.
 * <p>
 * There are two equivalent ways of using this method.
 * The first is to invoke this method.
 * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}:

changeset 24256	da9a41004459
parent 22566	4ebe53dd7814
child 24985	61ec15d123c3