Duration

Duration

Duration ()

add

Duration add (Duration rhs)

计算值为 this+rhs的新持续时间。

例如，

 "1 day" + "-3 days" = "-2 days"
 "1 year" + "1 day" = "1 year and 1 day"
 "-(1 hour,50 minutes)" + "-20 minutes" = "-(1 hours,70 minutes)"
 "15 hours" + "-3 days" = "-(2 days,9 hours)"
 "1 year" + "-1 day" = IllegalStateException
 

由于没有办法从1个月内有意义地减去1天，所以有些情况下 IllegalStateException中的操作失败。

形式上，计算定义如下。

首先，我们可以假设两个 Duration被增补为正不失一般性（即 (-X)+Y=Y-X ， X+(-Y)=X-Y ， (-X)+(-Y)=-(X+Y) ）

两个正数 Duration的添加仅仅被定义为逐字段添加，其中缺少的字段被视为0。

当且仅当两个输入 Duration的相应字段 Duration设置时，结果 Duration字段将被取消设置。

请注意，如果 lhs.signum()*rhs.signum()!=-1或两者 lhs.signum()*rhs.signum()!=-1一化，则 lhs.add(rhs)将总是成功。

addTo

void addTo (Calendar calendar)

将此持续时间添加到 Calendar对象。

如果这些字段存在，按年，月，日，小时，分钟，秒和毫秒的顺序拨打add(int, int) 。 由于Calendar类使用int来保存值，因此有时会出现此方法无法正常工作的情况（例如，如果字段值超出int范围）。

此外，由于此持续时间类别是格里高利持续时间，因此如果给定的 Calendar对象基于其他日历系统，则此方法无法正常工作。

超过毫秒的Duration对象的任何小数部分都将被忽略。 例如，如果这个持续时间是“P1.23456S”，那么1被添加到SECONDS，234被添加到MILLISECONDS，其余的将不被使用。

需要注意的是，因为add(int, int)是使用int， Duration与超越在其领域int范围值将导致溢/下溢给定Calendar 。 add(Duration)提供了与此方法相同的基本操作，同时避免了上溢/下溢问题。

addTo

void addTo (Date date)

将此持续时间添加到 Date对象。

首先将给定日期转换为 GregorianCalendar ，然后持续时间与 addTo(Calendar)方法完全相同。

然后将更新的时刻转换回 Date对象，并用于更新给定的 Date对象。

这个有点多余的计算是明确确定月份和年份的持续时间所必需的。

compare

int compare (Duration duration)

与此 Duration实例的部分订购关系比较。

比较结果必须符合 W3C XML Schema 1.0 Part 2, Section 3.2.7.6.2, Order relation on duration 。

返回：

• LESSER if this Duration is shorter than duration parameter
• EQUAL if this Duration is equal to duration parameter
• GREATER if this Duration is longer than duration parameter
• INDETERMINATE if a conclusive partial order relation cannot be determined

equals

boolean equals (Object duration)

检查此持续时间对象是否与另一个 Duration对象具有相同的持续时间。

例如，“P1D”（1天）等于“PT24H”（24小时）。

当且仅当时间点t + X和t + Y对于XML Schema 1.0规范第3.2.6.2节中规定的所有测试时间点相同时，持续时间X等于Y.

请注意，有些情况下两个Duration彼此“无法比拟”，例如一个月和30天。 例如，

 !new Duration("P1M").isShorterThan(new Duration("P30D"))
 !new Duration("P1M").isLongerThan(new Duration("P30D"))
 !new Duration("P1M").equals(new Duration("P30D"))
 

getDays

int getDays ()

获得DAYS字段的值作为整数值，如果不存在，则为0。 此方法的工作原理与getYears()类似，只不过此方法在DAYS字段中起作用。

getField

Number getField (DatatypeConstants.Field field)

获取字段的值。 持续时间对象的字段可能包含任意大的值。 因此，此方法旨在返回一个Number对象。 在YEARS，MONTHS，DAYS，HOURS和MINUTES的情况下，返回的数字将是一个非负整数。 在秒的情况下，返回的数字可能是非负的十进制值。

getHours

int getHours ()

获取HOURS字段的值作为整数值，如果不存在，则为0。 此方法的工作方式与getYears()类似，只是此方法适用于HOURS字段。

getMinutes

int getMinutes ()

获取MINUTES字段的值作为整数值，如果不存在，则为0。 此方法的工作原理与getYears()类似，但此方法适用于MINUTES字段。

getMonths

int getMonths ()

获取MONTHS字段的值作为整数值，如果不存在，则为0。 此方法的工作原理与getYears()类似，只是此方法适用于MONTHS字段。

getSeconds

int getSeconds ()

获取SECONDS字段的值作为整数值，如果不存在，则为0。 此方法的工作原理与getYears()类似，只不过此方法适用于SECONDS字段。

getSign

int getSign ()

以-1,0或1返回此持续时间的符号。

getTimeInMillis

long getTimeInMillis (Calendar startInstant)

以毫秒为单位返回持续时间的长度。

如果秒字段携带的数字超过毫秒级别，则会丢弃这些数字（或换句话说，舍入为零）。例如，对于任何日历值 x ，

 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.
 

请注意，此方法使用addTo(Calendar)方法，该方法可能与其字段中值非常大的Duration对象错误地工作。 有关详细信息，请参阅addTo(Calendar)方法。

getTimeInMillis

long getTimeInMillis (Date startInstant)

以毫秒为单位返回持续时间的长度。

