Module java.base
Package java.time

Class Period

java.lang.Object
java.time.Period
所有已实现的接口:
Serializable, ChronoPeriod, TemporalAmount
public final class Period extends Object implements ChronoPeriod, Serializable
ISO-8601日历系统中的基于日期的时间量，例如'2年，3个月和4天'。

此类以年、月和日的形式模拟时间的数量或量。请参见Duration，该类是该类的基于时间的等效类。

在将持续时间和周期添加到ZonedDateTime时，持续时间和周期在处理夏令时时会有所不同。持续时间将添加确切的秒数，因此一天的持续时间始终恰好为24小时。相比之下，周期将添加一个概念上的日，试图保持本地时间。

例如，考虑在夏令时间隙前一天晚上18:00添加一天的周期和一天的持续时间。周期将添加概念上的一天，并导致隔天晚上18:00的ZonedDateTime。相比之下，持续时间将添加确切的24小时，导致隔天晚上19:00的ZonedDateTime（假设有一个小时的夏令时间隙）。

周期支持的单位为YEARS、MONTHS和DAYS。这三个字段始终存在，但可以设置为零。

ISO-8601日历系统是当今世界大部分地区使用的现代公民日历系统。它等同于先验公历日历系统，其中应用了今天的闰年规则。

周期被建模为有向时间量，这意味着周期的各个部分可能为负。

这是一个基于值的类；程序员应将相等的实例视为可互换的，并且不应将实例用于同步，否则可能会发生不可预测的行为。例如，在将来的版本中，同步可能会失败。应使用equals方法进行比较。

