Module java.base

Package java.time.temporal

Class TemporalAdjusters

java.lang.Object

java.time.temporal.TemporalAdjusters

       public final class TemporalAdjusters extends Object
      

常见且有用的TemporalAdjusters。

Adjusters是修改时间对象的关键工具。它们存在是为了外部化调整过程，允许不同的方法，符合策略设计模式。例如，可能会有一个调整器，设置日期以避开周末，或者一个将日期设置为月份最后一天的调整器。

使用TemporalAdjuster有两种等效的方式。第一种是直接在接口上调用方法。第二种是使用Temporal.with(TemporalAdjuster)：

   // 这两行是等效的，但第二种方法更推荐
   temporal = thisAdjuster.adjustInto(temporal);
   temporal = temporal.with(thisAdjuster);
 

推荐使用第二种方法with(TemporalAdjuster)，因为在代码中更清晰易读。

这个类包含一组标准的adjusters，可通过静态方法获得。这些包括：

• 找到月份的第一天或最后一天
• 找到下个月的第一天
• 找到年份的第一天或最后一天
• 找到下一年的第一天
• 找到月份内的第一个或最后一个星期几，比如“六月的第一个星期三”
• 找到下一个或上一个星期几，比如“下个星期四”

实现要求：

所有由静态方法提供的实现都是不可变的。

自版本：

1.8

参见：

• TemporalAdjuster

Method Summary

Modifier and Type	Method	Description
static TemporalAdjuster	dayOfWeekInMonth(int ordinal, DayOfWeek dayOfWeek)	返回月份内星期几的adjuster，根据月份返回基于星期几的序数日期。
static TemporalAdjuster	firstDayOfMonth()	返回“本月第一天”adjuster，将新日期设置为当前月份的第一天。
static TemporalAdjuster	firstDayOfNextMonth()	返回“下个月第一天”adjuster，将新日期设置为下个月的第一天。
static TemporalAdjuster	firstDayOfNextYear()	返回“下一年第一天”adjuster，将新日期设置为下一年的第一天。
static TemporalAdjuster	firstDayOfYear()	返回“本年第一天”adjuster，将新日期设置为当前年的第一天。
static TemporalAdjuster	firstInMonth(DayOfWeek dayOfWeek)	返回月份内第一个星期几的adjuster，返回同一月份中第一个匹配星期几的新日期。
static TemporalAdjuster	lastDayOfMonth()	返回“本月最后一天”adjuster，将新日期设置为当前月份的最后一天。
static TemporalAdjuster	lastDayOfYear()	返回“本年最后一天”adjuster，将新日期设置为当前年的最后一天。
static TemporalAdjuster	lastInMonth(DayOfWeek dayOfWeek)	返回月份内最后一个星期几的adjuster，返回同一月份中最后一个匹配星期几的新日期。
static TemporalAdjuster	next(DayOfWeek dayOfWeek)	返回下一个星期几的adjuster，将日期调整为指定星期几之后的第一个出现。
static TemporalAdjuster	nextOrSame(DayOfWeek dayOfWeek)	返回下一个或相同星期几的adjuster，将日期调整为指定星期几之后的第一个出现，除非已经在那一天，此时返回相同对象。
static TemporalAdjuster	ofDateAdjuster(UnaryOperator<LocalDate> dateBasedAdjuster)	获得包装日期调整器的TemporalAdjuster。
static TemporalAdjuster	previous(DayOfWeek dayOfWeek)	返回前一个星期几的adjuster，将日期调整为指定星期几之前的第一个出现。
static TemporalAdjuster	previousOrSame(DayOfWeek dayOfWeek)	返回前一个或相同星期几的adjuster，将日期调整为指定星期几之前的第一个出现，除非已经在那一天，此时返回相同对象。

Methods declared in class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

ofDateAdjuster

             public static TemporalAdjuster ofDateAdjuster(UnaryOperator<LocalDate> dateBasedAdjuster)
            

获得包装日期调整器的TemporalAdjuster。

TemporalAdjuster基于底层的Temporal接口。此方法允许将从LocalDate到LocalDate的调整器包装以匹配基于时间的接口。这是为了方便起见，使用户编写的调整器更简单。

一般来说，用户编写的调整器应该是静态常量：

  static TemporalAdjuster TWO_DAYS_LATER =
       TemporalAdjusters.ofDateAdjuster(date -> date.plusDays(2));
 

参数：

dateBasedAdjuster - 基于日期的调整器，不能为空

返回：

包装在日期调整器上的时间调整器，不能为空

firstDayOfMonth

             public static TemporalAdjuster firstDayOfMonth()
            

