- * This class provides common implementations of {@link TemporalAdjuster}. - * They are especially useful to document the intent of business logic and - * often link well to requirements. - * For example, these two pieces of code do the same thing, but the second - * one is clearer (assuming that there is a static import of this class): - *
- * // direct manipulation - * date.withDayOfMonth(1).plusMonths(1).minusDays(1); - * // use of an adjuster from this class - * date.with(lastDayOfMonth()); - *- * There are two equivalent ways of using a {@code TemporalAdjuster}. - * The first is to invoke the method on the interface directly. - * The second is to use {@link Temporal#with(TemporalAdjuster)}: - *
- * // these two lines are equivalent, but the second approach is recommended - * dateTime = adjuster.adjustInto(dateTime); - * dateTime = dateTime.with(adjuster); - *- * It is recommended to use the second approach, {@code with(TemporalAdjuster)}, - * as it is a lot clearer to read in code. - * - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 will return 2011-01-01.
- * The input 2011-02-15 will return 2011-02-01.
- *
- * The behavior is suitable for use with most calendar systems. - * It is equivalent to: - *
- * temporal.with(DAY_OF_MONTH, 1); - *- * - * @return the first day-of-month adjuster, not null - */ - public static TemporalAdjuster firstDayOfMonth() { - return Impl.FIRST_DAY_OF_MONTH; - } - - /** - * Returns the "last day of month" adjuster, which returns a new date set to - * the last day of the current month. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 will return 2011-01-31.
- * The input 2011-02-15 will return 2011-02-28.
- * The input 2012-02-15 will return 2012-02-29 (leap year).
- * The input 2011-04-15 will return 2011-04-30.
- *
- * The behavior is suitable for use with most calendar systems. - * It is equivalent to: - *
- * long lastDay = temporal.range(DAY_OF_MONTH).getMaximum(); - * temporal.with(DAY_OF_MONTH, lastDay); - *- * - * @return the last day-of-month adjuster, not null - */ - public static TemporalAdjuster lastDayOfMonth() { - return Impl.LAST_DAY_OF_MONTH; - } - - /** - * Returns the "first day of next month" adjuster, which returns a new date set to - * the first day of the next month. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 will return 2011-02-01.
- * The input 2011-02-15 will return 2011-03-01.
- *
- * The behavior is suitable for use with most calendar systems. - * It is equivalent to: - *
- * temporal.with(DAY_OF_MONTH, 1).plus(1, MONTHS); - *- * - * @return the first day of next month adjuster, not null - */ - public static TemporalAdjuster firstDayOfNextMonth() { - return Impl.FIRST_DAY_OF_NEXT_MONTH; - } - - //----------------------------------------------------------------------- - /** - * Returns the "first day of year" adjuster, which returns a new date set to - * the first day of the current year. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 will return 2011-01-01.
- * The input 2011-02-15 will return 2011-01-01.
- *
- * The behavior is suitable for use with most calendar systems. - * It is equivalent to: - *
- * temporal.with(DAY_OF_YEAR, 1); - *- * - * @return the first day-of-year adjuster, not null - */ - public static TemporalAdjuster firstDayOfYear() { - return Impl.FIRST_DAY_OF_YEAR; - } - - /** - * Returns the "last day of year" adjuster, which returns a new date set to - * the last day of the current year. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 will return 2011-12-31.
- * The input 2011-02-15 will return 2011-12-31.
- *
- * The behavior is suitable for use with most calendar systems. - * It is equivalent to: - *
- * long lastDay = temporal.range(DAY_OF_YEAR).getMaximum(); - * temporal.with(DAY_OF_YEAR, lastDay); - *- * - * @return the last day-of-year adjuster, not null - */ - public static TemporalAdjuster lastDayOfYear() { - return Impl.LAST_DAY_OF_YEAR; - } - - /** - * Returns the "first day of next year" adjuster, which returns a new date set to - * the first day of the next year. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 will return 2012-01-01.
- *
- * The behavior is suitable for use with most calendar systems. - * It is equivalent to: - *
- * temporal.with(DAY_OF_YEAR, 1).plus(1, YEARS); - *- * - * @return the first day of next month adjuster, not null - */ - public static TemporalAdjuster firstDayOfNextYear() { - return Impl.FIRST_DAY_OF_NEXT_YEAR; - } - - //----------------------------------------------------------------------- - /** - * Enum implementing the adjusters. - */ - private static class Impl implements TemporalAdjuster { - /** First day of month adjuster. */ - private static final Impl FIRST_DAY_OF_MONTH = new Impl(0); - /** Last day of month adjuster. */ - private static final Impl LAST_DAY_OF_MONTH = new Impl(1); - /** First day of next month adjuster. */ - private static final Impl FIRST_DAY_OF_NEXT_MONTH = new Impl(2); - /** First day of year adjuster. */ - private static final Impl FIRST_DAY_OF_YEAR = new Impl(3); - /** Last day of year adjuster. */ - private static final Impl LAST_DAY_OF_YEAR = new Impl(4); - /** First day of next month adjuster. */ - private static final Impl FIRST_DAY_OF_NEXT_YEAR = new Impl(5); - /** The ordinal. */ - private final int ordinal; - private Impl(int ordinal) { - this.ordinal = ordinal; - } - @Override - public Temporal adjustInto(Temporal temporal) { - switch (ordinal) { - case 0: return temporal.with(DAY_OF_MONTH, 1); - case 1: return temporal.with(DAY_OF_MONTH, temporal.range(DAY_OF_MONTH).getMaximum()); - case 2: return temporal.with(DAY_OF_MONTH, 1).plus(1, MONTHS); - case 3: return temporal.with(DAY_OF_YEAR, 1); - case 4: return temporal.with(DAY_OF_YEAR, temporal.range(DAY_OF_YEAR).getMaximum()); - case 5: return temporal.with(DAY_OF_YEAR, 1).plus(1, YEARS); - } - throw new IllegalStateException("Unreachable"); - } - } - - //----------------------------------------------------------------------- - /** - * Returns the first in month adjuster, which returns a new date - * in the same month with the first matching day-of-week. - * This is used for expressions like 'first Tuesday in March'. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-12-15 for (MONDAY) will return 2011-12-05.
- * The input 2011-12-15 for (FRIDAY) will return 2011-12-02.
- *
- * The behavior is suitable for use with most calendar systems. - * It uses the {@code DAY_OF_WEEK} and {@code DAY_OF_MONTH} fields - * and the {@code DAYS} unit, and assumes a seven day week. - * - * @param dayOfWeek the day-of-week, not null - * @return the first in month adjuster, not null - */ - public static TemporalAdjuster firstInMonth(DayOfWeek dayOfWeek) { - Objects.requireNonNull(dayOfWeek, "dayOfWeek"); - return new DayOfWeekInMonth(1, dayOfWeek); - } - - /** - * Returns the last in month adjuster, which returns a new date - * in the same month with the last matching day-of-week. - * This is used for expressions like 'last Tuesday in March'. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-12-15 for (MONDAY) will return 2011-12-26.
- * The input 2011-12-15 for (FRIDAY) will return 2011-12-30.
- *
- * The behavior is suitable for use with most calendar systems. - * It uses the {@code DAY_OF_WEEK} and {@code DAY_OF_MONTH} fields - * and the {@code DAYS} unit, and assumes a seven day week. - * - * @param dayOfWeek the day-of-week, not null - * @return the first in month adjuster, not null - */ - public static TemporalAdjuster lastInMonth(DayOfWeek dayOfWeek) { - Objects.requireNonNull(dayOfWeek, "dayOfWeek"); - return new DayOfWeekInMonth(-1, dayOfWeek); - } - - /** - * Returns the day-of-week in month adjuster, which returns a new date - * in the same month with the ordinal day-of-week. - * This is used for expressions like the 'second Tuesday in March'. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-12-15 for (1,TUESDAY) will return 2011-12-06.
- * The input 2011-12-15 for (2,TUESDAY) will return 2011-12-13.
- * The input 2011-12-15 for (3,TUESDAY) will return 2011-12-20.
- * The input 2011-12-15 for (4,TUESDAY) will return 2011-12-27.
- * The input 2011-12-15 for (5,TUESDAY) will return 2012-01-03.
- * The input 2011-12-15 for (-1,TUESDAY) will return 2011-12-27 (last in month).
- * The input 2011-12-15 for (-4,TUESDAY) will return 2011-12-06 (3 weeks before last in month).
- * The input 2011-12-15 for (-5,TUESDAY) will return 2011-11-29 (4 weeks before last in month).
- * The input 2011-12-15 for (0,TUESDAY) will return 2011-11-29 (last in previous month).
- *
- * For a positive or zero ordinal, the algorithm is equivalent to finding the first - * day-of-week that matches within the month and then adding a number of weeks to it. - * For a negative ordinal, the algorithm is equivalent to finding the last - * day-of-week that matches within the month and then subtracting a number of weeks to it. - * The ordinal number of weeks is not validated and is interpreted leniently - * according to this algorithm. This definition means that an ordinal of zero finds - * the last matching day-of-week in the previous month. - *
- * The behavior is suitable for use with most calendar systems. - * It uses the {@code DAY_OF_WEEK} and {@code DAY_OF_MONTH} fields - * and the {@code DAYS} unit, and assumes a seven day week. - * - * @param ordinal the week within the month, unbound but typically from -5 to 5 - * @param dayOfWeek the day-of-week, not null - * @return the day-of-week in month adjuster, not null - * @throws IllegalArgumentException if the ordinal is invalid - */ - public static TemporalAdjuster dayOfWeekInMonth(int ordinal, DayOfWeek dayOfWeek) { - Objects.requireNonNull(dayOfWeek, "dayOfWeek"); - return new DayOfWeekInMonth(ordinal, dayOfWeek); - } - - /** - * Class implementing day-of-week in month adjuster. - */ - private static final class DayOfWeekInMonth implements TemporalAdjuster { - /** The ordinal. */ - private final int ordinal; - /** The day-of-week value, from 1 to 7. */ - private final int dowValue; - - private DayOfWeekInMonth(int ordinal, DayOfWeek dow) { - super(); - this.ordinal = ordinal; - this.dowValue = dow.getValue(); - } - @Override - public Temporal adjustInto(Temporal temporal) { - if (ordinal >= 0) { - Temporal temp = temporal.with(DAY_OF_MONTH, 1); - int curDow = temp.get(DAY_OF_WEEK); - int dowDiff = (dowValue - curDow + 7) % 7; - dowDiff += (ordinal - 1L) * 7L; // safe from overflow - return temp.plus(dowDiff, DAYS); - } else { - Temporal temp = temporal.with(DAY_OF_MONTH, temporal.range(DAY_OF_MONTH).getMaximum()); - int curDow = temp.get(DAY_OF_WEEK); - int daysDiff = dowValue - curDow; - daysDiff = (daysDiff == 0 ? 0 : (daysDiff > 0 ? daysDiff - 7 : daysDiff)); - daysDiff -= (-ordinal - 1L) * 7L; // safe from overflow - return temp.plus(daysDiff, DAYS); - } - } - } - - //----------------------------------------------------------------------- - /** - * Returns the next day-of-week adjuster, which adjusts the date to the - * first occurrence of the specified day-of-week after the date being adjusted. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 (a Saturday) for parameter (MONDAY) will return 2011-01-17 (two days later).
- * The input 2011-01-15 (a Saturday) for parameter (WEDNESDAY) will return 2011-01-19 (four days later).
- * The input 2011-01-15 (a Saturday) for parameter (SATURDAY) will return 2011-01-22 (seven days later).
- *
- * The behavior is suitable for use with most calendar systems. - * It uses the {@code DAY_OF_WEEK} field and the {@code DAYS} unit, - * and assumes a seven day week. - * - * @param dayOfWeek the day-of-week to move the date to, not null - * @return the next day-of-week adjuster, not null - */ - public static TemporalAdjuster next(DayOfWeek dayOfWeek) { - return new RelativeDayOfWeek(2, dayOfWeek); - } - - /** - * Returns the next-or-same day-of-week adjuster, which adjusts the date to the - * first occurrence of the specified day-of-week after the date being adjusted - * unless it is already on that day in which case the same object is returned. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 (a Saturday) for parameter (MONDAY) will return 2011-01-17 (two days later).
- * The input 2011-01-15 (a Saturday) for parameter (WEDNESDAY) will return 2011-01-19 (four days later).
- * The input 2011-01-15 (a Saturday) for parameter (SATURDAY) will return 2011-01-15 (same as input).
- *
- * The behavior is suitable for use with most calendar systems. - * It uses the {@code DAY_OF_WEEK} field and the {@code DAYS} unit, - * and assumes a seven day week. - * - * @param dayOfWeek the day-of-week to check for or move the date to, not null - * @return the next-or-same day-of-week adjuster, not null - */ - public static TemporalAdjuster nextOrSame(DayOfWeek dayOfWeek) { - return new RelativeDayOfWeek(0, dayOfWeek); - } - - /** - * Returns the previous day-of-week adjuster, which adjusts the date to the - * first occurrence of the specified day-of-week before the date being adjusted. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 (a Saturday) for parameter (MONDAY) will return 2011-01-10 (five days earlier).
- * The input 2011-01-15 (a Saturday) for parameter (WEDNESDAY) will return 2011-01-12 (three days earlier).
- * The input 2011-01-15 (a Saturday) for parameter (SATURDAY) will return 2011-01-08 (seven days earlier).
- *
- * The behavior is suitable for use with most calendar systems. - * It uses the {@code DAY_OF_WEEK} field and the {@code DAYS} unit, - * and assumes a seven day week. - * - * @param dayOfWeek the day-of-week to move the date to, not null - * @return the previous day-of-week adjuster, not null - */ - public static TemporalAdjuster previous(DayOfWeek dayOfWeek) { - return new RelativeDayOfWeek(3, dayOfWeek); - } - - /** - * Returns the previous-or-same day-of-week adjuster, which adjusts the date to the - * first occurrence of the specified day-of-week before the date being adjusted - * unless it is already on that day in which case the same object is returned. - *
- * The ISO calendar system behaves as follows:
- * The input 2011-01-15 (a Saturday) for parameter (MONDAY) will return 2011-01-10 (five days earlier).
- * The input 2011-01-15 (a Saturday) for parameter (WEDNESDAY) will return 2011-01-12 (three days earlier).
- * The input 2011-01-15 (a Saturday) for parameter (SATURDAY) will return 2011-01-15 (same as input).
- *
- * The behavior is suitable for use with most calendar systems. - * It uses the {@code DAY_OF_WEEK} field and the {@code DAYS} unit, - * and assumes a seven day week. - * - * @param dayOfWeek the day-of-week to check for or move the date to, not null - * @return the previous-or-same day-of-week adjuster, not null - */ - public static TemporalAdjuster previousOrSame(DayOfWeek dayOfWeek) { - return new RelativeDayOfWeek(1, dayOfWeek); - } - - /** - * Implementation of next, previous or current day-of-week. - */ - private static final class RelativeDayOfWeek implements TemporalAdjuster { - /** Whether the current date is a valid answer. */ - private final int relative; - /** The day-of-week value, from 1 to 7. */ - private final int dowValue; - - private RelativeDayOfWeek(int relative, DayOfWeek dayOfWeek) { - Objects.requireNonNull(dayOfWeek, "dayOfWeek"); - this.relative = relative; - this.dowValue = dayOfWeek.getValue(); - } - - @Override - public Temporal adjustInto(Temporal temporal) { - int calDow = temporal.get(DAY_OF_WEEK); - if (relative < 2 && calDow == dowValue) { - return temporal; - } - if ((relative & 1) == 0) { - int daysDiff = calDow - dowValue; - return temporal.plus(daysDiff >= 0 ? 7 - daysDiff : -daysDiff, DAYS); - } else { - int daysDiff = dowValue - calDow; - return temporal.minus(daysDiff >= 0 ? 7 - daysDiff : -daysDiff, DAYS); - } - } - } - -}