- 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小时,在ZonedDateTime
19:00产生ZonedDateTime
(假设DST差距为1小时)。一段时间的支持单位为
YEARS
,MONTHS
和DAYS
。 所有三个字段始终存在,但可以设置为零。ISO-8601日历系统是当今世界大部分地区使用的现代民用日历系统。 它等同于公历的格里高利历法系统,其中今天的闰年规则一直适用。
该时期被建模为指示的时间量,意味着该时期的各个部分可能是负的。
这是一个value-based班; 在
Period
实例上使用身份敏感操作(包括引用相等(==
),标识哈希码或同步)可能会产生不可预测的结果,应该避免使用。 应使用equals
方法进行比较。- 实现要求:
- 这个类是不可变的和线程安全的。
- 从以下版本开始:
- 1.8
- 另请参见:
- Serialized Form
-
-
方法摘要
所有方法 静态方法 实例方法 具体的方法 变量和类型 方法 描述 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)
获得Period
从文本字符串,如PnYnMnD
。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)
返回具有指定年数的此期间的副本。
-
-
-
字段详细信息
-
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)
-
get
public long get(TemporalUnit unit)
- Specified by:
-
get
,界面ChronoPeriod
- Specified by:
-
get
在界面TemporalAmount
- 参数
-
unit
- 要为其返回值的TemporalUnit
- 结果
- 单位的长期价值
- 异常
-
DateTimeException
- 如果不支持该设备 -
UnsupportedTemporalTypeException
- 如果不支持该装置
-
getUnits
public List<TemporalUnit> getUnits()
- Specified by:
-
getUnits
in interfaceChronoPeriod
- Specified by:
-
getUnits
在界面TemporalAmount
- 结果
- 包含年,月和日单位的列表,不为空
-
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 interfaceChronoPeriod
- 结果
- 如果此期间的任何单位为负数,则为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
-
hashCode
public int hashCode()
此期间的哈希码。- Specified by:
-
hashCode
在界面ChronoPeriod
- 重写:
-
hashCode
在课程Object
- 结果
- 合适的哈希码
- 另请参见:
-
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
-
toString
public String toString()
将此期间输出为String
,例如P6Y3M1D
。输出将采用ISO-8601期间格式。 零周期将表示为零天,'P0D'。
- Specified by:
-
toString
在界面ChronoPeriod
- 重写:
-
toString
在课程Object
- 结果
- 此期间的字符串表示形式,不为null
-
-