Package com.impossibl.postgres.api.data

Class Interval

java.lang.Object

com.impossibl.postgres.api.data.Interval

All Implemented Interfaces:

Serializable, TemporalAmount

public final class Interval
extends Object
implements TemporalAmount, Serializable

An amount of time in the ISO-8601 calendar system that combines a period and a duration.

This class models a quantity or amount of time in terms of a Period and Duration. A period is a date-based amount of time, consisting of years, months and days. A duration is a time-based amount of time, consisting of seconds and nanoseconds. See the Period and Duration classes for more details.

The days in a period take account of daylight saving changes (23 or 25 hour days). When performing calculations, the period is added first, then the duration.

The model is of a directed amount, meaning that the amount may be negative.

Implementation Requirements:

This class is immutable and thread-safe.

This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static Interval	ZERO	A constant for a duration of zero.

Method Summary

Modifier and Type	Method	Description
Temporal	addTo(Temporal temporal)	Adds this amount to the specified temporal object.
static Interval	between(Temporal startInclusive, Temporal endExclusive)	Obtains an instance consisting of the amount of time between two temporals.
boolean	equals(Object otherAmount)	Checks if this amount is equal to the specified PeriodDuration.
static Interval	from(TemporalAmount amount)	Obtains an instance from a temporal amount.
long	get(TemporalUnit unit)	Gets the value of the requested unit.
Duration	getDuration()	Gets the duration part.
Period	getPeriod()	Gets the period part.
List<TemporalUnit>	getUnits()	Gets the set of units supported by this amount.
int	hashCode()	A hash code for this amount.
boolean	isZero()	Checks if all parts of this amount are zero.
Interval	minus(TemporalAmount amountToAdd)	Returns a copy of this amount with the specified amount subtracted.
Interval	multipliedBy(int scalar)	Returns an instance with the amount multiplied by the specified scalar.
Interval	negated()	Returns an instance with the amount negated.
Interval	normalizedStandardDays()	Returns a copy of this instance with the days and duration normalized using the standard day of 24 hours.
Interval	normalizedYears()	Returns a copy of this instance with the years and months exactly normalized.
static Interval	of(Duration duration)	Obtains an instance based on a duration.
static Interval	of(Period period)	Obtains an instance based on a period.
static Interval	of(Period period, Duration duration)	Obtains an instance based on a period and duration.
static Interval	parse(CharSequence text)	Obtains an instance from a text string such as PnYnMnDTnHnMnS.
Interval	plus(TemporalAmount amountToAdd)	Returns a copy of this amount with the specified amount added.
Temporal	subtractFrom(Temporal temporal)	Subtracts this amount from the specified temporal object.
String	toString()	Returns a string representation of the amount.
Interval	withDuration(Duration duration)	Returns a copy of this period-duration with a different duration.
Interval	withPeriod(Period period)	Returns a copy of this period-duration with a different period.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ZERO

public static final Interval ZERO

A constant for a duration of zero.

Method Detail

of

public static Interval of(Period period,
                          Duration duration)

Obtains an instance based on a period and duration.

The total amount of time of the resulting instance is the period plus the duration.

Parameters:

period - the period, not null

duration - the duration, not null

Returns:

the combined period-duration, not null

of

public static Interval of(Period period)

Obtains an instance based on a period.

The duration will be zero.

Parameters:

period - the period, not null

Returns:

the combined period-duration, not null

of

public static Interval of(Duration duration)

Obtains an instance based on a duration.

The period will be zero.

Parameters:

duration - the duration, not null

Returns:

the combined period-duration, not null

from

public static Interval from(TemporalAmount amount)

Obtains an instance from a temporal amount.

This obtains an instance based on the specified amount. A TemporalAmount represents an amount of time which this factory extracts to a Interval.

The result is calculated by looping around each unit in the specified amount. Any amount that is zero is ignore. If a unit has an exact duration, it will be totalled using Duration.plus(Duration). If the unit is days or weeks, it will be totalled into the days part of the period. If the unit is months or quarters, it will be totalled into the months part of the period. If the unit is years, decades, centuries or millennia, it will be totalled into the years part of the period.

Parameters:

amount - the temporal amount to convert, not null

Returns:

the equivalent duration, not null

Throws:

DateTimeException - if unable to convert to a Duration

ArithmeticException - if numeric overflow occurs

parse

public static Interval parse(CharSequence text)

Obtains an instance from a text string such as PnYnMnDTnHnMnS.

This will parse the string produced by toString() which is based on the ISO-8601 period formats PnYnMnDTnHnMnS and PnW.

