模块 java.base

包 java.time

类 MonthDay

java.lang.Object

java.time.MonthDay

所有已实现的接口：

Serializable , Comparable<MonthDay> , TemporalAccessor , TemporalAdjuster

public final class MonthDay extends Object implements TemporalAccessor , TemporalAdjuster , Comparable <MonthDay >, Serializable 
      

ISO-8601 日历系统中的月日，例如 --12-03 。

MonthDay 是一个不可变的日期时间对象，表示月份和日期的组合。任何可以从月和日派生出来的字段，比如quarter-of-year，都可以得到。

此类不存储或表示年份、时间或时区。例如，值“December 3rd”可以存储在 MonthDay 中。

由于 MonthDay 没有年份，因此闰日 2 月 29 日被认为是有效的。

此类实现 TemporalAccessor 而不是 Temporal 。这是因为在没有外部信息的情况下无法定义 2 月 29 日是否有效，从而阻止了加减法的实施。与此相关，MonthDay 仅提供查询和设置字段 MONTH_OF_YEAR 和 DAY_OF_MONTH 的权限。

ISO-8601 日历系统是当今世界大部分地区使用的现代民用日历系统。它相当于公历系统，在所有时间都适用今天的闰年规则。对于当今编写的大多数应用程序，ISO-8601 规则完全适用。然而，任何使用历史日期并要求它们准确的应用程序都会发现 ISO-8601 方法不合适。

这是一个value-based类；程序员应该将 equal 的实例视为可互换的，并且不应使用实例进行同步，否则可能会发生不可预测的行为。例如，在未来的版本中，同步可能会失败。 equals 方法应该用于比较。

实现要求：

这个类是不可变的和线程安全的。

自从：

1.8

参见：

• Serialized Form

方法总结

修饰符和类型	方法	描述
Temporal	adjustInto(Temporal temporal)	调整指定的时间对象以具有此月-日。
LocalDate	atYear(int year)	将这个月-日与年份结合起来创建一个 LocalDate 。
int	compareTo(MonthDay other)	将这个月日与另一个月日进行比较。
boolean	equals(Object obj)	检查这个月日是否等于另一个月日。
String	format(DateTimeFormatter formatter)	使用指定的格式化程序格式化这个月日。
static MonthDay	from(TemporalAccessor temporal)	从时间对象中获取 MonthDay 的实例。
int	get(TemporalField field)	从此月-日获取指定字段的值作为 int 。
int	getDayOfMonth()	获取日期字段。
long	getLong(TemporalField field)	从此月-日获取指定字段的值作为 long 。
Month	getMonth()	使用 Month 枚举获取月份字段。
int	getMonthValue()	获取从 1 到 12 的月份字段。
int	hashCode()	这个月-日的哈希码。
boolean	isAfter(MonthDay other)	检查这个月日是否在指定的月日之后。
boolean	isBefore(MonthDay other)	检查这个月日是否在指定的月日之前。
boolean	isSupported(TemporalField field)	检查是否支持指定的字段。
boolean	isValidYear(int year)	检查年份是否对该月-日有效。
static MonthDay	now()	从默认时区的系统时钟获取当前月日。
static MonthDay	now(Clock clock)	从指定时钟获取当前月-日。
static MonthDay	now(ZoneId zone)	从指定时区的系统时钟获取当前月-日。
static MonthDay	of(int month, int dayOfMonth)	获得 MonthDay 的实例。
static MonthDay	of(Month month, int dayOfMonth)	获得 MonthDay 的实例。
static MonthDay	parse(CharSequence text)	从 --12-03 等文本字符串中获取 MonthDay 的实例。
static MonthDay	parse(CharSequence text, DateTimeFormatter formatter)	使用特定格式化程序从文本字符串中获取 MonthDay 的实例。
<R> R	query(TemporalQuery<R> query)	使用指定查询查询本月-日。
ValueRange	range(TemporalField field)	获取指定字段的有效值范围。
String	toString()	将这个月-日输出为 String ，例如 --12-03 。
MonthDay	with(Month month)	返回此 MonthDay 的副本，其中月份已更改。
MonthDay	withDayOfMonth(int dayOfMonth)	返回此 MonthDay 的副本，其中日期已更改。
MonthDay	withMonth(int month)	返回此 MonthDay 的副本，其中月份已更改。

在类 java.lang.Object 中声明的方法

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

方法详情

now

public static MonthDay  now()
            

从默认时区的系统时钟获取当前月日。

这将查询默认时区中的 system clock 以获取当前月日。

使用此方法将阻止使用备用时钟进行测试的能力，因为时钟是硬编码的。

返回：

使用系统时钟和默认时区的当前月日，不为空

