- java.lang.Object
-
- java.time.Period
-
- All Implemented Interfaces:
-
Serializable,ChronoPeriod,TemporalAmount
public final class Period extends Object implements ChronoPeriod, Serializable
ISO-8601日历系统中的日期时间,例如“2年3个月4天”。这个课程以年,月和日为单位建立数量或时间量。 请参阅
Duration的时间相当于此类。在
ZonedDateTime加入夏令时期间,持续时间和时间不同。 ADuration将添加确切的秒数,因此一天的持续时间总是24小时。 相比之下,Period将增加一个概念日,试图维持当地时间。例如,在夏令时间之前,请考虑在晚上添加一天的时间和一天的时间到18:00。
Period将在第二天的18:00添加概念日,结果为ZonedDateTime。 相比之下,Duration将正好添加24小时,从而在ZonedDateTime的19:00(假设一小时的DST差距)产生了ZonedDateTime。一段时间的支持单位为
YEARS,MONTHS和DAYS。 所有三个字段始终存在,但可以设置为零。ISO-8601日历系统是当今世界绝大多数的现代民用日历系统。 它相当于今天的闰年规则一直适用于日常生活的公历日历系统。
这个时期被模拟为一定的时间量,这意味着该时期的各个部分可能是负面的。
这是一个value-based课; 在
Period实例上使用身份敏感操作(包括引用等式(==),身份哈希码或同步)可能会产生不可预测的结果,应该避免。equals方法应用于比较。- 实现要求:
- 这个类是不可变的和线程安全的。
- 从以下版本开始:
- 1.8
- 另请参见:
- Serialized Form
-
-
方法摘要
所有方法 静态方法 接口方法 具体的方法 Modifier and Type 方法 描述 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)以指定的年数返回此期间的副本。-
Methods inherited from interface java.time.chrono.ChronoPeriod
between
-
-
-
-
字段详细信息
-
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,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返回值的TemporalUnit - 结果
- 单位的长期价值
- 异常
-
DateTimeException- 如果不支持本机 -
UnsupportedTemporalTypeException- 如果不支持本机
-
getUnits
public List<TemporalUnit> getUnits()
- Specified by:
-
getUnits在接口ChronoPeriod - Specified by:
-
getUnits在接口TemporalAmount - 结果
- 包含年份,月份和日期单位的列表,不为空
-
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 - 重写:
-
equals在Object - 参数
-
obj- 要检查的对象,null返回false - 结果
- 如果这等于其他时期,则为真
- 另请参见:
-
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 - 结果
- 此期间的字符串表示,不为空
-
-