返回“本月第一天”adjuster，将新日期设置为当前月份的第一天。

ISO日历系统的行为如下：
输入2011-01-15将返回2011-01-01。
输入2011-02-15将返回2011-02-01。

此行为适用于大多数日历系统。它等同于：

  temporal.with(DAY_OF_MONTH, 1);
 

返回：

第一天的adjuster，不能为空

lastDayOfMonth

             public static TemporalAdjuster lastDayOfMonth()
            

返回“本月最后一天”adjuster，将新日期设置为当前月份的最后一天。

ISO日历系统的行为如下：
输入2011-01-15将返回2011-01-31。
输入2011-02-15将返回2011-02-28。
输入2012-02-15将返回2012-02-29（闰年）。
输入2011-04-15将返回2011-04-30。

此行为适用于大多数日历系统。它等同于：

  long lastDay = temporal.range(DAY_OF_MONTH).getMaximum();
  temporal.with(DAY_OF_MONTH, lastDay);
 

返回：

最后一天的adjuster，不能为空

firstDayOfNextMonth

             public static TemporalAdjuster firstDayOfNextMonth()
            

返回“下个月第一天”adjuster，将新日期设置为下个月的第一天。

ISO日历系统的行为如下：
输入2011-01-15将返回2011-02-01。
输入2011-02-15将返回2011-03-01。

此行为适用于大多数日历系统。它等同于：

  temporal.with(DAY_OF_MONTH, 1).plus(1, MONTHS);
 

返回：

下个月第一天的adjuster，不能为空

firstDayOfYear

             public static TemporalAdjuster firstDayOfYear()
            

返回“本年第一天”adjuster，将新日期设置为当前年的第一天。

ISO日历系统的行为如下：
输入2011-01-15将返回2011-01-01。
输入2011-02-15将返回2011-01-01。

此行为适用于大多数日历系统。它等同于：

  temporal.with(DAY_OF_YEAR, 1);
 

返回：

本年第一天的adjuster，不能为空

lastDayOfYear

             public static TemporalAdjuster lastDayOfYear()
            

返回“本年最后一天”adjuster，将新日期设置为当前年的最后一天。

ISO日历系统的行为如下：
输入2011-01-15将返回2011-12-31。
输入2011-02-15将返回2011-12-31。

此行为适用于大多数日历系统。它等同于：

  long lastDay = temporal.range(DAY_OF_YEAR).getMaximum();
  temporal.with(DAY_OF_YEAR, lastDay);
 

返回：

本年最后一天的adjuster，不能为空

firstDayOfNextYear

             public static TemporalAdjuster firstDayOfNextYear()
            

返回“下一年第一天”adjuster，将新日期设置为下一年的第一天。

ISO日历系统的行为如下：
输入2011-01-15将返回2012-01-01。

此行为适用于大多数日历系统。它等同于：

  temporal.with(DAY_OF_YEAR, 1).plus(1, YEARS);
 

返回：

下一年第一天的adjuster，不能为空

firstInMonth

             public static TemporalAdjuster firstInMonth(DayOfWeek dayOfWeek)
            

返回月份内第一个星期几的adjuster，返回同一月份中第一个匹配星期几的新日期。用于表达式如“三月的第一个星期二”。

ISO日历系统的行为如下：
输入2011-12-15（星期一）将返回2011-12-05。
输入2011-12-15（星期五）将返回2011-12-02。

此行为适用于大多数日历系统。它使用DAY_OF_WEEK和DAY_OF_MONTH字段以及DAYS单位，并假定一周七天。

参数：

dayOfWeek - 星期几，不能为空

返回：

月份内第一个的adjuster，不能为空

lastInMonth

             public static TemporalAdjuster lastInMonth(DayOfWeek dayOfWeek)
            

返回月份内最后一个星期几的adjuster，返回同一月份中最后一个匹配星期几的新日期。用于表达式如“三月的最后一个星期二”。

ISO日历系统的行为如下：
输入2011-12-15（星期一）将返回2011-12-26。
输入2011-12-15（星期五）将返回2011-12-30。

此行为适用于大多数日历系统。它使用DAY_OF_WEEK和DAY_OF_MONTH字段以及DAYS单位，并假定一周七天。

参数：

dayOfWeek - 星期几，不能为空

返回：

月份内最后一个的adjuster，不能为空

dayOfWeekInMonth

             public static TemporalAdjuster dayOfWeekInMonth(int ordinal, DayOfWeek dayOfWeek)
            

返回月份内星期几的adjuster，返回基于月份的星期几序数日期。用于表达式如“三月的第二个星期二”。

