- 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小时,在ZonedDateTime19:00产生ZonedDateTime(假设DST差距为1小时)。一段时间的支持单位为
YEARS,MONTHS和DAYS。 所有三个字段始终存在,但可以设置为零。ISO-8601日历系统是当今世界大部分地区使用的现代民用日历系统。 它等同于公历的格里高利历法系统,其中今天的闰年规则一直适用。
该时期被建模为指示的时间量,意味着该时期的各个部分可能是负的。
这是一个value-based班; 在
Period实例上使用身份敏感操作(包括引用相等(==),标识哈希码或同步)可能会产生不可预测的结果,应该避免使用。 应使用equals方法进行比较。- 实现要求:
- 这个类是不可变的和线程安全的。
- 从以下版本开始:
- 1.8
- 另请参见:
- Serialized Form
-
-
方法摘要
所有方法 静态方法 实例方法 具体的方法 变量和类型 方法 描述 TemporaladdTo(Temporal temporal)将此句点添加到指定的时态对象。static Periodbetween(LocalDate startDateInclusive, LocalDate endDateExclusive)获得Period包括两个日期之间的年数,月数和天数。booleanequals(Object obj)检查此期间是否等于另一期间。static Periodfrom(TemporalAmount amount)从时间量获得Period的实例。longget(TemporalUnit unit)获取所请求单元的值。IsoChronologygetChronology()获取此期间的年表,即ISO日历系统。intgetDays()获取此期间的天数。intgetMonths()获取此期间的月数。List<TemporalUnit>getUnits()获取此句点支持的单位集。intgetYears()获取此期间的年数。inthashCode()此期间的哈希码。booleanisNegative()检查此期间的三个单位中的任何一个是否为负数。booleanisZero()检查此期间的所有三个单位是否为零。Periodminus(TemporalAmount amountToSubtract)返回此期间的副本,并减去指定的期间。PeriodminusDays(long daysToSubtract)返回此期间的副本,并减去指定的天数。PeriodminusMonths(long monthsToSubtract)返回此期间的副本,并减去指定的月份。PeriodminusYears(long yearsToSubtract)返回此期间的副本,并减去指定的年份。PeriodmultipliedBy(int scalar)返回一个新实例,该周期中的每个元素乘以指定的标量。Periodnegated()返回一个新实例,此期间的每个金额都被否定。Periodnormalized()返回此期间的副本,其中年份和月份已标准化。static Periodof(int years, int months, int days)获得代表若干年,月和日的Period。static PeriodofDays(int days)获得代表若干天的Period。static PeriodofMonths(int months)获得代表若干个月的Period。static PeriodofWeeks(int weeks)获得代表若干周的Period。static PeriodofYears(int years)获得代表Period。static Periodparse(CharSequence text)获得Period从文本字符串,如PnYnMnD。Periodplus(TemporalAmount amountToAdd)返回此期间的副本,并添加指定的期间。PeriodplusDays(long daysToAdd)返回此期间的副本,并添加指定的天数。PeriodplusMonths(long monthsToAdd)返回此期间的副本,并添加指定的月份。PeriodplusYears(long yearsToAdd)返回此期间的副本,并添加指定年份。TemporalsubtractFrom(Temporal temporal)从指定的时态对象中减去此句点。StringtoString()将此期间输出为String,例如P6Y3M1D。longtoTotalMonths()获取此期间的总月数。PeriodwithDays(int days)返回具有指定天数的此期间的副本。PeriodwithMonths(int months)返回具有指定月份数的此期间的副本。PeriodwithYears(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:
-
getUnitsin 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:
-
isNegativein 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
-
-