实现要求:
此类是不可变的且线程安全的。
自:
1.8
参见:

  • Field Details

    • ZERO

      public static final Period ZERO
      一个零时期的常量。

  • Method Details

    • 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)
      从文本字符串（如PnYnMnD）获取Period。

      这将解析由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 - 要解析的文本，非空
      返回:
      解析后的周期，非空
      抛出:
      DateTimeParseException - 如果无法将文本解析为周期

    • between

      public static Period between(LocalDate startDateInclusive, LocalDate endDateExclusive)
      获取两个日期之间的年数、月数和天数构成的Period。

      开始日期包含在内，但结束日期不包含在内。该期间是通过去除完整的月份，然后计算剩余的天数来计算的，并调整以确保两者具有相同的符号。然后根据12个月一年的规则将月数分为年和月。如果结束日期的日期大于或等于开始日期的日期，则认为是一个月。例如，从2010-01-15到2011-03-18是一年、两个月和三天。

      如果结束日期在开始日期之前，则此方法的结果可能是负数。负号在年、月和日中都相同。

      参数:
      startDateInclusive - 开始日期（包含），不能为空
      endDateExclusive - 结束日期（不包含），不能为空
      返回:
      此日期和结束日期之间的期间，不能为空
      参见:

    • get

      public long get(TemporalUnit unit)
      获取请求单位的值。

      这将返回三个支持单位YEARS、MONTHS和DAYS的值。所有其他单位都会抛出异常。

      指定者:
      get 在接口 ChronoPeriod
      指定者:
      get 在接口 TemporalAmount
      参数:
      unit - 要返回值的TemporalUnit
      返回:
      单位的长整型值
      抛出:
      DateTimeException - 如果单位不受支持
      UnsupportedTemporalTypeException - 如果单位不受支持

    • getUnits

      public List<TemporalUnit> getUnits()
      获取此期间支持的单位集。

      支持的单位是YEARS、MONTHS和DAYS。它们按照年、月、日的顺序返回。

      此集合可与get(TemporalUnit)一起使用，以访问期间的整个状态。

      指定者:
      getUnits 在接口 ChronoPeriod
      指定者:
      getUnits 在接口 TemporalAmount
      返回:
      包含年、月和日单位的列表，不能为空

    • getChronology

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

      Chronology表示正在使用的日历系统。ISO-8601日历系统是当今世界大部分地区使用的现代公民日历系统。它等同于延续的公历日历系统，其中适用今天的闰年规则。

      指定者:
      getChronology 在接口 ChronoPeriod
      返回:
      ISO年表，不能为空

    • isZero

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

      零期间的年、月和日单位的值都为零。

      指定者:
      isZero 在接口 ChronoPeriod
      返回:
      如果此期间为零长度，则为true

    • isNegative

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

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

      指定者:
      isNegative 在接口 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 - 要表示的天数，可能为负数
      返回:
      基于此期间的具有请求天数的Period，不能为空

    • plus

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

      这将分别对年、月和日进行操作。不执行归一化。

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

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

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

      指定者:
      plus 在接口 ChronoPeriod
      参数:
      amountToAdd - 要添加的数量，不能为空
      返回:
      基于此期间的具有请求期间添加的Period，不能为空
      抛出:
      DateTimeException - 如果指定的数量具有非ISO年表或包含无效单位
      ArithmeticException - 如果发生数值溢出

    • plusYears

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

      这将在此期间的副本中添加年单位的数量。月和日单位不受影响。例如，“1年6个月3天”加上2年将返回“3年6个月3天”。

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

      参数:
      yearsToAdd - 要添加的年数，可以为正数或负数
      返回:
      基于此期间的具有指定年数添加的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)进行解释。

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

      指定者：
      minus 在接口 ChronoPeriod
      参数：
      amountToSubtract - 要减去的数量，不为null
      返回：
      基于此期间的副本，减去请求的期间的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天”。不执行规范化。

      指定者：
      multipliedBy 在接口 ChronoPeriod
      参数：
      scalar - 要乘以的标量，不为null
      返回：
      基于此期间的副本，每个数量乘以标量的Period，不为null
      抛出：
      ArithmeticException - 如果发生数值溢出

    • negated

      public Period negated()
      返回每个此期间中的数量取反后的新实例。

      这将返回一个期间，其中每个年份、月份和天数单位分别取反。例如，“2年，-3个月和4天”将被取反为“-2年，3个月和-4天”。不执行规范化。

      指定者：
      negated 在接口 ChronoPeriod
      返回：
      基于此期间的副本，每个数量取反的Period，不为null
      抛出：
      ArithmeticException - 如果发生数值溢出，仅在其中一个单位的值为Integer.MIN_VALUE时才会发生

    • normalized

      public Period normalized()
      返回年份和月份已规范化的此期间的副本。

      这将规范化年份和月份单位，保持天数单位不变。月份单位将调整为绝对值小于12，年份单位将进行调整以补偿。例如，“1年和15个月”的期间将被规范化为“2年和3个月”。

      规范化后，年份和月份单位的符号将保持不变。例如，“1年和-25个月”的期间将被规范化为“-1年和-1个月”。

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

      指定者：
      normalized 在接口 ChronoPeriod
      返回：
      基于此期间的副本，将多余的月份规范化为年份的Period，不为null
      抛出：
      ArithmeticException - 如果发生数值溢出

    • toTotalMonths

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

      通过将年数乘以12并加上月数，返回期间中的总月数。

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

      返回：
      期间中的总月数，可能为负数

    • addTo

      public Temporal addTo(Temporal temporal)
      将此期间添加到指定的时间对象。

      返回一个与输入具有相同可观察类型的时间对象，其中添加了此期间。如果时间对象具有年表，则必须是ISO年表。

      在大多数情况下，通过使用Temporal.plus(TemporalAmount)来反转调用模式更清晰。

         // 这两行是等效的，但推荐第二种方法
   dateTime = thisPeriod.addTo(dateTime);
   dateTime = dateTime.plus(thisPeriod);

      计算操作如下。首先，检查时间对象的年表，以确保它是ISO年表或null。其次，如果月份为零，则如果年份为非零，则添加年份，否则如果年份和月份组合不为零，则添加。最后，添加任何天数。

      此方法确保可以将部分期间添加到部分日期。例如，可以将年份和/或月份的期间添加到YearMonth，但包含天数的期间则不行。该方法还在必要时将年份和月份一起添加，以确保在月末时行为正确。

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

      指定者：
      addTo 在接口 ChronoPeriod
      指定者：
      addTo 在接口 TemporalAmount
      参数：
      temporal - 要调整的时间对象，不为null
      返回：
      进行了调整的相同类型的对象，不为null
      抛出：
      DateTimeException - 如果无法添加
      ArithmeticException - 如果发生数值溢出

    • subtractFrom

      public Temporal subtractFrom(Temporal temporal)
      从指定的时间对象中减去此周期。

      返回一个与输入相同可观察类型的时间对象，其中减去了此周期。如果时间对象有一个年表，则必须是ISO年表。

      在大多数情况下，通过使用Temporal.minus(TemporalAmount)来反转调用模式会更清晰。

         // 这两行是等效的，但推荐第二种方法
   dateTime = thisPeriod.subtractFrom(dateTime);
   dateTime = dateTime.minus(thisPeriod);

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

      此方法确保可以从部分日期中减去部分周期。例如，可以从YearMonth中减去年份和/或月份的周期，但包括天数的周期则不行。该方法还在必要时一起减去年份和月份，以确保在月底时行为正确。

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

      指定者：
      subtractFrom 在接口 ChronoPeriod
      指定者：
      subtractFrom 在接口 TemporalAmount
      参数：
      temporal - 要调整的时间对象，不能为空
      返回：
      进行调整后的相同类型的对象，不能为空
      抛出：
      DateTimeException - 如果无法减去
      ArithmeticException - 如果发生数值溢出

    • equals

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

      比较基于类型Period和三个数量。要相等，年份、月份和天数单位必须分别相等。请注意，这意味着“15个月”的周期不等于“1年和3个月”的周期。

      指定者：
      equals 在接口 ChronoPeriod
      覆盖：
      equals 在类 Object
      参数：
      obj - 要检查的对象，null返回false
      返回：
      如果这个周期等于另一个周期，则为true
      参见：

    • hashCode

      public int hashCode()
      此周期的哈希码。
      指定者：
      hashCode 在接口 ChronoPeriod
      覆盖：
      hashCode 在类 Object
      返回：
      适当的哈希码
      参见：

    • toString

      public String toString()
      将此周期输出为String，例如P6Y3M1D。

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

      指定者：
      toString 在接口 ChronoPeriod
      覆盖：
      toString 在类 Object
      返回：
      此周期的字符串表示，不能为空