Module java.base

Package java.time.chrono

Interface Era

所有超接口:

TemporalAccessor, TemporalAdjuster

所有已知实现类:

HijrahEra, IsoEra, JapaneseEra, MinguoEra, ThaiBuddhistEra

       public interface Era extends TemporalAccessor, TemporalAdjuster
      

时间线上的一个时代。

大多数日历系统将时间线分为两个时代，有一个将时间线分为多个时代的日历系统，比如每位领导人的统治时代。在所有情况下，时代在概念上是时间线的最大划分。每个年表都定义了已知时代和一个Chronology.eras来获取有效时代。

例如，泰国佛教日历系统将时间分为两个时代，一个是某个特定日期之前，一个是之后。相比之下，日本日历系统为每位天皇的统治设立一个时代。

Era的实例可以使用==运算符进行比较。

实现要求:

必须小心实现此接口，以确保其他类能够正确运行。所有实现必须是单例 - final、不可变且线程安全。建议尽可能使用枚举。

自版本:

1.8

Method Summary

Modifier and Type	Method	Description
default Temporal	adjustInto(Temporal temporal)	调整指定的时间对象，使其具有与此对象相同的时代。
default int	get(TemporalField field)	获取此时代中指定字段的值作为int。
default String	getDisplayName(TextStyle style, Locale locale)	获取此时代的文本表示。
default long	getLong(TemporalField field)	获取此时代中指定字段的值作为long。
int	getValue()	获取与年表定义的时代相关联的数值。
default boolean	isSupported(TemporalField field)	检查是否支持指定的字段。
default <R> R	query(TemporalQuery<R> query)	使用指定查询查询此时代。
default ValueRange	range(TemporalField field)	获取指定字段的有效值范围。

Method Details

getValue

             int getValue()
            

获取与年表定义的时代相关联的数值。每个年表都定义了预定义的时代和列出年表时代的方法。

所有字段，包括时代，都有一个关联的数值。时代的数值含义由年表根据以下原则确定：

• 1970-01-01（ISO）时代的值为1。
• 后续时代具有依次增加的值。
• 先前时代具有依次减小的值，可能为负值。

返回:

数字时代值

isSupported

             default boolean isSupported(TemporalField field)
            

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

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

如果字段是ChronoField，则在此处实现查询。ERA字段返回true。所有其他ChronoField实例将返回false。

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

指定者:

isSupported 在接口 TemporalAccessor中

参数:

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

返回:

如果此时代支持该字段，则为true，否则为false

range

             default ValueRange range(TemporalField field)
            

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

范围对象表示字段的最小和最大有效值。此时代用于增强返回范围的准确性。如果无法返回范围，因为不支持该字段或出于其他原因，将抛出异常。

如果字段是ChronoField，则在此处实现查询。ERA字段返回范围。所有其他ChronoField实例将抛出UnsupportedTemporalTypeException。

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

默认实现必须返回ERA的范围从零到一，适用于像ISO这样的两个时代日历系统。

指定者:

range 在接口 TemporalAccessor中

参数:

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

返回:

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

抛出:

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

UnsupportedTemporalTypeException - 如果不支持该单位

get

             default int get(TemporalField field)
            

获取此时代中指定字段的值作为int。

查询此时代以获取指定字段的值。返回的值将始终在字段的有效值范围内。如果无法返回值，因为不支持该字段或出于其他原因，将抛出异常。

如果字段是ChronoField，则在此处实现查询。ERA字段返回时代的值。所有其他ChronoField实例将抛出UnsupportedTemporalTypeException。

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

指定者:

get 在接口 TemporalAccessor中

参数:

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

返回:

字段的值

抛出:

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

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

ArithmeticException - 如果发生数值溢出

getLong

             default long getLong(TemporalField field)
            

获取此时代中指定字段的值作为long。

查询此时代以获取指定字段的值。如果无法返回值，因为不支持该字段或出于其他原因，将抛出异常。

如果字段是ChronoField，则在此处实现查询。ERA字段返回时代的值。所有其他ChronoField实例将抛出UnsupportedTemporalTypeException。

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

指定者:

getLong 在接口 TemporalAccessor中

参数:

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

返回:

字段的值

抛出:

DateTimeException - 如果无法获取字段的值

UnsupportedTemporalTypeException - 如果不支持该字段

ArithmeticException - 如果发生数值溢出

query

             default <R> R query(TemporalQuery<R> query)
            

使用指定的查询查询此时代。

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

通过在指定的查询上调用TemporalQuery.queryFrom(TemporalAccessor)方法获取此方法的结果，传递this作为参数。

指定者:

query 在接口 TemporalAccessor中

类型参数:

R - 结果的类型

参数:

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

返回:

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

抛出:

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

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

adjustInto

             default Temporal adjustInto(Temporal temporal)
            

调整指定的时间对象，使其具有与此对象相同的纪元。

返回一个与输入相同可观察类型的时间对象，其纪元已更改为与此相同。

此调整等同于使用Temporal.with(TemporalField, long)传递ChronoField.ERA作为字段。

在大多数情况下，通过使用Temporal.with(TemporalAdjuster)来颠倒调用模式更清晰：

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

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

指定者:

adjustInto 在接口 TemporalAdjuster中

参数:

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

返回:

调整后的对象，不能为空

抛出:

DateTimeException - 如果无法进行调整

ArithmeticException - 如果发生数值溢出

getDisplayName

             default String getDisplayName(TextStyle style, Locale locale)
            

获取此纪元的文本表示。

返回用于标识纪元的文本名称，适合向用户展示。参数控制返回文本的样式和区域设置。

如果找不到文本映射，则返回数值。

API注释:

此默认实现适用于大多数实现。

参数:

style - 所需文本的样式，不能为空

locale - 要使用的区域设置，不能为空

返回:

纪元的文本值，不能为空