Module java.base
Package java.time

Class Year

java.lang.Object
java.time.Year
所有已实现的接口:
Serializable, Comparable<Year>, Temporal, TemporalAccessor, TemporalAdjuster
public final class Year extends Object implements Temporal, TemporalAdjuster, Comparable<Year>, Serializable
ISO-8601日历系统中的一年，例如2007。

Year是一个不可变的日期时间对象，表示一年。可以获取任何可以从一年派生的字段。

请注意，ISO年表仅在现代年份中与格里高利-朱利安系统中的年份对齐。俄罗斯的部分地区直到1920年才转换为现代的格里高利/ISO规则。因此，必须谨慎处理历史年份。

此类不存储或表示月份、日期、时间或时区。例如，值“2007”可以存储在一个Year中。

此类表示的年份遵循ISO-8601标准，并使用推测编号系统。年份1之前是年份0，然后是年份-1。

ISO-8601日历系统是当今世界大部分地区使用的现代公民日历系统。它等同于推测的格里高利日历系统，其中适用于所有时间的闰年规则。对于今天编写的大多数应用程序，ISO-8601规则完全合适。但是，任何需要使用历史日期并要求它们准确的应用程序将发现ISO-8601方法不适用。

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

实现要求:
此类是不可变的且线程安全的。
自版本:
1.8
参见:

  • Field Details

    • MIN_VALUE

      public static final int MIN_VALUE
      支持的最小年份为'-999,999,999'。
      参见:

    • MAX_VALUE

      public static final int MAX_VALUE
      支持的最大年份为'+999,999,999'。
      参见:

  • Method Details

    • now

      public static Year now()
      从默认时区的系统时钟获取当前年份。

      这将查询默认时区中的系统时钟以获取当前年份。

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

      返回:
      使用系统时钟和默认时区获取的当前年份，非空

    • now

      public static Year now(ZoneId zone)
      从指定时区的系统时钟获取当前年份。

      这将查询系统时钟以获取当前年份。指定时区避免依赖默认时区。

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

      参数:
      zone - 要使用的区域ID，非空
      返回:
      使用系统时钟获取的当前年份，非空

    • now

      public static Year now(Clock clock)
      从指定时钟获取当前年份。

      这将查询指定的时钟以获取当前年份。使用此方法允许使用替代时钟进行测试。可以使用依赖注入引入替代时钟。

      参数:
      clock - 要使用的时钟，非空
      返回:
      当前年份，非空

    • of

      public static Year of(int isoYear)
      获取Year的实例。

      此方法接受来自推测ISO日历系统的年份值。

      公元2年代/公元是由2表示。
      公元1年代/公元是由1表示。
      公元前1年代/公元前是由0表示。
      公元前2年代/公元前是由-1表示。

      参数:
      isoYear - 要表示的ISO推测年份，从MIN_VALUE到MAX_VALUE
      返回:
      年份，非空
      抛出:
      DateTimeException - 如果字段无效

    • from

      public static Year from(TemporalAccessor temporal)
      从一个时间对象获取Year的实例。

      根据指定的时间获取一个年份。一个TemporalAccessor表示一组任意的日期和时间信息，此工厂将其转换为Year的实例。

      转换提取年份字段。只有在时间对象具有ISO年表，或者可以转换为LocalDate时才允许提取。

      此方法与函数接口TemporalQuery的签名匹配，允许通过方法引用Year::from来使用它作为查询。

      参数:
      temporal - 要转换的时间对象，非空
      返回:
      年份，非空
      抛出:
      DateTimeException - 如果无法转换为Year

    • parse

      public static Year parse(CharSequence text)
      从文本字符串（如2007）获取Year的实例。

      字符串必须表示一个有效的年份。

      参数:
      text - 要解析的文本，例如"2007"，非空
      返回:
      解析的年份，非空
      抛出:
      DateTimeParseException - 如果无法解析文本

    • parse

      public static Year parse(CharSequence text, DateTimeFormatter formatter)
      使用特定格式化程序从文本字符串获取Year的实例。

      使用格式化程序解析文本，返回一个年份。

      参数:
      text - 要解析的文本，非空
      formatter - 要使用的格式化程序，非空
      返回:
      解析的年份，非空
      抛出:
      DateTimeParseException - 如果无法解析文本

    • isLeap

      public static boolean isLeap(long year)
      检查年份是否是闰年，根据ISO历法系统规则。

      此方法适用于整个时间线上的闰年当前规则。一般来说，如果年份能被4整除，则是闰年。然而，能被100整除的年份不是闰年，但能被400整除的年份是闰年。

      例如，1904年是闰年，因为能被4整除。1900年不是闰年，因为能被100整除，但2000年是闰年，因为能被400整除。

      计算是推测性的 - 将相同规则应用到遥远的未来和过去。这在历史上是不准确的，但对于ISO-8601标准是正确的。

      参数:
      year - 要检查的年份
      返回:
      如果年份是闰年则返回true，否则返回false

    • getValue

      public int getValue()
      获取年份值。

      此方法返回的年份是根据get(YEAR)推测性的。

      返回:
      年份，MIN_VALUE 到 MAX_VALUE

    • isSupported

      public boolean isSupported(TemporalField field)
      检查指定字段是否受支持。

      这将检查是否可以查询指定字段的此年份。如果返回false，则调用range、get和with(TemporalField, long)方法将抛出异常。

      如果字段是ChronoField，则在此处实现查询。支持的字段包括：

    • YEAR_OF_ERA
    • YEAR
    • ERA
      • 所有其他ChronoField实例将返回false。

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

      指定者:
      isSupported 在接口 TemporalAccessor
      参数:
      field - 要检查的字段，null返回false
      返回:
      如果此年份支持该字段则返回true，否则返回false

    • isSupported

      public boolean isSupported(TemporalUnit unit)
      检查指定单位是否受支持。

      这将检查是否可以将指定单位添加到此年份或从中减去。如果返回false，则调用plus(long, TemporalUnit)和minus方法将抛出异常。

      如果单位是ChronoUnit，则在此处实现查询。支持的单位包括：

    • YEARS
    • DECADES
    • CENTURIES
    • MILLENNIA
    • ERAS
      • 所有其他ChronoUnit实例将返回false。

      如果单位不是ChronoUnit，则通过调用TemporalUnit.isSupportedBy(Temporal)传递this作为参数来获取此方法的结果。单位是否受支持由单位决定。

      指定者:
      isSupported 在接口 Temporal
      参数:
      unit - 要检查的单位，null返回false
      返回:
      如果可以添加/减去该单位则返回true，否则返回false

    • range

      public ValueRange range(TemporalField field)
      获取指定字段的有效值范围。

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

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

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

      指定者:
      range 在接口 TemporalAccessor
      参数:
      field - 要查询范围的字段，不能为空
      返回:
      字段的有效值范围，不能为空
      抛出:
      DateTimeException - 如果无法获取字段的范围
      UnsupportedTemporalTypeException - 如果不支持该字段

    • get

      public int get(TemporalField field)
      从此年份获取指定字段的值作为int。

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

      如果字段是ChronoField，则在此处实现查询。支持的字段将根据此年份返回有效值。所有其他ChronoField实例将抛出UnsupportedTemporalTypeException。

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

      指定者:
      get 在接口 TemporalAccessor
      参数:
      field - 要获取的字段，不能为空
      返回:
      字段的值
      抛出:
      DateTimeException - 如果无法获取字段的值或值超出字段的有效值范围
      UnsupportedTemporalTypeException - 如果不支持该字段或值范围超出int
      ArithmeticException - 如果发生数值溢出

    • getLong

      public long getLong(TemporalField field)
      从此年份获取指定字段的值作为long。

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

      如果字段是ChronoField，则在此处实现查询。支持的字段将根据此年份返回有效值。所有其他ChronoField实例将抛出UnsupportedTemporalTypeException。

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

      指定者:
      getLong 在接口 TemporalAccessor
      参数:
      field - 要获取的字段，不能为空
      返回:
      字段的值
      抛出:
      DateTimeException - 如果无法获取字段的值
      UnsupportedTemporalTypeException - 如果不支持该字段
      ArithmeticException - 如果发生数值溢出

    • isLeap

      public boolean isLeap()
      检查年份是否是闰年，根据ISO历法系统规则。

      此方法适用于整个时间线上的闰年当前规则。一般来说，如果年份能被4整除，则是闰年。然而，能被100整除的年份不是闰年，但能被400整除的年份是闰年。

      例如，1904年是闰年，因为能被4整除。1900年不是闰年，因为能被100整除，但2000年是闰年，因为能被400整除。

      计算是推测性的 - 将相同规则应用到遥远的未来和过去。这在历史上是不准确的，但对于ISO-8601标准是正确的。

      返回:
      如果年份是闰年则返回true，否则返回false

    • isValidMonthDay

      public boolean isValidMonthDay(MonthDay monthDay)
      检查月日是否对此年份有效。

      此方法检查此年份和输入的月份和日期是否形成有效日期。

      参数:
      monthDay - 要验证的月日，null返回false
      返回:
      如果月份和日期对此年份有效则返回true

    • length

      public int length()
      获取此年份的天数长度。
      返回:
      此年份的天数长度，365或366

    • with

      public Year with(TemporalAdjuster adjuster)
      返回调整后的年份的副本。

      这将返回一个基于当前年份的Year，并根据指定的调整策略对象进行调整。通过阅读调整器的文档，了解将进行何种调整。

      此方法的结果是通过在指定的调整器上调用TemporalAdjuster.adjustInto(Temporal)方法，并将this作为参数传递来获得的。

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

      指定者：
      with 在接口 Temporal中
      参数：
      adjuster - 要使用的调整器，不能为空
      返回：
      基于this进行调整后的Year，不能为空
      抛出：
      DateTimeException - 如果无法进行调整
      ArithmeticException - 如果发生数值溢出

    • with

      public Year with(TemporalField field, long newValue)
      返回将指定字段设置为新值后的年份的副本。

      这将返回一个基于当前年份的Year，并将指定字段的值更改为新值。如果无法设置值，因为不支持该字段或出于其他原因，则会抛出异常。

      如果字段是一个ChronoField，则在此处实现调整。支持的字段行为如下：

      • YEAR_OF_ERA - 返回具有指定年份的Year。纪元将保持不变。
      • YEAR - 返回具有指定年份的Year。这将完全替换日期，并等效于of(int)。
      • ERA - 返回具有指定纪元的Year。年份将保持不变。

      在所有情况下，如果新值超出字段的有效值范围，则将抛出DateTimeException。

      所有其他ChronoField实例将抛出UnsupportedTemporalTypeException。

      如果字段不是ChronoField，则通过调用TemporalField.adjustInto(Temporal, long)方法并将this作为参数传递来获得此方法的结果。在这种情况下，字段确定是否以及如何调整时刻。

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

      指定者：
      with 在接口 Temporal中
      参数：
      field - 要在结果中设置的字段，不能为空
      newValue - 结果中字段的新值
      返回：
      基于this进行设置指定字段后的Year，不能为空
      抛出：
      DateTimeException - 如果无法设置字段
      UnsupportedTemporalTypeException - 如果不支持该字段
      ArithmeticException - 如果发生数值溢出

    • plus

      public Year plus(TemporalAmount amountToAdd)
      返回将指定数量添加后的年份的副本。

      这将返回一个基于当前年份的Year，并添加指定的数量。该数量通常是Period，但也可以是实现TemporalAmount接口的任何其他类型。

      通过调用TemporalAmount.addTo(Temporal)将计算委托给数量对象。数量的实现可以以任何希望的方式实现加法，但通常会回调plus(long, TemporalUnit)。请查阅数量实现的文档，以确定是否可以成功添加。

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

      指定者：
      plus 在接口 Temporal中
      参数：
      amountToAdd - 要添加的数量，不能为空
      返回：
      基于当前年份进行添加后的Year，不能为空
      抛出：
      DateTimeException - 如果无法进行添加
      ArithmeticException - 如果发生数值溢出

    • plus

      public Year plus(long amountToAdd, TemporalUnit unit)
      返回将指定数量添加后的年份的副本。

      这将返回一个基于当前年份的Year，并以单位的形式添加数量。如果无法添加数量，因为不支持该单位或出于其他原因，则会抛出异常。

      如果字段是一个ChronoUnit，则在此处实现添加。支持的字段行为如下：

      • YEARS - 返回添加指定年数后的Year。这等效于plusYears(long)。
      • DECADES - 返回添加指定数十年后的Year。这等效于调用将数量乘以10的plusYears(long)。
      • CENTURIES - 返回添加指定世纪数后的Year。这等效于调用将数量乘以100的plusYears(long)。
      • MILLENNIA - 返回添加指定千年数后的Year。这等效于调用将数量乘以1,000的plusYears(long)。
      • ERAS - 返回添加指定纪元数后的Year。仅支持两个纪元，因此数量必须为一、零或负一。如果数量非零，则更改年份，使得年份-纪元保持不变。

      所有其他ChronoUnit实例将抛出UnsupportedTemporalTypeException。

      如果字段不是ChronoUnit，则通过调用TemporalUnit.addTo(Temporal, long)方法并将this作为参数传递来获得此方法的结果。在这种情况下，单位确定是否以及如何执行添加。

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

      指定者：
      plus 在接口 Temporal中
      参数：
      amountToAdd - 要添加到结果的单位数量，可以为负数
      unit - 要添加的数量的单位，不能为空
      返回：
      基于当前年份进行添加后的Year，不能为空
      抛出：
      DateTimeException - 如果无法进行添加
      UnsupportedTemporalTypeException - 如果不支持该单位
      ArithmeticException - 如果发生数值溢出

    • plusYears

      public Year plusYears(long yearsToAdd)
      返回将指定数量年份添加后的Year的副本。

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

      参数：
      yearsToAdd - 要添加的年数，可以为负数
      返回：
      基于当前年份进行添加后的Year，不能为空
      抛出：
      DateTimeException - 如果结果超出支持的范围

    • minus

      public Year minus(TemporalAmount amountToSubtract)
      返回将指定数量减去后的年份的副本。

      这将返回一个基于当前年份的Year，并减去指定的数量。该数量通常是Period，但也可以是实现TemporalAmount接口的任何其他类型。

      通过调用TemporalAmount.subtractFrom(Temporal)将计算委托给数量对象。数量的实现可以以任何希望的方式实现减法，但通常会回调minus(long, TemporalUnit)。请查阅数量实现的文档，以确定是否可以成功减去。

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

      指定者：
      minus 在接口 Temporal中
      参数：
      amountToSubtract - 要减去的数量，不能为空
      返回：
      基于当前年份进行减去后的Year，不能为空
      抛出：
      DateTimeException - 如果无法进行减法
      ArithmeticException - 如果发生数值溢出

    • minus

      public Year minus(long amountToSubtract, TemporalUnit unit)
      返回减去指定数量后的今年的副本。

      这将返回一个基于此年份的Year，减去指定单位的数量。如果无法减去数量，因为不支持该单位或其他原因，将抛出异常。

      此方法等效于使用plus(long, TemporalUnit)并取负数的方式。查看该方法以获取有关加法（因此也是减法）如何工作的完整描述。

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

      指定者：
      minus 在接口 Temporal
      参数：
      amountToSubtract - 要从结果中减去的单位数量，可以为负数
      unit - 要减去的数量单位，不能为空
      返回：
      基于此年份的Year，减去指定数量后的结果，不能为空
      抛出：
      DateTimeException - 如果无法进行减法运算
      UnsupportedTemporalTypeException - 如果不支持该单位
      ArithmeticException - 如果发生数值溢出

    • minusYears

      public Year minusYears(long yearsToSubtract)
      返回减去指定年数后的此Year的副本。

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

      参数：
      yearsToSubtract - 要减去的年数，可以为负数
      返回：
      基于此年份的Year，减去年份后的结果，不能为空
      抛出：
      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.YEAR作为字段。如果指定的时间对象不使用ISO日历系统，则会抛出DateTimeException。

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

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

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

      指定者：
      adjustInto 在接口 TemporalAdjuster
      参数：
      temporal - 要调整的目标对象，不能为空
      返回：
      调整后的对象，不能为空
      抛出：
      DateTimeException - 如果无法进行调整
      ArithmeticException - 如果发生数值溢出

    • until

      public long until(Temporal endExclusive, TemporalUnit unit)
      计算以指定单位的时间为单位直到另一年的时间量。

      这将计算两个Year对象之间的时间量，以单个TemporalUnit为单位。起始点和结束点是this和指定的年份。如果结束在开始之前，则结果将为负数。传递给此方法的Temporal将使用from(TemporalAccessor)转换为Year。例如，可以使用startYear.until(endYear, DECADES)来计算两年之间的十年数。

      计算返回一个整数，表示两年之间完整单位的数量。例如，2012年和2031年之间的十年数将只有一个十年，因为距离两个十年还差一年。

      有两种等效的使用此方法的方式。第一种是调用此方法。第二种是使用TemporalUnit.between(Temporal, Temporal)：

         // 这两行是等效的
   amount = start.until(end, YEARS);
   amount = YEARS.between(start, end);
      应根据哪种方式使代码更易读来进行选择。

      此方法中实现了ChronoUnit的计算。支持单位YEARS、DECADES、CENTURIES、MILLENNIA和ERAS。其他ChronoUnit值将抛出异常。

      如果单位不是ChronoUnit，则通过调用TemporalUnit.between(Temporal, Temporal)传递this作为第一个参数和转换后的输入时间作为第二个参数来获得此方法的结果。

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

      指定者：
      until 在接口 Temporal
      参数：
      endExclusive - 结束日期（不包括），将转换为Year，不能为空
      unit - 用于测量时间量的单位，不能为空
      返回：
      此年份和结束年份之间的时间量
      抛出：
      DateTimeException - 如果无法计算数量，或者无法将结束时间转换为Year
      UnsupportedTemporalTypeException - 如果不支持该单位
      ArithmeticException - 如果发生数值溢出

    • format

      public String format(DateTimeFormatter formatter)
      使用指定的格式化程序格式化此年份。

      此年份将传递给格式化程序以生成一个字符串。

      参数：
      formatter - 要使用的格式化程序，不能为空
      返回：
      格式化后的年份字符串，不能为空
      抛出：
      DateTimeException - 在打印过程中发生错误

    • atDay

      public LocalDate atDay(int dayOfYear)
      将此年份与一年中的某一天组合以创建LocalDate。

      这将返回一个由此年份和指定的一年中的某一天组成的LocalDate。

      一年中的第366天仅在闰年中有效。

      参数：
      dayOfYear - 要使用的一年中的某一天，从1到365-366
      返回：
      由此年份和指定年份的日期组成的本地日期，不能为空
      抛出：
      DateTimeException - 如果一年中的天数为零或更少，为366或大于等于366且此不是闰年

    • atMonth

      public YearMonth atMonth(Month month)
      将此年份与月份组合以创建YearMonth。

      这将返回一个由此年份和指定月份组成的YearMonth。年份和月份的所有可能组合都是有效的。

      此方法可作为生成日期链的一部分使用：

        LocalDate date = year.atMonth(month).atDay(day);
      参数：
      month - 要使用的月份，不能为空
      返回：
      由此年份和指定月份组成的年份-月份，不能为空

    • atMonth

      public YearMonth atMonth(int month)
      将此年份与月份组合以创建YearMonth。

      这将返回一个由此年份和指定月份组成的YearMonth。年份和月份的所有可能组合都是有效的。

      此方法可作为生成日期链的一部分使用：

        LocalDate date = year.atMonth(month).atDay(day);
      参数：
      month - 要使用的月份，从1（一月）到12（十二月）
      返回：
      由此年份和指定月份组成的年份-月份，不能为空
      抛出：
      DateTimeException - 如果月份无效

    • atMonthDay

      public LocalDate atMonthDay(MonthDay monthDay)
      将今年与一个月-日组合起来创建一个LocalDate。

      返回一个由今年和指定的月-日组成的LocalDate。

      如果今年不是闰年，则2月29日将被调整为2月28日。

      参数:
      monthDay - 要使用的月-日，不能为空
      返回:
      由今年和指定的月-日组成的本地日期，不能为空

    • compareTo

      public int compareTo(Year other)
      将今年与另一年进行比较。

      比较基于年份的值。它是“与equals一致”的，如Comparable中定义的。

      指定者:
      compareTo 在接口 Comparable<Year>
      参数:
      other - 要比较的另一年，不能为空
      返回:
      比较值，如果这个在other之前则小于零，如果相等则为零，如果这个在other之后则大于零
      参见:

    • isAfter

      public boolean isAfter(Year other)
      检查这个年份是否在指定年份之后。
      参数:
      other - 要比较的另一年，不能为空
      返回:
      如果这个在指定年份之后则为true

    • isBefore

      public boolean isBefore(Year other)
      检查这个年份是否在指定年份之前。
      参数:
      other - 要比较的另一年，不能为空
      返回:
      如果这个在指定年份之前则为true

    • equals

      public boolean equals(Object obj)
      检查这个年份是否等于另一年。

      比较基于年份的时间线位置。

      覆盖:
      equals 在类 Object
      参数:
      obj - 要检查的对象，如果为null则返回false
      返回:
      如果这个等于另一年则为true
      参见:

    • hashCode

      public int hashCode()
      这个年份的哈希码。
      覆盖:
      hashCode 在类 Object
      返回:
      一个适当的哈希码
      参见:

    • toString

      public String toString()
      将这个年份输出为一个String。
      覆盖:
      toString 在类 Object
      返回:
      这个年份的字符串表示，不能为空