Module  java.base
软件包  java.time

Class Period

  • All Implemented Interfaces:
    SerializableChronoPeriodTemporalAmount


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

    这个课程以年,月和日为单位建立数量或时间量。 请参阅Duration的时间相当于此类。

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

    例如,在夏令时间之前,请考虑在晚上添加一天的时间和一天的时间到18:00。 Period将在第二天的18:00添加概念日,结果为ZonedDateTime 相比之下, Duration将正好添加24小时,从而在ZonedDateTime的19:00(假设一小时的DST差距)产生了ZonedDateTime

    一段时间的支持单位为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的实例。

        这取决于指定金额的期限。 A TemporalAmount表示这个工厂提取给Period的时间量,可以是基于日期或时间的。

        该转换围绕该单位的数量循环 ,并使用YEARS,MONTHSDAYS单位创建期间。 如果找到任何其他单位,则会抛出异常。

        如果金额是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年表,不为空
      • isZero

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

        零期间的年,月和日单位为零。

        Specified by:
        isZero在接口 ChronoPeriod
        结果
        如果这个时期是零长度,则为真
      • isNegative

        public boolean isNegative​()
        检查此期间的三个单位是否为负。

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

        Specified by:
        isNegative在接口 ChronoPeriod
        结果
        如果这个时期的任何一个单位都是负数,则为真
      • 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基于这个期间与要求的年份,不为null
      • withMonths

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

        这设定了这个期间的副本的月份数量。 年和日单位不受影响。

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

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

        参数
        months - 表示的月份可能为负数
        结果
        一个 Period基于此期间与请求的月份,不为null
      • withDays

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

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

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

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

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

        这在几年,几个月和几天内分开运作。 不执行归一化。

        例如“1年6个月3天”加“2年2个月2天”返还“3年8个月5日”。

        指定数量通常为Period的实例。 其他类型使用from(TemporalAmount)进行解释。

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

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

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

        这增加了这个期间的年份单位的数额。 月和日单位不受影响。 例如,“1年6个月3天”加上2年“3年6个月3天”。

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

        参数
        yearsToAdd - 增加的年份,正面或负面
        结果
        一个 Period基于这个时期与指定的年份添加,不为null
        异常
        ArithmeticException - 如果发生数字溢出
      • plusMonths

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

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

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

        参数
        monthsToAdd - 增加的正数或负数
        结果
        一个 Period基于这个时期加上指定的月份,不为null
        异常
        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基于此期间减去所请求的期间,不为null
        异常
        DateTimeException - 如果指定的数量具有非ISO年表或包含无效单位
        ArithmeticException - 如果发生数字溢出
      • minusYears

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

        这减去这个期间的年份单位的数额。 月和日单位不受影响。 例如,“1年6个月3天”减去2年后返回“-1年6个月3天”。

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

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

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

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

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

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

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

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

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

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

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

        这返回一个时期,每个年份,月份和日期单位分别乘以。 例如,“2年-3个月4天”乘以3将返回“6年-9个月12天”。 不执行归一化。

        Specified by:
        multipliedBy在接口 ChronoPeriod
        参数
        scalar - 要乘以的标量,不为空
        结果
        一个基于此期间的 Period ,其数量乘以标量,不为null
        异常
        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年表或null。 第二,如果月份为零,则如果不为零,则添加年份,否则如果非零,则添加年份和月份的组合。 最后,添加任何日子。

        这种方法确保可以将部分期间添加到部分日期。 例如,可以在YearMonth添加一段时间和/或几个月,但包括天数在内的期间不能。 该方法在必要时还可以一起添加数年和数月,从而确保月底的正确行为。

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

        Specified by:
        addTo在接口 ChronoPeriod
        Specified by:
        addTo在接口 TemporalAmount
        参数
        temporal - 要调整的时间对象,不为空
        结果
        与调整相同类型的对象,不为空
        异常
        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年表或null。 第二,如果月份为零,则如果非零则减去年份,否则如果非零,则减去年和月的组合。 最后,减去任何日子。

        这种方法确保可以从部分日期中减去部分期间。 例如,可以从YearMonth扣除一段时间和/或几个月,但包括天数在内的期间不能。 该方法在必要时也会一起减少数年和数月,从而确保月底的正确行为。

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

        Specified by:
        subtractFrom在接口 ChronoPeriod
        Specified by:
        subtractFrom在接口 TemporalAmount
        参数
        temporal - 要调整的时间对象,不为空
        结果
        与调整相同类型的对象,不为空
        异常
        DateTimeException - 如果不能减去
        ArithmeticException - 如果发生数字溢出
      • equals

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

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

        Specified by:
        equals在接口 ChronoPeriod
        重写:
        equalsObject
        参数
        obj - 要检查的对象,null返回false
        结果
        如果这等于其他时期,则为真
        另请参见:
        Object.hashCode()HashMap
      • toString

        public String toString​()
        输出这个时期为String ,如P6Y3M1D

        输出的格式为ISO-8601。 零期将被表示为零天,“P0D”。

        Specified by:
        toString在接口 ChronoPeriod
        重写:
        toStringObject
        结果
        此期间的字符串表示,不为空