The string starts with an optional sign, denoted by the ASCII negative or positive symbol. If negative, the whole amount is negated. The ASCII letter "P" is next in upper or lower case. There are then a number of sections, each consisting of a number and a suffix. At least one of the sections must be present. The sections have suffixes in ASCII of "Y" for years, "M" for months, "W" for weeks, "D" for days, "H" for hours, "M" for minutes, "S" for seconds, accepted in upper or lower case. Note that the ASCII letter "T" separates the date and time parts and must be present if any time part is present. The suffixes must occur in order. The number part of each section must consist of ASCII digits. The number may be prefixed by the ASCII negative or positive symbol. The number must parse to an int. Any week-based input is multiplied by 7 and treated as a number of days.

The leading plus/minus sign, and negative values for weeks and days are not part of the ISO-8601 standard.

Note that the date style format PYYYY-MM-DDTHH:MM:SS is not supported.

For example, the following are valid inputs:

   "P2Y"             -- PeriodDuration.of(Period.ofYears(2))
   "P3M"             -- PeriodDuration.of(Period.ofMonths(3))
   "P4W"             -- PeriodDuration.of(Period.ofWeeks(4))
   "P5D"             -- PeriodDuration.of(Period.ofDays(5))
   "PT6H"            -- PeriodDuration.of(Duration.ofHours(6))
   "P1Y2M3D"         -- PeriodDuration.of(Period.of(1, 2, 3))
   "P1Y2M3W4DT8H"    -- PeriodDuration.of(Period.of(1, 2, 25), Duration.ofHours(8))
   "P-1Y2M"          -- PeriodDuration.of(Period.of(-1, 2, 0))
   "-P1Y2M"          -- PeriodDuration.of(Period.of(-1, -2, 0))
 

Parameters:

text - the text to parse, not null

Returns:

the parsed period, not null

Throws:

DateTimeParseException - if the text cannot be parsed to a period

between

public static Interval between(Temporal startInclusive,
                               Temporal endExclusive)

Obtains an instance consisting of the amount of time between two temporals.

The start is included, but the end is not. The result of this method can be negative if the end is before the start.

The calculation examines the temporals and extracts LocalDate and LocalTime. If the time is missing, it will be defaulted to midnight. If one date is missing, it will be defaulted to the other date. It then finds the amount of time between the two dates and between the two times.

Parameters:

startInclusive - the start, inclusive, not null

endExclusive - the end, exclusive, not null

Returns:

the number of days between this date and the end date, not null

get

public long get(TemporalUnit unit)

Gets the value of the requested unit.

This returns a value for the supported units - ChronoUnit.YEARS, ChronoUnit.MONTHS, ChronoUnit.DAYS, ChronoUnit.SECONDS and ChronoUnit.NANOS. All other units throw an exception. Note that hours and minutes throw an exception.

Specified by:

get in interface TemporalAmount

Parameters:

unit - the TemporalUnit for which to return the value

Returns:

the long value of the unit

Throws:

UnsupportedTemporalTypeException - if the unit is not supported

getUnits

public List<TemporalUnit> getUnits()

Gets the set of units supported by this amount.

This returns the list ChronoUnit.YEARS, ChronoUnit.MONTHS, ChronoUnit.DAYS, ChronoUnit.SECONDS and ChronoUnit.NANOS.

This set can be used in conjunction with get(TemporalUnit) to access the entire state of the amount.

Specified by:

getUnits in interface TemporalAmount

Returns:

a list containing the days unit, not null

getPeriod

public Period getPeriod()

Gets the period part.

Returns:

the period part

withPeriod

public Interval withPeriod(Period period)

Returns a copy of this period-duration with a different period.

This instance is immutable and unaffected by this method call.

Parameters:

period - the new period

Returns:

the updated period-duration

getDuration

public Duration getDuration()

Gets the duration part.

Returns:

the duration part

withDuration

public Interval withDuration(Duration duration)

Returns a copy of this period-duration with a different duration.

This instance is immutable and unaffected by this method call.

Parameters:

duration - the new duration

Returns:

the updated period-duration

isZero

public boolean isZero()

Checks if all parts of this amount are zero.

This returns true if both Period.isZero() and Duration.isZero() return true.

Returns:

true if this period is zero-length

plus

public Interval plus(TemporalAmount amountToAdd)

Returns a copy of this amount with the specified amount added.

The parameter is converted using from(TemporalAmount). The period and duration are combined separately.

This instance is immutable and unaffected by this method call.

Parameters:

amountToAdd - the amount to add, not null

