模块  java.base
软件包  java.time

Class Period

  • 实现的所有接口
    SerializableChronoPeriodTemporalAmount

    public final class Period
    extends Object
    implements ChronoPeriod, Serializable
    ISO-8601日历系统中基于日期的时间量,例如“2年,3个月和4天”。

    本课程以年,月,日为单位对数量或时间进行建模。 有关此类的基于时间的等效项,请参见Duration

    当添加到ZonedDateTime时,持续时间和周期对夏令时的处理有所不同。 Duration将添加确切的秒数,因此一天的持续时间总是恰好24小时。 相比之下, Period将增加一个概念日,试图维持当地时间。

    例如,考虑在夏令时间差之前的晚上添加一天的时段和一天的持续时间到18:00。 Period将在第二天的18:00添加概念日并生成ZonedDateTime 相比之下, Duration将恰好增加24小时,在ZonedDateTime 19:00产生ZonedDateTime (假设DST差距为1小时)。

    一段时间的支持单位为YEARSMONTHSDAYS 所有三个字段始终存在,但可以设置为零。

    ISO-8601日历系统是当今世界大部分地区使用的现代民用日历系统。 它等同于公历的格里高利历法系统,其中今天的闰年规则一直适用。

    该时期被建模为指示的时间量,意味着该时期的各个部分可能是负的。

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

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

      • ZERO

        public static final Period ZERO
        一个常数为零。
    • 方法详细信息

      • ofYears

        public static Period ofYears​(int years)
        获得代表Period

        结果期间将具有指定年份。 月份和日期单位为零。

        参数
        years - 年数,正面或负面
        结果
        这段时间,不是空的
      • ofMonths

        public static Period ofMonths​(int months)
        获得代表数月的Period

        结果期间将具有指定的月份。 年和日的单位为零。

        参数
        months - 月份数,正数或负数
        结果
        几个月的时间,不是空的
      • ofWeeks

        public static Period ofWeeks​(int weeks)
        获得代表若干周的Period

        结果期间将基于日期,天数等于周数乘以7.年和月的单位将为零。

        参数
        weeks - 周数,正数或负数
        结果
        输入周转换为天数的期间,不为空
      • ofDays

        public static Period ofDays​(int days)
        获得代表若干天的Period

        结果期间将具有指定的天数。 年和月的单位将为零。

        参数
        days - 天数,正数或负数
        结果
        这段时间,不是空的
      • of

        public static Period of​(int years,
                                int months,
                                int days)
        获得代表若干年,月和日的Period

        这将创建基于年,月和日的实例。

        参数
        years - 年数,可能是负数
        months - 月数,可能是负数
        days - 天数,可能是负数
        结果
        年,月和日的期间,不为空
      • from

        public static Period from​(TemporalAmount amount)
        从时间量获得Period的实例。

        这将获得基于指定金额的期间。 TemporalAmount表示可以是基于日期或基于时间的时间量,该工厂将其提取到Period

        转换回路围绕该组的从单元,其数量和使用YEARSMONTHSDAYS单位创建的期间。 如果找到任何其他单位,则抛出异常。

        如果金额是ChronoPeriod那么它必须使用ISO年表。

        参数
        amount - 要转换的时间量,不为空
        结果
        等效期,不为空
        异常
        DateTimeException - 如果无法转换为 Period
        ArithmeticException - 如果年,月或日的数量超过int
      • parse

        public static Period parse​(CharSequence text)
        获得Period从文本字符串,如PnYnMnD

        这将解析由toString()生成的字符串,该字符串基于ISO-8601期间格式PnYnMnDPnW

        该字符串以可选符号开头,由ASCII否定符号或正符号表示。 如果是否定的,整个时期都会被否定。 ASCII字母“P”接下来是大写或小写。 然后有四个部分,每个部分由数字和后缀组成。 必须存在四个部分中的至少一个。 这些部分的ASCII为“Y”,“M”,“W”和“D”的后缀表示年,月,周和日,以大写或小写形式接受。 后缀必须按顺序出现。 每个部分的编号部分必须由ASCII数字组成。 该数字可以以ASCII否定符号或正符号作为前缀。 该号码必须解析为int

        前导加号/减号以及其他单位的负值不属于ISO-8601标准。 此外,ISO-8601不允许在PnYnMnDPnW格式之间进行混合。 任何基于周的输入乘以7并视为天数。

        例如,以下是有效输入:

          "P2Y"             -- Period.ofYears(2)
           "P3M"             -- Period.ofMonths(3)
           "P4W"             -- Period.ofWeeks(4)
           "P5D"             -- Period.ofDays(5)
           "P1Y2M3D"         -- Period.of(1, 2, 3)
           "P1Y2M3W4D"       -- Period.of(1, 2, 25)
           "P-1Y2M"          -- Period.of(-1, 2, 0)
           "-P1Y2M"          -- Period.of(-1, -2, 0) 
        参数
        text - 要解析的文本,而不是null
        结果
        解析的时间段,不为空
        异常
        DateTimeParseException - 如果文本无法解析为句点
      • between

        public static Period between​(LocalDate startDateInclusive,
                                     LocalDate endDateExclusive)
        获得Period包括两个日期之间的年数,月数和天数。

        包括开始日期,但结束日期不包括在内。 通过删除完整月份,然后计算剩余天数,调整以确保两者具有相同的符号来计算期间。 然后根据12个月的年份将月数分为几年和几个月。 如果结束日期大于或等于开始日期,则考虑一个月。 例如,从2010-01-152011-03-18是一年,两个月和三天。

        如果结束在开始之前,则该方法的结果可以是负周期。 每年,每月和每一天的负号都是相同的。

        参数
        startDateInclusive - 开始日期(包括),非空
        endDateExclusive - 结束日期,独占,非空
        结果
        此日期和结束日期之间的时间段,不为空
        另请参见:
        ChronoLocalDate.until(ChronoLocalDate)
      • getChronology

        public IsoChronology getChronology()
        获取此期间的年表,即ISO日历系统。

        Chronology表示正在使用的日历系统。 ISO-8601日历系统是当今世界大部分地区使用的现代民用日历系统。 它等同于公历的格里高利历法系统,其中今天的闰年规则一直适用。

        Specified by:
        getChronology ,界面 ChronoPeriod
        结果
        ISO年表,不是null
      • isZero

        public boolean isZero()
        检查此期间的所有三个单位是否为零。

        对于年,月和日单位,零周期的值为零。

        Specified by:
        isZero接口 ChronoPeriod
        结果
        如果此期间为零长度,则为true
      • isNegative

        public boolean isNegative()
        检查此期间的三个单位中的任何一个是否为负数。

        这将检查年,月或日单位是否小于零。

        Specified by:
        isNegative in interface ChronoPeriod
        结果
        如果此期间的任何单位为负数,则为true
      • getYears

        public int getYears()
        获取此期间的年数。

        这将返回年份单位。

        月份单位不会使用年份单位自动标准化。 这意味着“15个月”的时期与“1年3个月”的时期不同。

        结果
        这段时间的年数,可能是负数
      • getMonths

        public int getMonths()
        获取此期间的月数。

        这将返回月份单位。

        月份单位不会使用年份单位自动标准化。 这意味着“15个月”的时期与“1年3个月”的时期不同。

        结果
        这个时期的月数,可能是负数
      • getDays

        public int getDays()
        获取此期间的天数。

        这将返回天数单位。

        结果
        这段时间的天数,可能是负数
      • withYears

        public Period withYears​(int years)
        返回具有指定年数的此期间的副本。

        这将在此期间的副本中设置年份单位的数量。 月份和日期单位不受影响。

        月份单位不会使用年份单位自动标准化。 这意味着“15个月”的时期与“1年3个月”的时期不同。

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

        参数
        years - 代表的年份,可能是负面的
        结果
        基于此期间的请求年份的 Period ,不为空
      • withMonths

        public Period withMonths​(int months)
        返回具有指定月份数的此期间的副本。

        这将在此期间的副本中设置月份单位的数量。 年份和日期单位不受影响。

        月份单位不会使用年份单位自动标准化。 这意味着“15个月”的时期与“1年3个月”的时期不同。

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

        参数
        months - 代表的月份可能是负数
        结果
        基于此期间的请求月份的 Period ,不为空
      • withDays

        public Period withDays​(int days)
        返回具有指定天数的此期间的副本。

        这将设置此期间副本中的天数单位。 年份和月份单位不受影响。

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

        参数
        days - 代表的日子,可能是负面的
        结果
        a Period基于此期间的请求天数,不为空
      • plus

        public Period plus​(TemporalAmount amountToAdd)
        返回此期间的副本,并添加指定的期间。

        这在几年,几个月和几天分开运作。 不执行规范化。

        例如,“1年,6个月和3天”加上“2年,2个月和2天”返回“3年,8个月和5天”。

        指定的金额通常是Period的实例。 其他类型使用from(TemporalAmount)进行解释。

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

        Specified by:
        plus ,界面 ChronoPeriod
        参数
        amountToAdd - 要添加的金额,不为空
        结果
        基于此期间的 Period ,添加了请求的期间,而不是空
        异常
        DateTimeException - 如果指定的金额具有非ISO年表或包含无效单位
        ArithmeticException - 如果发生数字溢出
      • plusYears

        public Period plusYears​(long yearsToAdd)
        返回此期间的副本,并添加指定年份。

        这会在此期间的副本中添加年份单位的金额。 月份和日期单位不受影响。 例如,“1年,6个月和3天”加上2年返回“3年,6个月和3天”。

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

        参数
        yearsToAdd - 添加年份,正面或负面
        结果
        a Period基于此期间添加的指定年份,不为空
        异常
        ArithmeticException - 如果发生数字溢出
      • plusMonths

        public Period plusMonths​(long monthsToAdd)
        返回此期间的副本,并添加指定的月份。

        这会将金额添加到此期间副本中的月份单位。 年份和日期单位不受影响。 例如,“1年,6个月和3天”加上2个月返回“1年,8个月和3天”。

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

        参数
        monthsToAdd - 要添加的月份,正面或负面
        结果
        基于此期间的 Period ,添加了指定的月份,而不是空
        异常
        ArithmeticException - 如果发生数字溢出
      • plusDays

        public Period plusDays​(long daysToAdd)
        返回此期间的副本,并添加指定的天数。

        这会将金额添加到此期间副本中的天数单位。 年份和月份单位不受影响。 例如,“1年,6个月和3天”加上2天返回“1年,6个月和5天”。

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

        参数
        daysToAdd - 添加的日期,正面或负面
        结果
        基于此期间的 Period ,添加了指定的天数,而不是null
        异常
        ArithmeticException - 如果发生数字溢出
      • minus

        public Period minus​(TemporalAmount amountToSubtract)
        返回此期间的副本,并减去指定的期间。

        这在几年,几个月和几天分开运作。 不执行规范化。

        例如,“1年,6个月和3天”减去“2年,2个月和2天”返回“-1年,4个月和1天”。

        指定的金额通常是Period的实例。 其他类型使用from(TemporalAmount)进行解释。

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

        Specified by:
        minus在界面 ChronoPeriod
        参数
        amountToSubtract - 要减去的金额,而不是空
        结果
        基于此期间的 Period ,请求的时间段减去,不为空
        异常
        DateTimeException - 如果指定的金额具有非ISO年表或包含无效单位
        ArithmeticException - 如果发生数字溢出
      • minusYears

        public Period minusYears​(long yearsToSubtract)
        返回此期间的副本,并减去指定的年份。

        这会从该期间的副本中减去年份单位的金额。 月份和日期单位不受影响。 例如,“1年,6个月和3天”减去2年将返回“-1年,6个月和3天”。

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

        参数
        yearsToSubtract - 减去,正面或负面的年份
        结果
        基于此期间的 Period ,减去指定年份,不为空
        异常
        ArithmeticException - 如果发生数字溢出
      • minusMonths

        public Period minusMonths​(long monthsToSubtract)
        返回此期间的副本,并减去指定的月份。

        这会从该期间的副本中减去月份单位的金额。 年份和日期单位不受影响。 例如,“1年,6个月和3天”减去2个月返回“1年,4个月和3天”。

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

        参数
        monthsToSubtract - 减 monthsToSubtract ,正数或负数
        结果
        基于此期间的 Period ,减去指定月份,不为空
        异常
        ArithmeticException - 如果发生数字溢出
      • minusDays

        public Period minusDays​(long daysToSubtract)
        返回此期间的副本,并减去指定的天数。

        这会减去此期间副本中天数单位的金额。 年份和月份单位不受影响。 例如,“1年,6个月和3天”减去2天返回“1年,6个月和1天”。

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

        参数
        daysToSubtract - 减去的月数,正数或负数
        结果
        基于此期间的 Period ,减去指定天数,不为空
        异常
        ArithmeticException - 如果发生数字溢出
      • multipliedBy

        public Period multipliedBy​(int scalar)
        返回一个新实例,该周期中的每个元素乘以指定的标量。

        这将返回一个句点,其中每个年,月和日单位各自相乘。 例如,“2年,3个月和4天”的时间乘以3将返回“6年,-9个月和12天”。 不执行规范化。

        Specified by:
        multipliedBy在界面 ChronoPeriod
        参数
        scalar - 要乘以的标量,而不是null
        结果
        基于此期间的 Period ,其数量乘以标量,而不是空
        异常
        ArithmeticException - 如果发生数字溢出
      • negated

        public Period negated()
        返回一个新实例,此期间的每个金额都被否定。

        这将返回一个句点,其中每个年,月和日的单位都被单独否定。 例如,“2年,3个月和4天”的期限将被否定为“-2年,3个月和-4天”。 不执行规范化。

        Specified by:
        negated在界面 ChronoPeriod
        结果
        基于此期间的 Period ,金额被否定,不为空
        异常
        ArithmeticException - 如果发生数字溢出,仅当其中一个单位具有值 Long.MIN_VALUE时才会发生
      • normalized

        public Period normalized()
        返回此期间的副本,其中年份和月份已标准化。

        这使年份和月份单位正常化,使日期单位保持不变。 调整月份单位的绝对值小于12,并调整年份单位以进行补偿。 例如,“1年和15个月”的期间将标准化为“2年3个月”。

        标准化后,年份和月份单位的符号将相同。 例如,“1年和-25个月”的期间将标准化为“-1年和-1个月”。

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

        Specified by:
        normalized在界面 ChronoPeriod
        结果
        基于此期间的 Period ,超额月份标准化为年,不为空
        异常
        ArithmeticException - 如果发生数字溢出
      • toTotalMonths

        public long toTotalMonths()
        获取此期间的总月数。

        通过将年数乘以12并添加月数,可以返回该期间的总月数。

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

        结果
        期间的总月数,可能是负数
      • addTo

        public Temporal addTo​(Temporal temporal)
        将此句点添加到指定的时态对象。

        这将返回与添加此句点的输入相同的可观察类型的时间对象。 如果时间具有年表,则必须是ISO年表。

        在大多数情况下,使用Temporal.plus(TemporalAmount)更清楚地反转调用模式。

          // these two lines are equivalent, but the second approach is recommended
           dateTime = thisPeriod.addTo(dateTime);
           dateTime = dateTime.plus(thisPeriod); 

        计算如下操作。 首先,检查时间的年表,以确保它是ISO年表或无效。 其次,如果月份为零,则在非零时添加年份,否则如果非零,则添加年份和月份的组合。 最后,添加任何日子。

        此方法可确保将部分期间添加到部分日期。 例如,可以将年和/或月的期间添加到YearMonth ,但是包括天的期间不能。 该方法还在必要时将数年和数月相加,这确保了月末的正确行为。

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

        Specified by:
        addTo在界面 ChronoPeriod
        Specified by:
        addTo在界面 TemporalAmount
        参数
        temporal - 要调整的时态对象,而不是null
        结果
        进行调整的相同类型的对象,不为空
        异常
        DateTimeException - 如果无法添加
        ArithmeticException - 如果发生数字溢出
      • subtractFrom

        public Temporal subtractFrom​(Temporal temporal)
        从指定的时态对象中减去此句点。

        这将返回与输入相同的可观察类型的时间对象,并减去此时间段。 如果时间具有年表,则必须是ISO年表。

        在大多数情况下,使用Temporal.minus(TemporalAmount)更清楚地反转调用模式。

          // these two lines are equivalent, but the second approach is recommended
           dateTime = thisPeriod.subtractFrom(dateTime);
           dateTime = dateTime.minus(thisPeriod); 

        计算如下操作。 首先,检查时间的年表,以确保它是ISO年表或无效。 其次,如果月份为零,则如果非零则减去年份,否则如果非零,则减去年份和月份的组合。 最后,减去任何天数。

        该方法确保可以从部分日期中减去部分时段。 例如,可以从YearMonth减去一年和/或几个月的期间,但是包括天数的期间不能。 该方法还在必要时将数年和数月相减,这确保了月末的正确行为。

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

        Specified by:
        subtractFrom在界面 ChronoPeriod
        Specified by:
        subtractFrom在界面 TemporalAmount
        参数
        temporal - 要调整的时态对象,而不是null
        结果
        进行调整的相同类型的对象,不为空
        异常
        DateTimeException - 如果无法减去
        ArithmeticException - 如果发生数字溢出
      • equals

        public boolean equals​(Object obj)
        检查此期间是否等于另一期间。

        比较基于类型Period以及三个金额中的每一个。 为了平等,年,月和日的单位必须相等。 请注意,这意味着“15个月”的时段不等于“1年3个月”的时段。

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

        public String toString()
        将此期间输出为String ,例如P6Y3M1D

        输出将采用ISO-8601期间格式。 零周期将表示为零天,'P0D'。

        Specified by:
        toString在界面 ChronoPeriod
        重写:
        toString在课程 Object
        结果
        此期间的字符串表示形式,不为null