+ * 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); + } + } + } + +}