Module  java.base
软件包  java.time

Class Year

  • All Implemented Interfaces:
    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'。
        另请参见:
        Constant Field Values
      • MAX_VALUE

        public static final int MAX_VALUE
        最大支持年份为'+ 999,999,999'。
        另请参见:
        Constant Field Values
    • 方法详细信息

      • 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 isoYear年代表,从 MIN_VALUEMAX_VALUE
        结果
        一年,不为零
        异常
        DateTimeException - 如果该字段无效
      • from

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

        这取决于指定时间的一年。 A 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”,不为空
        结果
        被解析的年份,不为零
        异常
        DateTimeParseException - 如果文本无法解析
      • parse

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

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

        参数
        text - 要解析的文本,不为空
        formatter - 使用的格式化程序,不为空
        结果
        被解析的年份,不为零
        异常
        DateTimeParseException - 如果文本无法解析
      • isLeap

        public static boolean isLeap​(long year)
        根据ISO培训日历系统规则,检查年份是否是闰年。

        这种方法在整个时间线上应用目前的闰年规则。 一般来说,一年是一个闰年,如果没有余数可以被四分割。 但是,除了100岁之外,年份可以被分割为100岁,除了年龄可以被400除外。

        例如,1904年是一个闰年,可以被4整除。1900年不是一个闰年,因为它可以被100整除,然而2000年是一个闰年,因为它可以被400除数。

        计算是应激的 - 将相同的规则应用到远未来很远的地方。 这在历史上是不准确的,但对于ISO-8601标准是正确的。

        参数
        year - 检查年份
        结果
        如果一年是飞跃,否则为假
      • getValue

        public int getValue​()
        获取年值。

        通过这种方法返回的年份是根据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
        参数
        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作为参数。 设备是否受支持由本机决定。

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

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

        范围对象表示字段的最小和最大有效值。 今年用于提高返回范围的准确性。 如果不可能返回范围,因为该字段不受支持或出于某种其他原因,则抛出异常。

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

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

        Specified by:
        range在接口 TemporalAccessor
        参数
        field - 查询范围的字段,不为null
        结果
        字段的有效值的范围不为null
        异常
        DateTimeException - 如果无法获取字段的范围
        UnsupportedTemporalTypeException - 如果该字段不被支持
      • get

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

        今年将查询指定字段的值。 返回的值将始终在该字段的值的有效范围内。 如果不可能返回值,因为该字段不受支持或出于某种其他原因,则抛出异常。

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

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

        Specified by:
        get在接口 TemporalAccessor
        参数
        field - 要获取的字段,不为null
        结果
        该字段的值
        异常
        DateTimeException - 如果无法获取字段的值,或者该值超出了该字段的有效值的范围
        UnsupportedTemporalTypeException - 如果该字段不受支持或值的范围超过 int
        ArithmeticException - 如果发生数字溢出
      • getLong

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

        今年将查询指定字段的值。 如果不可能返回值,因为该字段不受支持或出于某种其他原因,则抛出异常。

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

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

        Specified by:
        getLong在接口 TemporalAccessor
        参数
        field - 要获取的字段,不为null
        结果
        该字段的值
        异常
        DateTimeException - 如果无法获取字段的值
        UnsupportedTemporalTypeException - 如果该字段不被支持
        ArithmeticException - 如果发生数字溢出
      • isLeap

        public boolean isLeap​()
        根据ISO培训日历系统规则,检查年份是否是闰年。

        这种方法在整个时间线上应用目前的闰年规则。 一般来说,一年是一个闰年,如果没有余数可以被四分割。 但是,除了100岁之外,年份可以被分割为100岁,除了年龄可以被400除外。

        例如,1904年是一个闰年,可以被4整除。1900年不是一个闰年,因为它可以被100整除,然而2000年是一个闰年,因为它可以被400除数。

        计算是应激的 - 将相同的规则应用到远未来很远的地方。 这在历史上是不准确的,但对于ISO-8601标准是正确的。

        结果
        如果一年是飞跃,否则为假
      • isValidMonthDay

        public boolean isValidMonthDay​(MonthDay monthDay)
        检查今年的月日是否有效。

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

        参数
        monthDay - 验证的月日,null返回false
        结果
        如果月和日在今年有效,则为真
      • length

        public int length​()
        在几天内获得今年的长度。
        结果
        今年的长短是365天或366天
      • with

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

        这返回一个Year ,基于这一个,随着年度的调整。 调整使用指定的调整器策略对象进行。 阅读调整器的文档,了解将进行什么调整。

        该方法的结果是通过调用TemporalAdjuster.adjustInto(Temporal)方法获得的指定调整器通过this作为参数。

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

        Specified by:
        with在接口 Temporal
        参数
        adjuster - 调整器使用,不为空
        结果
        一个 Year基于 this进行了调整,不为null
        异常
        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
        参数
        field - 要在结果中设置的字段,不为null
        newValue - 结果中字段的新值
        结果
        一个 Year基于 this与指定的字段集,不为null
        异常
        DateTimeException - 如果该字段无法设置
        UnsupportedTemporalTypeException - 如果该字段不被支持
        ArithmeticException - 如果发生数字溢出
      • plus

        public Year plus​(TemporalAmount amountToAdd)
        返回今年的副本,并附加指定的金额。

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

        通过调用TemporalAmount.addTo(Temporal)将计算委托给金额对象。 数量执行可以以任何方式实现添加,但是它通常会调用到plus(long, TemporalUnit) 请参阅金额执行的文档,以确定是否可以成功添加。

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

        Specified by:
        plus在接口 Temporal
        参数
        amountToAdd - 要添加的金额,不为null
        结果
        一个 Year基于今年添加,不为null
        异常
        DateTimeException - 如果不能添加
        ArithmeticException - 如果发生数字溢出
      • plus

        public Year plus​(long amountToAdd,
                         TemporalUnit unit)
        返回今年的副本,并附加指定的金额。

        这将返回一个Year ,基于此,以添加的单位数量。 如果不可能添加金额,因为单位不受支持或出于某种其他原因,则抛出异常。

        如果该字段是一个ChronoUnit那么在这里实现添加。 支持的字段的行为如下:

        • YEARS - 返回指定年数的Year 这相当于plusYears(long)
        • DECADES - 返回一个Year ,加上指定的几十年。 这相当于调用plusYears(long) ,数量乘以10。
        • CENTURIES - 返回一个Year ,加上指定的几个世纪。 这相当于调用plusYears(long) ,数量乘以100。
        • MILLENNIA - 返回一个Year ,加上指定的几千年。 这相当于调用plusYears(long) ,数量乘以1,000。
        • ERAS - 返回一个Year ,其中添加了指定的时间。 只支持两个时间,所以数量必须是1,零或者减1。 如果金额不是零,那么这个年份就会改变,使得年龄不变。

        所有其他ChronoUnit实例将抛出一个UnsupportedTemporalTypeException

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

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

        Specified by:
        plus在接口 Temporal
        参数
        amountToAdd - 要添加到结果中的单位数量,可能为负数
        unit - 要添加的单位,不为null
        结果
        一个 Year基于今年与指定的数量添加,不为null
        异常
        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) 请参阅数量执行的文档,以确定是否可以成功减去它们。

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

        Specified by:
        minus在接口 Temporal
        参数
        amountToSubtract - 减去量,不为空
        结果
        一个 Year基于今年的减法而不是null
        异常
        DateTimeException - 如果不能进行减法
        ArithmeticException - 如果发生数字溢出
      • minus

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

        这将返回一个Year ,基于此,减去单位的数量。 如果不可能减去金额,因为该单位不受支持或出于某种其他原因,则会抛出异常。

        这种方法相当于plus(long, TemporalUnit) ,数量被否定。 请参阅该方法,以了解如何添加,从而减去运算。

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

        Specified by:
        minus在接口 Temporal
        参数
        amountToSubtract - 从结果中减去的单位数量可能为负数
        unit - 减去量的单位,不为空
        结果
        一个 Year基于今年减去指定的数量,不为null
        异常
        DateTimeException - 如果不能进行减法
        UnsupportedTemporalTypeException - 如果不支持本机
        ArithmeticException - 如果发生数字溢出
      • minusYears

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

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

        参数
        yearsToSubtract - 减去年份,可能为负数
        结果
        一个 Year基于今年减去年,不为零
        异常
        DateTimeException - 如果结果超出了支持的范围
      • query

        public <R> R query​(TemporalQuery<R> query)
        今年查询使用指定的查询。

        今年使用指定的查询策略对象查询。 TemporalQuery对象定义要用于获取结果的逻辑。 阅读查询的文档,以了解该方法的结果。

        该方法的结果是通过在指定的查询this作为参数调用TemporalQuery.queryFrom(TemporalAccessor)方法获得的。

        Specified by:
        query在接口 TemporalAccessor
        参数类型
        R - 结果的类型
        参数
        query - 要调用的查询,不为空
        结果
        查询结果可能返回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
        结果
        调整对象,不为null
        异常
        DateTimeException - 如果不能进行调整
        ArithmeticException - 如果发生数字溢出
      • until

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

        这可以计算一个Year对象之间的时间量,单个TemporalUnit 起点和终点为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 - 使用年月日,不为空
        结果
        从今年和特定月份形成的年月,不为零
      • 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
        结果
        如果这是在指定年份之后,则为真
      • isBefore

        public boolean isBefore​(Year other)
        检查今年是否在指定年份之前。
        参数
        other - 与其他年比较,不为空
        结果
        如果这一点在指定年份之前,则为真
      • equals

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

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

        重写:
        equalsObject
        参数
        obj - 要检查的对象,null返回false
        结果
        如果这等于其他年份,则为真
        另请参见:
        Object.hashCode()HashMap
      • toString

        public String toString​()
        今年产量为 String
        重写:
        toStringObject
        结果
        今年的字符串表示,不为空