ISO日历系统的行为如下：
输入2011-12-15（1,星期二）将返回2011-12-06。
输入2011-12-15（2,星期二）将返回2011-12-13。
输入2011-12-15（3,星期二）将返回2011-12-20。
输入2011-12-15（4,星期二）将返回2011-12-27。
输入2011-12-15（5,星期二）将返回2012-01-03。
输入2011-12-15（-1,星期二）将返回2011-12-27（月份最后一个）。
输入2011-12-15（-4,星期二）将返回2011-12-06（月份倒数第三周）。
输入2011-12-15（-5,星期二）将返回2011-11-29（月份倒数第四周）。
输入2011-12-15（0,星期二）将返回2011-11-29（上个月的最后一个星期二）。

对于正数或零序数，算法等同于在月份内找到第一个匹配的星期几，然后添加一定数量的周数。对于负数序数，算法等同于在月份内找到最后一个匹配的星期几，然后减去一定数量的周数。周数的序数不会被验证，并且根据此算法宽松解释。这个定义意味着序数为零会在上个月找到最后一个匹配的星期几。

此行为适用于大多数日历系统。它使用DAY_OF_WEEK和DAY_OF_MONTH字段以及DAYS单位，并假定一周七天。

参数:

ordinal - 月份内的周数，无限制但通常为-5到5

dayOfWeek - 星期几，非空

返回:

月份内星期几调整器，非空

next

             public static TemporalAdjuster next(DayOfWeek dayOfWeek)
            

返回下一个星期几调整器，将日期调整为指定星期几在被调整日期之后的第一次出现。

ISO日历系统的行为如下：
对于参数（星期一），输入2011-01-15（星期六）将返回2011-01-17（晚两天）。
对于参数（星期三），输入2011-01-15（星期六）将返回2011-01-19（晚四天）。
对于参数（星期六），输入2011-01-15（星期六）将返回2011-01-22（晚七天）。

该行为适用于大多数日历系统。它使用DAY_OF_WEEK字段和DAYS单位，并假定一周为七天。

参数:

dayOfWeek - 要将日期移动到的星期几，非空

返回:

下一个星期几调整器，非空

nextOrSame

             public static TemporalAdjuster nextOrSame(DayOfWeek dayOfWeek)
            

返回下一个或相同的星期几调整器，将日期调整为指定星期几在被调整日期之后的第一次出现，除非日期已经在该天，此时返回相同的对象。

ISO日历系统的行为如下：
对于参数（星期一），输入2011-01-15（星期六）将返回2011-01-17（晚两天）。
对于参数（星期三），输入2011-01-15（星期六）将返回2011-01-19（晚四天）。
对于参数（星期六），输入2011-01-15（星期六）将返回2011-01-15（与输入相同）。

该行为适用于大多数日历系统。它使用DAY_OF_WEEK字段和DAYS单位，并假定一周为七天。

参数:

dayOfWeek - 要检查或将日期移动到的星期几，非空

返回:

下一个或相同的星期几调整器，非空

previous

             public static TemporalAdjuster previous(DayOfWeek dayOfWeek)
            

返回前一个星期几调整器，将日期调整为指定星期几在被调整日期之前的第一次出现。

ISO日历系统的行为如下：
对于参数（星期一），输入2011-01-15（星期六）将返回2011-01-10（早五天）。
对于参数（星期三），输入2011-01-15（星期六）将返回2011-01-12（早三天）。
对于参数（星期六），输入2011-01-15（星期六）将返回2011-01-08（早七天）。

该行为适用于大多数日历系统。它使用DAY_OF_WEEK字段和DAYS单位，并假定一周为七天。

参数:

dayOfWeek - 要将日期移动到的星期几，非空

返回:

前一个星期几调整器，非空

previousOrSame

             public static TemporalAdjuster previousOrSame(DayOfWeek dayOfWeek)
            

返回前一个或相同的星期几调整器，将日期调整为指定星期几在被调整日期之前的第一次出现，除非日期已经在该天，此时返回相同的对象。

ISO日历系统的行为如下：
对于参数（星期一），输入2011-01-15（星期六）将返回2011-01-10（早五天）。
对于参数（星期三），输入2011-01-15（星期六）将返回2011-01-12（早三天）。
对于参数（星期六），输入2011-01-15（星期六）将返回2011-01-15（与输入相同）。

该行为适用于大多数日历系统。它使用DAY_OF_WEEK字段和DAYS单位，并假定一周为七天。

参数:

dayOfWeek - 要检查或将日期移动到的星期几，非空

返回:

前一个或相同的星期几调整器，非空