模块 java.base

包 java.time

类 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 时，持续时间和期间在处理夏令时方面有所不同。 Duration 将添加精确的秒数，因此一天的持续时间始终正好是 24 小时。相比之下，Period 将添加一个概念日，试图保持本地时间。

例如，考虑在夏令时间隙之前的晚上的 18:00 添加一天的时间段和一天的持续时间。 Period 将添加概念日并在第二天 18:00 生成 ZonedDateTime。相比之下，Duration 将恰好添加 24 小时，从而在第二天 19:00 产生 ZonedDateTime（假设 DST 间隔一小时）。

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

ISO-8601 日历系统是当今世界大部分地区使用的现代民用日历系统。它相当于公历系统，在所有时间都适用今天的闰年规则。

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

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

实现要求：

这个类是不可变的和线程安全的。

自从：

1.8

参见：

• Serialized Form

字段摘要

字段

修饰符和类型	Field	描述
static final Period	ZERO	零期间的常数。

方法总结

修饰符和类型	方法	描述
Temporal	addTo(Temporal temporal)	将此期间添加到指定的时间对象。
static Period	between(LocalDate startDateInclusive, LocalDate endDateExclusive)	获得一个 Period，由两个日期之间的年数、月数和天数组成。
boolean	equals(Object obj)	检查此期间是否等于另一个期间。
static Period	from(TemporalAmount amount)	从时间量中获取 Period 的实例。
long	get(TemporalUnit unit)	获取所请求单位的值。
IsoChronology	getChronology()	获取该时期的年表，即ISO日历系统。
int	getDays()	获取此期间的天数。
int	getMonths()	获取此期间的月数。
List<TemporalUnit>	getUnits()	获取此期间支持的单位集。
int	getYears()	获取此期间的年数。
int	hashCode()	此期间的哈希码。
boolean	isNegative()	检查此期间的三个单位中是否有任何一个为负数。
boolean	isZero()	检查此期间的所有三个单位是否为零。
Period	minus(TemporalAmount amountToSubtract)	返回此期间减去指定期间的副本。
Period	minusDays(long daysToSubtract)	返回此期间减去指定天数的副本。
Period	minusMonths(long monthsToSubtract)	返回此期间减去指定月份的副本。
Period	minusYears(long yearsToSubtract)	返回此期间减去指定年份的副本。
Period	multipliedBy(int scalar)	返回一个新实例，该实例中的每个元素都乘以指定的标量。
Period	negated()	返回一个新实例，此期间的每个金额都被取反。
Period	normalized()	返回此期间的副本，其中年份和月份已标准化。
static Period	of(int years, int months, int days)	获得代表年、月和日数的Period。
static Period	ofDays(int days)	获得代表天数的 Period。
static Period	ofMonths(int months)	获得代表月份数的 Period。
static Period	ofWeeks(int weeks)	获得代表周数的 Period。
static Period	ofYears(int years)	获得代表年份数的 Period。
static Period	parse(CharSequence text)	从 PnYnMnD 等文本字符串中获取 Period。
Period	plus(TemporalAmount amountToAdd)	返回添加了指定期间的此期间的副本。
Period	plusDays(long daysToAdd)	返回添加了指定天数的此期间的副本。
Period	plusMonths(long monthsToAdd)	返回添加了指定月份的此期间的副本。
Period	plusYears(long yearsToAdd)	返回添加了指定年份的此期间的副本。
Temporal	subtractFrom(Temporal temporal)	从指定的时间对象中减去这个周期。
String	toString()	将此期间输出为 String ，例如 P6Y3M1D 。
long	toTotalMonths()	获取此期间的总月数。
Period	withDays(int days)	返回具有指定天数的此期间的副本。
Period	withMonths(int months)	返回具有指定月数的此期间的副本。
Period	withYears(int years)	返回具有指定年数的此期间的副本。

在类 java.lang.Object 中声明的方法

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

字段详细信息

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)
            

从 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 - 结束日期，独占，不为空

返回：

此日期和结束日期之间的时间段，不为空

参见：

• ChronoLocalDate.until(ChronoLocalDate)

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 中

返回：

如果此期间为零长度，则为真

isNegative

public boolean isNegative()
            

检查此期间的三个单位中是否有任何一个为负数。

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

指定者：

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 基于此期间和请求的年份，不为空

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 - 添加的数量，不为空

返回：

a 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 基于此期间添加指定天数，不为空

抛出：

ArithmeticException - 如果发生数字溢出

minus

public Period  minus(TemporalAmount  amountToSubtract)
            

返回此期间减去指定期间的副本。

这分别在年、月和日上运行。不执行归一化。

例如，“1 年 6 个月零 3 天”减去“2 年 2 个月零 2 天”得出“-1 年 4 个月零 1 天”。

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

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

指定者：

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 - 要减去的年份，正数或负数

返回：

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 天”。不执行归一化。

指定者：

multipliedBy 在接口 ChronoPeriod 中

参数：

scalar - 要乘以的标量，不为空

返回：

Period 基于此期间，金额乘以标量，不为空

抛出：

ArithmeticException - 如果发生数字溢出

negated

public Period  negated()
            

返回一个新实例，此期间的每个金额都被取反。

这将返回一个期间，其中每个年、月和日单位都被单独取反。例如，“2 年，-3 个月和 4 天”的期间将取反为“-2 年，3 个月和 -4 天”。不执行归一化。

指定者：

negated 在接口 ChronoPeriod 中

返回：

Period 基于此期间，金额被否定，不为空

抛出：

ArithmeticException - 如果发生数字溢出，只有当其中一个单位的值为 Integer.MIN_VALUE 时才会发生

normalized

public Period  normalized()
            

返回此期间的副本，其中年份和月份已标准化。

这使年和月单位标准化，使天单位保持不变。调整月单位使其绝对值小于 12，调整年单位以进行补偿。例如，“1 年 15 个月”的时间段将标准化为“2 年 3 个月”。

标准化后年月单位的符号相同。例如，“1 年零 -25 个月”的时间段将标准化为“-1 年零 -1 个月”。

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

指定者：

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 ，但不能添加包含天数的时间段。该方法还会在必要时将年份和月份相加，以确保月末的正确行为。

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

指定者：

addTo 在接口 ChronoPeriod 中

指定者：

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 年表或为空。其次，如果月份为零，如果非零则减去年，否则如果非零则减去年和月的组合。最后，减去任何天数。

这种方法确保可以从部分日期中减去部分时间段。例如，可以从 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

返回：

如果这等于另一个时期，则为真

参见：

• Object.hashCode()
• HashMap

hashCode

public int hashCode()
            

此期间的哈希码。

指定者：

hashCode 在接口 ChronoPeriod 中

重写：

hashCode 在类 Object 中

返回：

合适的哈希码

参见：

• Object.equals(java.lang.Object)
• System.identityHashCode(java.lang.Object)

toString

public String  toString()
            

将此期间输出为 String ，例如 P6Y3M1D 。

输出将采用 ISO-8601 句点格式。零期将表示为零天，“P0D”。

指定者：

toString 在接口 ChronoPeriod 中

重写：

toString 在类 Object 中

返回：

此期间的字符串表示形式，不为空