- 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 方法 描述 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)
以指定的年数返回此期间的副本。-
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
- 结果
- 此期间的字符串表示,不为空
-
-