now

public static MonthDay  now(ZoneId  zone)
            

从指定时区的系统时钟获取当前月-日。

这将查询 system clock 以获取当前月-日。指定时区避免了对默认时区的依赖。

使用此方法将阻止使用备用时钟进行测试的能力，因为时钟是硬编码的。

参数：

zone - 要使用的区域 ID，不为空

返回：

使用系统时钟的当前月日，不为空

now

public static MonthDay  now(Clock  clock)
            

从指定时钟获取当前月-日。

这将查询指定的时钟以获取当前的月-日。使用此方法允许使用备用时钟进行测试。可以使用 dependency injection 引入备用时钟。

参数：

clock - 使用的时钟，不为空

返回：

当前月日，不为空

of

public static MonthDay  of(Month  month, int dayOfMonth)
            

获得 MonthDay 的实例。

日期必须对闰年内的月份有效。因此，对于 2 月，第 29 天有效。

例如，在 4 月和第 31 天传递将引发异常，因为任何一年都不可能有 4 月 31 日。相比之下，允许在 2 月 29 日通过，因为该月日有时是有效的。

参数：

month - 要表示的月份，不为空

dayOfMonth - 要表示的日期，从 1 到 31

返回：

月日，不为空

抛出：

DateTimeException - 如果任何字段的值超出范围，或者如果该月的日期无效

of

public static MonthDay  of(int month, int dayOfMonth)
            

获得 MonthDay 的实例。

日期必须对闰年内的月份有效。因此，对于第 2 个月（2 月），第 29 天有效。

例如，在第 4 个月（4 月）和第 31 天传递将引发异常，因为任何一年都不可能有 4 月 31 日。相比之下，允许在 2 月 29 日通过，因为该月日有时是有效的。

参数：

month - 要表示的月份，从 1（一月）到 12（十二月）

dayOfMonth - 要表示的日期，从 1 到 31

返回：

月日，不为空

抛出：

DateTimeException - 如果任何字段的值超出范围，或者如果该月的日期无效

from

public static MonthDay  from(TemporalAccessor  temporal)
            

从时间对象中获取 MonthDay 的实例。

这将根据指定的时间获得月日。 TemporalAccessor 表示一组任意的日期和时间信息，该工厂将其转换为 MonthDay 的一个实例。

转换提取 MONTH_OF_YEAR 和 DAY_OF_MONTH 字段。仅当时间对象具有 ISO 年表或可以转换为 LocalDate 时才允许提取。

此方法与功能接口 TemporalQuery 的签名相匹配，允许它通过方法参考 MonthDay::from 用作查询。

参数：

temporal - 要转换的时间对象，不为空

返回：

月日，不为空

抛出：

DateTimeException - 如果无法转换为 MonthDay

parse

public static MonthDay  parse(CharSequence  text)
            

从 --12-03 等文本字符串中获取 MonthDay 的实例。

该字符串必须表示有效的月-日。格式为 --MM-dd 。

参数：

text - 要解析的文本，例如“--12-03”，不为空

返回：

解析的月日，不为空

抛出：

DateTimeParseException - 如果无法解析文本

parse

public static MonthDay  parse(CharSequence  text, DateTimeFormatter  formatter)
            

使用特定格式化程序从文本字符串中获取 MonthDay 的实例。

使用格式化程序解析文本，返回月-日。

参数：

text - 要解析的文本，不为空

formatter - 要使用的格式化程序，不为空

返回：

解析的月日，不为空

抛出：

DateTimeParseException - 如果无法解析文本

isSupported

public boolean isSupported(TemporalField  field)
            

检查是否支持指定的字段。

这将检查是否可以查询指定字段的月日。如果为 false，则调用 range 和 get 方法将抛出异常。

如果该字段是一个ChronoField 那么查询就在这里实现。支持的字段是：

• MONTH_OF_YEAR
• YEAR

所有其他 ChronoField 实例将返回 false。

如果该字段不是 ChronoField ，则通过调用 TemporalField.isSupportedBy(TemporalAccessor) 传递 this 作为参数来获得此方法的结果。字段是否支持由字段决定。

指定者：

isSupported 在接口 TemporalAccessor 中

参数：

field - 要检查的字段，null 返回 false

返回：

如果该月-日支持该字段，则为 true，否则为 false

range

public ValueRange  range(TemporalField  field)
            

获取指定字段的有效值范围。

范围对象表示字段的最小和最大有效值。这个月-日用于增强返回范围的准确性。如果由于不支持该字段或其他原因而无法返回范围，则会抛出异常。

如果该字段是一个ChronoField 那么查询就在这里实现。 supported fields 将返回适当的范围实例。所有其他 ChronoField 实例将抛出 UnsupportedTemporalTypeException 。