如果秒字段携带的数字超过毫秒级别，则会丢弃这些数字（或换句话说，舍入为零）。例如，对于任何 Date值 x ，

 new Duration("PT10.00099S").getTimeInMills(x) == 10000.
 new Duration("-PT10.00099S").getTimeInMills(x) == -10000.
 

请注意，此方法使用addTo(Date)方法，该方法可能与其字段中值非常大的Duration对象错误地工作。 有关详细信息，请参阅addTo(Date)方法。

getXMLSchemaType

QName getXMLSchemaType ()

返回此实例映射到的XML模式日期/时间类型的名称。 类型根据设置的字段进行计算，即isSet(DatatypeConstants.Field) == true 。

getYears

int getYears ()

得到这个年值 Duration为 int或者 0 ，如果不存在。

getYears()为方便方法 getField(DatatypeConstants.YEARS) 。

As the return value is an int, an incorrect value will be returned for Durations with years that go beyond the range of an int. Use getField(DatatypeConstants.YEARS) to avoid possible loss of precision.

hashCode

int hashCode ()

返回与equals方法的定义一致的散列码。

isLongerThan

boolean isLongerThan (Duration duration)

检查此持续时间对象是否严格超过另一个 Duration对象。

当且仅当X> Y（如XML Schema 1.0规范的3.2.6.2节中定义）时，持续时间X比Y长。

例如，“P1D”（一天）>“PT12H”（12小时）和“P2Y”（两年）>“P23M”（23个月）。

isSet

boolean isSet (DatatypeConstants.Field field)

检查是否设置了字段。 持续时间对象的字段可能存在也可能不存在。 此方法可用于测试字段是否存在。

isShorterThan

boolean isShorterThan (Duration duration)

检查此持续时间对象是否严格短于另一个 Duration对象。

multiply

Duration multiply (int factor)

计算一个新的持续时间，其值比此持续时间的值长 factor倍。

This method is provided for the convenience. It is functionally equivalent to the following code:

 multiply(new BigDecimal(String.valueOf(factor)))
 

multiply

Duration multiply (BigDecimal factor)

计算一个新的持续时间，其值比该持续时间的值长 factor倍。

例如，

 "P1M" (1 month) * "12" = "P12M" (12 months)
 "PT1M" (1 min) * "0.3" = "PT18S" (18 seconds)
 "P1M" (1 month) * "1.5" = IllegalStateException
 

由于Duration类是不可变的，因此此方法不会更改此对象的值。 它只是计算一个新的Duration对象并返回它。

该操作将以BigDecimal的精度逐场进行。 由于除秒以外的所有字段都限制为保持整数，因此计算产生的任何分数都将向下传递给下一个单元。 例如，如果您将“P1D”（1天）与“0.5”相乘，那么它将为0.5天，这将被降至“PT12H”（12小时）。 当月份的分数不能有意义地持续到几天或一年到几个月时，这将导致IllegalStateException被抛出。 例如，如果您将一个月乘以0.5。

要避免 IllegalStateException ，请使用 normalizeWith(Calendar)方法删除年份和月份字段。

negate

Duration negate ()

返回一个新 Duration对象，其值是 -this 。

由于Duration类是不可变的，因此此方法不会更改此对象的值。 它只是计算一个新的Duration对象并返回它。

normalizeWith

Duration normalizeWith (Calendar startTimeInstant)

将特定时间点作为参考点，将年份和月份字段转换为日期字段。

例如，对于开始时间实例“2003年7月8日，17：40：32”，一个月的持续时间标准化为31天。

形式上，计算如下完成：

1. the given Calendar object is cloned
2. the years, months and days fields will be added to the Calendar object by using the add(int, int) method
3. the difference between the two Calendars in computed in milliseconds and converted to days, if a remainder occurs due to Daylight Savings Time, it is discarded
4. the computed days, along with the hours, minutes and seconds fields of this duration object is used to construct a new Duration object.

请注意，由于Calendar类使用 int来保存年份和月份的值，因此如果此持续时间对象在年份或月份字段中包含非常大的值，则此方法可能会产生意外的结果。

subtract

Duration subtract (Duration rhs)

计算值为 this-rhs的新持续时间。

例如：

 "1 day" - "-3 days" = "4 days"
 "1 year" - "1 day" = IllegalStateException
 "-(1 hour,50 minutes)" - "-20 minutes" = "-(1hours,30 minutes)"
 "15 hours" - "-3 days" = "3 days and 15 hours"
 "1 year" - "-1 day" = "1 year and 1 day"
 

由于没有办法从1个月有意义地减去1天，所以有些情况下 IllegalStateException中的操作失败。

正式的计算定义如下。 首先，我们可以假设两个Duration均为正数而不失一般性。 （即， (-X)-Y=-(X+Y) ， X-(-Y)=X+Y ， (-X)-(-Y)=-(X-Y) ）

然后逐场减去两个持续时间。 如果任何非零字段F的符号与最高有效字段的符号不同，则1（如果F为负）或-1（否则）将从下一个更大的单位F中借用 。

重复此过程，直到所有非零字段具有相同的符号。

如果借款发生在天数字段中（换句话说，如果计算需要借用1个月或-1个月来补偿天数），则计算失败，投掷 IllegalStateException 。

toString

String toString ()

返回此 Duration Object的 String表示 Object 。

结果按照XML Schema 1.0规范进行格式化，并且总是可以稍后解析为 Duration Object newDuration(String) 。

在形式上，以下任何 Duration Object x都适用：

 new Duration(x.toString()).equals(x)