Returns:

a Days based on this instance with the requested amount added, not null

Throws:

DateTimeException - if the specified amount contains an invalid unit

ArithmeticException - if numeric overflow occurs

minus

public Interval minus(TemporalAmount amountToAdd)

Returns a copy of this amount with the specified amount subtracted.

The parameter is converted using from(TemporalAmount). The period and duration are combined separately.

This instance is immutable and unaffected by this method call.

Parameters:

amountToAdd - the amount to add, not null

Returns:

a Days based on this instance with the requested amount subtracted, not null

Throws:

DateTimeException - if the specified amount contains an invalid unit

ArithmeticException - if numeric overflow occurs

multipliedBy

public Interval multipliedBy(int scalar)

Returns an instance with the amount multiplied by the specified scalar.

This instance is immutable and unaffected by this method call.

Parameters:

scalar - the scalar to multiply by, not null

Returns:

the amount multiplied by the specified scalar, not null

Throws:

ArithmeticException - if numeric overflow occurs

negated

public Interval negated()

Returns an instance with the amount negated.

This instance is immutable and unaffected by this method call.

Returns:

the negated amount, not null

Throws:

ArithmeticException - if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE

normalizedYears

public Interval normalizedYears()

Returns a copy of this instance with the years and months exactly normalized.

This normalizes the years and months units, leaving the days unit unchanged. The result is exact, always representing the same amount of time.

The months unit is adjusted to have an absolute value less than 11, with the years unit being adjusted to compensate. For example, a period of "1 year and 15 months" will be normalized to "2 years and 3 months".

The sign of the years and months units will be the same after normalization. For example, a period of "1 year and -25 months" will be normalized to "-1 year and -1 month".

Note that no normalization is performed on the days or duration.

This instance is immutable and unaffected by this method call.

Returns:

a PeriodDuration based on this one with excess months normalized to years, not null

Throws:

ArithmeticException - if numeric overflow occurs

normalizedStandardDays

public Interval normalizedStandardDays()

Returns a copy of this instance with the days and duration normalized using the standard day of 24 hours.

This normalizes the days and duration, leaving the years and months unchanged. The result uses a standard day length of 24 hours.

This combines the duration seconds with the number of days and shares the total seconds between the two fields. For example, a period of "2 days and 86401 seconds" will be normalized to "3 days and 1 second".

The sign of the days and duration will be the same after normalization. For example, a period of "1 day and -172801 seconds" will be normalized to "-1 day and -1 second".

Note that no normalization is performed on the years or months.

This instance is immutable and unaffected by this method call.

Returns:

a PeriodDuration based on this one with excess duration normalized to days, not null

Throws:

ArithmeticException - if numeric overflow occurs

addTo

public Temporal addTo(Temporal temporal)

Adds this amount to the specified temporal object.

This returns a temporal object of the same observable type as the input with this amount added. This simply adds the period and duration to the temporal.

This instance is immutable and unaffected by this method call.

Specified by:

addTo in interface TemporalAmount

Parameters:

temporal - the temporal object to adjust, not null

Returns:

an object of the same type with the adjustment made, not null

Throws:

DateTimeException - if unable to add

UnsupportedTemporalTypeException - if the DAYS unit is not supported

ArithmeticException - if numeric overflow occurs

subtractFrom

public Temporal subtractFrom(Temporal temporal)

Subtracts this amount from the specified temporal object.

This returns a temporal object of the same observable type as the input with this amount subtracted. This simply subtracts the period and duration from the temporal.

This instance is immutable and unaffected by this method call.

Specified by:

subtractFrom in interface TemporalAmount

Parameters:

temporal - the temporal object to adjust, not null

Returns:

an object of the same type with the adjustment made, not null

Throws:

DateTimeException - if unable to subtract

UnsupportedTemporalTypeException - if the DAYS unit is not supported

ArithmeticException - if numeric overflow occurs

equals

public boolean equals(Object otherAmount)

Checks if this amount is equal to the specified PeriodDuration.

The comparison is based on the underlying period and duration.

Overrides:

equals in class Object

Parameters:

otherAmount - the other amount, null returns false

Returns:

true if the other amount is equal to this one

hashCode

public int hashCode()

A hash code for this amount.

Overrides:

hashCode in class Object

Returns:

a suitable hash code

toString

public String toString()

Returns a string representation of the amount. This will be in the format 'PnYnMnDTnHnMnS', with sections omitted as necessary. An empty amount will return "PT0S".

Overrides:

toString in class Object

Returns:

the period in ISO-8601 string format