如果该字段不是 ChronoField ，则通过调用 TemporalField.rangeRefinedBy(TemporalAccessor) 传递 this 作为参数来获得此方法的结果。能否获取范围由字段决定。

指定者：

range 在接口 TemporalAccessor 中

参数：

field - 查询范围的字段，不为空

返回：

该字段的有效值范围，不为空

抛出：

DateTimeException - 如果无法获得该字段的范围

UnsupportedTemporalTypeException - 如果不支持该字段

get

public int get(TemporalField  field)
            

从此月-日获取指定字段的值作为 int 。

这将在本月-日查询指定字段的值。返回值将始终在该字段的有效值范围内。如果由于不支持该字段或其他原因而无法返回该值，则会抛出异常。

如果该字段是一个ChronoField 那么查询就在这里实现。 supported fields 将根据这个月-日返回有效值。所有其他 ChronoField 实例将抛出 UnsupportedTemporalTypeException 。

如果该字段不是 ChronoField ，则通过调用 TemporalField.getFrom(TemporalAccessor) 传递 this 作为参数来获得此方法的结果。能否获取到该值，该值代表什么，由字段决定。

指定者：

get 在接口 TemporalAccessor 中

参数：

field - 要获取的字段，不为空

返回：

该字段的值

抛出：

DateTimeException - 如果无法获取该字段的值或该值超出该字段的有效值范围

UnsupportedTemporalTypeException - 如果不支持该字段或值的范围超过 int

ArithmeticException - 如果发生数字溢出

getLong

public long getLong(TemporalField  field)
            

从此月-日获取指定字段的值作为 long 。

这将在本月-日查询指定字段的值。如果由于不支持该字段或其他原因而无法返回该值，则会抛出异常。

如果该字段是一个ChronoField 那么查询就在这里实现。 supported fields 将根据这个月-日返回有效值。所有其他 ChronoField 实例将抛出 UnsupportedTemporalTypeException 。

如果该字段不是 ChronoField ，则通过调用 TemporalField.getFrom(TemporalAccessor) 传递 this 作为参数来获得此方法的结果。能否获取到该值，该值代表什么，由字段决定。

指定者：

getLong 在接口 TemporalAccessor 中

参数：

field - 要获取的字段，不为空

返回：

该字段的值

抛出：

DateTimeException - 如果无法获得该字段的值

UnsupportedTemporalTypeException - 如果不支持该字段

ArithmeticException - 如果发生数字溢出

getMonthValue

public int getMonthValue()
            

获取从 1 到 12 的月份字段。

此方法将月份作为 int 从 1 到 12 返回。如果通过调用 getMonth() 使用枚举 Month ，应用程序代码通常会更清晰。

返回：

一年中的月份，从 1 到 12

参见：

• getMonth()

getMonth

public Month  getMonth()
            

使用 Month 枚举获取月份字段。

此方法返回月份的枚举 Month 。这避免混淆 int 值的含义。如果您需要访问原始 int 值，则枚举会提供 int value 。

返回：

月份，不为空

参见：

• getMonthValue()

getDayOfMonth

public int getDayOfMonth()
            

获取日期字段。

此方法返回日期的原始 int 值。

返回：

一个月中的第几天，从 1 到 31

isValidYear

public boolean isValidYear(int year)
            

检查年份是否对该月-日有效。

此方法检查此月和日以及输入的年份是否构成有效日期。这只能在 2 月 29 日返回 false。

参数：

year - 验证年份

返回：

如果年份对本月-日有效，则为真

参见：

• Year.isValidMonthDay(MonthDay)

withMonth

public MonthDay  withMonth(int month)
            

返回此 MonthDay 的副本，其中月份已更改。

这将返回指定月份的月日。如果指定月份的日期无效，则该日期将调整为最后一个有效的日期。

此实例是不可变的，不受此方法调用的影响。

参数：

month - 在返回的月份中设置的月份，从 1（一月）到 12（十二月）

返回：

a MonthDay 基于请求月份的月日，不为空

抛出：

DateTimeException - 如果月份值无效

with

public MonthDay  with(Month  month)
            

返回此 MonthDay 的副本，其中月份已更改。

这将返回指定月份的月日。如果指定月份的日期无效，则该日期将调整为最后一个有效的日期。

此实例是不可变的，不受此方法调用的影响。

参数：

month - 在返回的月份中设置的月份，不为空

返回：

a MonthDay 基于请求月份的月日，不为空

withDayOfMonth

public MonthDay  withDayOfMonth(int dayOfMonth)
            

返回此 MonthDay 的副本，其中日期已更改。

