模块  java.base
软件包  java.time

Class Period

  • 实现的所有接口
    Serializable ， ChronoPeriod ， TemporalAmount 
    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小时）。

    一段时间的支持单位为YEARS ， MONTHS和DAYS 。 所有三个字段始终存在，但可以设置为零。

    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 。

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

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

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

      • parse

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

        这将解析由toString()生成的字符串，该字符串基于ISO-8601期间格式PnYnMnD和PnW 。

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

        前导加号/减号以及其他单位的负值不属于ISO-8601标准。 此外，ISO-8601不允许在PnYnMnD和PnW格式之间进行混合。 任何基于周的输入乘以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-15到2011-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