模块  java.base
软件包  java.time

Class Year

  • 实现的所有接口
    SerializableComparable<Year>TemporalTemporalAccessorTemporalAdjuster

    public final class Year
    extends Object
    implements Temporal, TemporalAdjuster, Comparable<Year>, Serializable
    ISO- 2007 ,例如2007

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

    请注意,ISO年表中的年份仅与格里高利 - 朱利安系统中的年份一致。 俄罗斯的部分地区直到1920年才转向现代格里高利/ ISO规则。因此,历史年代必须谨慎对待。

    此类不存储或表示月,日,时间或时区。 例如,值“2007”可以存储在Year

    本课程所代表的年份遵循ISO-8601标准并使用预警编号系统。 第1年之前是第0年,然后是第-1年。

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

    这是一个value-based班; Year实例上使用身份敏感操作(包括引用相等( == ),标识哈希码或同步)可能会产生不可预测的结果,应该避免使用。 equals方法应该用于比较。

    实现要求:
    这个类是不可变的和线程安全的。
    从以下版本开始:
    1.8
    另请参见:
    Serialized Form
    • 字段详细信息

      • MIN_VALUE

        public static final int MIN_VALUE
        支持的最低年份'-999,999,999'。
        另请参见:
        常数字段值
      • MAX_VALUE

        public static final int MAX_VALUE
        支持的最大年份,'+999,999,999'。
        另请参见:
        常数字段值
    • 方法详细信息

      • now

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

        这将在默认时区中查询system clock以获取当前年份。

        使用此方法将无法使用备用时钟进行测试,因为时钟是硬编码的。

        结果
        使用系统时钟和默认时区的当前年份,不为空
      • now

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

        这将查询system clock以获取当前年份。 指定时区可避免依赖于默认时区。

        使用此方法将无法使用备用时钟进行测试,因为时钟是硬编码的。

        参数
        zone - 要使用的区域ID,不为空
        结果
        使用系统时钟的当前年份,不为空
      • now

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

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

        参数
        clock - 要使用的时钟,不为空
        结果
        当年,不是空的
      • of

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

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

        2AD / CE年份为2。
        1AD / CE年份由1表示。
        1BC / BCE年份为0。
        2BC / BCE年份为-1。

        参数
        isoYear - ISO的代表性,从 MIN_VALUEMAX_VALUE
        结果
        这一年,不是空的
        异常
        DateTimeException - 如果该字段无效
      • from

        public static Year from​(TemporalAccessor temporal)
        从时态对象获得Year的实例。

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

        转换提取year字段。 仅当时态对象具有ISO年表,或者可以将其转换为LocalDate ,才允许提取。

        该方法匹配功能接口TemporalQuery的签名,允许其通过方法参考Year::from用作查询。

        参数
        temporal - 要转换的时态对象,而不是null
        结果
        这一年,不是空的
        异常
        DateTimeException - 如无法兑换成 Year
      • parse

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

        该字符串必须代表有效年份。 超出0000到9999范围的年份必须以加号或减号为前缀。

        参数
        text - 要解析的文本,例如“2007”,而不是null
        结果
        解析的年份,不是空的
        异常
        DateTimeParseException - 如果无法解析文本
      • parse

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

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

        参数
        text - 要解析的文本,而不是null
        formatter - 要使用的格式化程序,而不是null
        结果
        解析的年份,不是空的
        异常
        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) ,此方法返回的年份是get(YEAR)

        结果
        全年, MIN_VALUEMAX_VALUE
      • isSupported

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

        这将检查是否可以查询指定字段的今年。 如果是假,然后调用rangegetwith(TemporalField, long)方法会抛出异常。

        如果该字段是ChronoField则在此处执行查询。 支持的字段是:

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

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

        Specified by:
        isSupported在界面 TemporalAccessor
        参数
        字段 - 要检查的字段,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作为参数。 设备是否受支持由设备决定。

        Specified by:
        isSupported在界面 Temporal
        参数
        unit - 要检查的单位,null返回false
        结果
        如果可以添加/减去单位,则为true,否则为false
      • range

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

        范围对象表示字段的最小和最大有效值。 今年用于提高返回范围的准确性。 如果无法返回范围,因为不支持该字段或由于某些其他原因,将引发异常。

        如果该字段是ChronoField则在此处执行查询。 supported fields将返回适当的范围实例。 所有其他ChronoField实例将抛出UnsupportedTemporalTypeException

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

        Specified by:
        range in interface TemporalAccessor
        参数
        字段 - 要查询范围的字段,而不是null
        结果
        字段的有效值范围,不为null
        异常
        DateTimeException - 如果无法获得该字段的范围
        UnsupportedTemporalTypeException - 如果不支持该字段
      • get

        public int get​(TemporalField field)
        int获取今年指定字段的值。

        这将查询今年的指定字段的值。 返回的值将始终在该字段的有效值范围内。 如果无法返回该值,因为不支持该字段或由于某些其他原因,将引发异常。

        如果该字段是ChronoField则在此处执行查询。 supported fields将根据今年返回有效值。 所有其他ChronoField实例将抛出UnsupportedTemporalTypeException

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

        Specified by:
        get in interface TemporalAccessor
        参数
        字段 - 要获取的字段,而不是null
        结果
        该字段的值
        异常
        DateTimeException - 如果无法获取该字段的值或该值超出该字段的有效值范围
        UnsupportedTemporalTypeException - 如果不支持该字段或值范围超过 int
        ArithmeticException - 如果发生数字溢出
      • getLong

        public long getLong​(TemporalField field)
        long获取今年指定字段的值。

        这将查询今年的指定字段的值。 如果无法返回该值,因为不支持该字段或由于某些其他原因,将引发异常。

        如果该字段是ChronoField则在此处执行查询。 supported fields将根据今年返回有效值。 所有其他ChronoField实例将抛出UnsupportedTemporalTypeException

        如果该字段不是ChronoField ,则通过调用this作为参数调用TemporalField.getFrom(TemporalAccessor)获得此方法的结果。 是否可以获得该值以及该值表示的值由该字段确定。

        Specified by:
        getLong in interface TemporalAccessor
        参数
        字段 - 要获取的字段,而不是null
        结果
        该字段的值
        异常
        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作为参数)来获得此方法的结果。

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

        Specified by:
        with在界面 Temporal
        参数
        adjuster - 要使用的调整器,不为null
        结果
        a Year基于 this进行调整,不为空
        异常
        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作为参数。 在这种情况下,该字段确定是否以及如何调整瞬间。

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

        Specified by:
        with在界面 Temporal
        参数
        字段 - 要在结果中设置的字段,不为null
        newValue - 结果中字段的新值
        结果
        Year基于 this ,指定字段集,不为空
        异常
        DateTimeException - 如果无法设置该字段
        UnsupportedTemporalTypeException - 如果不支持该字段
        ArithmeticException - 如果发生数字溢出
      • plus

        public Year plus​(TemporalAmount amountToAdd)
        返回指定数量的今年副本。

        这将返回基于此值的Year ,并添加指定的金额。 金额通常为Period但可能是实现TemporalAmount界面的任何其他类型。

        通过调用TemporalAmount.addTo(Temporal)将计算委托给amount对象。 实施金额可以任意方式自由实施,但通常会回拨plus(long, TemporalUnit) 请参阅金额实施的文档,以确定是否可以成功添加。

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

        Specified by:
        plus在界面 Temporal
        参数
        amountToAdd - 要添加的金额,不为空
        结果
        基于今年的 Year加入,不为空
        异常
        DateTimeException - 如果无法添加
        ArithmeticException - 如果发生数字溢出
      • plus

        public Year plus​(long amountToAdd,
                         TemporalUnit unit)
        返回指定数量的今年副本。

        这将返回基于此的Year ,其中包含已添加单位的金额。 如果无法添加金额,因为不支持该单位或由于某些其他原因,则会引发异常。

        如果该字段是ChronoUnit则在此处实现添加。 支持的字段表现如下:

        • YEARS - 返回添加了指定年数的Year 这相当于plusYears(long)
        • DECADES - 返回已添加指定Year数的Year 这相当于调用plusYears(long) ,金额乘以10。
        • CENTURIES - 返回一个指定了几个世纪的Year 这相当于调用plusYears(long) ,金额乘以100。
        • MILLENNIA - 返回一个Year ,其中添加了指定的千年数。 这相当于调用plusYears(long) ,金额乘以1,000。
        • ERAS - 返回一个Year ,其中添加了指定的Year数。 仅支持两个时代,因此金额必须为一,零或负一。 如果金额不为零,则改变年份,使得年龄不变。

        所有其他ChronoUnit实例将抛出UnsupportedTemporalTypeException

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

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

        Specified by:
        plus在界面 Temporal
        参数
        amountToAdd - 要添加到结果中的单位数量可能为负数
        unit - 要添加的金额的单位,而不是空
        结果
        a 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)将计算委托给amount对象。 实现量可以任意方式自由实现减法,但通常会回调到minus(long, TemporalUnit) 请参阅金额实施的文档,以确定是否可以成功减去它。

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

        Specified by:
        minus在界面 Temporal
        参数
        amountToSubtract - 要减去的金额,而不是空
        结果
        基于今年减去的 Year ,不为空
        异常
        DateTimeException - 如果无法进行减法
        ArithmeticException - 如果发生数字溢出
      • minus

        public Year minus​(long amountToSubtract,
                          TemporalUnit unit)
        返回今年的副本,减去指定的金额。

        这将返回一个Year ,基于此值,减去单位的数量。 如果无法减去金额,因为不支持该单位或由于某些其他原因,则抛出异常。

        该方法相当于plus(long, TemporalUnit) ,其数量为负数 有关添加和减法如何工作的完整描述,请参阅该方法。

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

        Specified by:
        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作为参数。

        Specified by:
        query在界面 TemporalAccessor
        参数类型
        R - 结果的类型
        参数
        query - 要调用的查询,而不是null
        结果
        查询结果,可以返回null(由查询定义)
        异常
        DateTimeException - 如果无法查询(由查询定义)
        ArithmeticException - 如果发生数字溢出(由查询定义)
      • adjustInto

        public Temporal adjustInto​(Temporal temporal)
        调整指定的时间对象以获得今年。

        这将返回与输入相同的可观察类型的时间对象,并将年份更改为与此相同。

        该调整是相当于使用Temporal.with(TemporalField, long)传递ChronoField.YEAR作为字段。 如果指定的时态对象不使用ISO日历系统,则抛出DateTimeException

        在大多数情况下,使用Temporal.with(TemporalAdjuster)更清楚地反转调用模式:

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

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

        Specified by:
        adjustInto在界面 TemporalAdjuster
        参数
        temporal - 要调整的目标对象,而不是null
        结果
        调整后的对象,不为空
        异常
        DateTimeException - 如果无法进行调整
        ArithmeticException - 如果发生数字溢出
      • until

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

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

        计算返回一个整数,表示两年之间完整单位的数量。 例如,2012年至2031年间的数十年仅为十年,因为距离二十年不到一年。

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

          // these two lines are equivalent
           amount = start.until(end, YEARS);
           amount = YEARS.between(start, end); 
        应该根据哪个使代码更具可读性来做出选择。

        该计算在ChronoUnit此方法中实施 单位YEARSDECADESCENTURIESMILLENNIAERAS支持。 其他ChronoUnit值将引发异常。

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

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

        Specified by:
        until在界面 Temporal
        参数
        endExclusive - 结束日期,不包括,转换为 Year ,不为空
        unit - 计量金额的单位,而不是空
        结果
        今年和结束之间的时间量
        异常
        DateTimeException - 如果金额无法计算,或者结束时间不能转换为 Year
        UnsupportedTemporalTypeException - 如果不支持该装置
        ArithmeticException - 如果发生数字溢出
      • format

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

        今年将传递给格式化程序以生成字符串。

        参数
        formatter - 要使用的格式化程序,而不是null
        结果
        格式化的年份字符串,不是null
        异常
        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 - 要使用的年份,不是null
        结果
        从今年和指定月份形成的年月,不为空
      • atMonth

        public YearMonth atMonth​(int month)
        结合今年和一个月创建YearMonth

        这将返回从今年和指定月份组成的YearMonth 年和月的所有可能组合均有效。

        此方法可用作链的一部分以生成日期:

          LocalDate date = year.atMonth(month).atDay(day); 
        参数
        month - 从1(1月)到12(12月)使用的月份
        结果
        从今年和指定月份形成的年月,不为空
        异常
        DateTimeException - 如果月份无效
      • atMonthDay

        public LocalDate atMonthDay​(MonthDay monthDay)
        结合今年和一个月的日子创建一个LocalDate

        这将返回从今年和指定的月日形成的LocalDate

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

        参数
        monthDay - 要使用的月份日,而不是空
        结果
        从今年和指定的月 - 日形成的本地日期,不为空
      • compareTo

        public int compareTo​(Year other)
        比较今年到另一年。

        比较基于年份的价值。 它与“等于”一致,如Comparable所定义。

        Specified by:
        compareTo在界面 Comparable<Year>
        参数
        other - 与之比较的另一年,而不是null
        结果
        比较器值,如果更小则为负,如果更大则为正
      • isAfter

        public boolean isAfter​(Year other)
        检查今年是否在指定年份之后。
        参数
        other - 与之比较的另一年,而不是null
        结果
        如果在指定年份之后,则为true
      • isBefore

        public boolean isBefore​(Year other)
        检查今年是否在指定年份之前。
        参数
        other - 要比较的另一年,而不是null
        结果
        如果此点在指定年份之前,则为true
      • equals

        public boolean equals​(Object obj)
        检查今年是否等于另一年。

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

        重写:
        equals在课程 Object
        参数
        obj - 要检查的对象,null返回false
        结果
        如果这等于另一年,则为true
        另请参见:
        Object.hashCode()HashMap
      • toString

        public String toString()
        今年的产出为 String
        重写:
        toString在类 Object
        结果
        今年的字符串表示形式,不是null