这将返回具有指定日期的月日。如果该月的日期无效，则会抛出异常。

此实例是不可变的，不受此方法调用的影响。

参数：

dayOfMonth - 在返回月日中设置的月中日，从 1 到 31

返回：

a MonthDay 基于这个月日和请求的日期，不为空

抛出：

DateTimeException - 如果日期值无效，或者该月的日期无效

query

public <R> R query(TemporalQuery <R> query)
            

使用指定查询查询本月-日。

这使用指定的查询策略对象查询这个月-日。 TemporalQuery 对象定义了用于获取结果的逻辑。阅读查询文档以了解此方法的结果。

此方法的结果是通过对指定查询调用 TemporalQuery.queryFrom(TemporalAccessor) 方法并将 this 作为参数传递来获得的。

指定者：

query 在接口 TemporalAccessor 中

类型参数：

R - 结果的类型

参数：

query - 要调用的查询，不为空

返回：

查询结果，可能返回null（由查询定义）

抛出：

DateTimeException - 如果无法查询（由查询定义）

ArithmeticException - 如果发生数字溢出（由查询定义）

adjustInto

public Temporal  adjustInto(Temporal  temporal)
            

调整指定的时间对象以具有此月-日。

这将返回一个与输入具有相同可观察类型的时间对象，其中月份和日期更改为与此相同。

调整相当于使用Temporal.with(TemporalField, long) 两次，将ChronoField.MONTH_OF_YEAR 和ChronoField.DAY_OF_MONTH 作为字段传递。如果指定的时间对象不使用 ISO 日历系统，则抛出 DateTimeException。

在大多数情况下，使用 Temporal.with(TemporalAdjuster) 反转调用模式会更清楚：

  // these two lines are equivalent, but the second approach is recommended
  temporal = thisMonthDay.adjustInto(temporal);
  temporal = temporal.with(thisMonthDay);
 

此实例是不可变的，不受此方法调用的影响。

指定者：

adjustInto 在接口 TemporalAdjuster 中

参数：

temporal - 要调整的目标对象，不为空

返回：

调整后的对象，不为空

抛出：

DateTimeException - 如果无法进行调整

ArithmeticException - 如果发生数字溢出

format

public String  format(DateTimeFormatter  formatter)
            

使用指定的格式化程序格式化这个月日。

这个月-日将传递给格式化程序以生成一个字符串。

参数：

formatter - 要使用的格式化程序，不为空

返回：

格式化的月日字符串，不为空

抛出：

DateTimeException - 如果在打印过程中发生错误

atYear

public LocalDate  atYear(int year)
            

将这个月-日与年份结合起来创建一个 LocalDate 。

这将返回一个 LocalDate 从这个月日和指定的年份形成。

如果年份不是闰年，结果日期中的 2 月 29 日将调整为 2 月 28 日。

此实例是不可变的，不受此方法调用的影响。

参数：

year - 使用的年份，从 MIN_YEAR 到 MAX_YEAR

返回：

由本月日和指定年份组成的本地日期，不为空

抛出：

DateTimeException - 如果年份超出有效年份范围

compareTo

public int compareTo(MonthDay  other)
            

将这个月日与另一个月日进行比较。

比较首先基于月的值，然后基于日的值。正如 Comparable 所定义的那样，它“与等于一致”。

指定者：

compareTo 在接口 Comparable<MonthDay> 中

参数：

other - 要比较的其他月日，不为空

返回：

比较值，小于则为负，大于则为正

isAfter

public boolean isAfter(MonthDay  other)
            

检查这个月日是否在指定的月日之后。

参数：

other - 要比较的其他月日，不为空

返回：

如果这是在指定的月日之后，则为真

isBefore

public boolean isBefore(MonthDay  other)
            

检查这个月日是否在指定的月日之前。

参数：

other - 要比较的其他月日，不为空

返回：

如果这一点在指定的月日之前，则为真

equals

public boolean equals(Object  obj)
            

检查这个月日是否等于另一个月日。

比较是根据一年中月日的时间线位置。

重写：

equals 在类 Object 中

参数：

obj - 要检查的对象，null 返回 false

返回：

如果这等于另一个月日，则为真

参见：

• Object.hashCode()
• HashMap

hashCode

public int hashCode()
            

这个月-日的哈希码。

重写：

hashCode 在类 Object 中

返回：

合适的哈希码

参见：

• Object.equals(java.lang.Object)
• System.identityHashCode(java.lang.Object)

toString

public String  toString()
            

将这个月-日输出为 String ，例如 --12-03 。

输出将采用 --MM-dd 格式：

重写：

toString 在类 Object 中

返回：

这个月日的字符串表示，不为空