Class Interval

java.lang.Object
io.r2dbc.postgresql.codec.Interval
All Implemented Interfaces:
Serializable, ChronoPeriod, TemporalAmount
public final class Interval extends Object implements ChronoPeriod, Serializable
Value object that maps to the interval datatype in Postgres.

This class models a quantity or amount of time in terms of years, months, days, hours, minutes, seconds, and microseconds. In addition to accessing its individual properties, its values can be retrieved as Period and Duration.

A physical duration could be of infinite length. For practicality, the duration is stored using integers without normalization. Normalizing applies separate normalization following IsoChronology. Days/hours/minutes/seconds/microseconds and years/months are normalized independent from each other to avoid month rollover as the amount of days per month varies by per month and leap year. Day normalization (e.g. more than 28/29/30/31 days) can only be applied in the context of an actual date hence it's not supported by this class. Normalizing an interval of 14 months and 43 days results in an interval of 1 year, 2 months, and 43 days.

An interval can be created either from a ISO-8601 or Postgres representation using parse(String). It can also be created from a TemporalAmount or as function accepting temporal start and end values through between(Temporal, Temporal).

This class is immutable and thread-safe.

Since:
0.8.7
See Also:

  • Field Details

    • ZERO

      public static final Interval ZERO
      Constant for a duration of zero.

  • Method Details

    • of

      public static Interval of(Period period)
      Create a new Interval given a period object.
      Parameters:
      period - the period object
      Returns:
      the new Interval object
      Throws:
      IllegalArgumentException - if period is null

    • of

      public static Interval of(Duration duration)
      Create a new Interval given a duration object.
      Parameters:
      duration - the duration object
      Returns:
      the new Interval object
      Throws:
      IllegalArgumentException - if duration is null

    • of

      public static Interval of(Period period, Duration duration)
      Create a new Interval given a period and duration object.
      Parameters:
      period - the period object
      duration - the duration object
      Returns:
      the new Interval object
      Throws:
      IllegalArgumentException - if period or duration is null

    • of

      public static Interval of(int years, int months, int days, int hours, int minutes, double seconds)
      Create a new Interval given the years, months, days, hours, minutes, and seconds.
      Parameters:
      years - interval years
      months - interval months
      days - interval days
      hours - interval hours
      minutes - interval minutes
      seconds - interval seconds including microseconds as fraction
      Returns:
      the new Interval object

    • of

      public static Interval of(int years, int months, int days, int hours, int minutes, int seconds, int microseconds)
      Create a new Interval given the years, months, days, hours, minutes, seconds, and microseconds.
      Parameters:
      years - interval years
      months - interval months
      days - interval days
      hours - interval hours
      minutes - interval minutes
      seconds - interval seconds
      microseconds - interval microseconds
      Returns:
      the new Interval object

    • between

      public static Interval between(Temporal startInclusive, Temporal endExclusive)
      Create a new Interval 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
      endExclusive - the end, exclusive
      Returns:
      the number of days between this date and the end date, not null
      Throws:
      IllegalArgumentException - if startInclusive or endExclusive is null

    • from

      public static Interval from(TemporalAmount amount)
      Create a new Interval 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
      Returns:
      the equivalent duration
      Throws:
      DateTimeException - if unable to convert to a Duration
      ArithmeticException - if numeric overflow occurs
      IllegalArgumentException - if amount is null

    • parse

      public static Interval parse(String value)
      Parse the value representing a Interval. This method only supports values that Postgres returns.
      Parameters:
      value - a string that represents the interval value
      Returns:
      the new Interval object
      Throws:
      IllegalArgumentException - if value is null or contains an invalid format

    • getYears

      public int getYears()
      Return the years represented by this interval.
      Returns:
      the years represented by this interval

    • getMonths

      public int getMonths()
      Return the months represented by this interval.
      Returns:
      the months represented by this interval

    • getDays

      public int getDays()
      Return the days represented by this interval.
      Returns:
      the days represented by this interval

    • getHours

      public int getHours()
      Return the hours represented by this interval.
      Returns:
      the hours represented by this interval

    • getMinutes

      public int getMinutes()
      Return the hours represented by this interval.
      Returns:
      the hours represented by this interval

    • getSeconds

      public double getSeconds()
      Return the seconds represented by this interval.
      Returns:
      seconds represented by this interval

    • getSecondsInMinute

      public int getSecondsInMinute()
      Return the seconds represented by this interval.
      Returns:
      seconds represented by this interval

    • getMicrosecondsInSecond

      public int getMicrosecondsInSecond()
      Return the microseconds represented by this interval.
      Returns:
      microseconds represented by this interval

    • get

      public long get(TemporalUnit unit)
      Specified by:
      get in interface ChronoPeriod
      Specified by:
      get in interface TemporalAmount

    • getUnits

      public List<TemporalUnit> getUnits()
      Specified by:
      getUnits in interface ChronoPeriod
      Specified by:
      getUnits in interface TemporalAmount

    • addTo

      public Temporal addTo(Temporal temporal)
      Specified by:
      addTo in interface ChronoPeriod
      Specified by:
      addTo in interface TemporalAmount

    • subtractFrom

      public Temporal subtractFrom(Temporal temporal)
      Specified by:
      subtractFrom in interface ChronoPeriod
      Specified by:
      subtractFrom in interface TemporalAmount

    • plus

      public Interval plus(TemporalAmount amountToAdd)
      Specified by:
      plus in interface ChronoPeriod

    • minus

      public Interval minus(TemporalAmount amountToSubtract)
      Specified by:
      minus in interface ChronoPeriod

    • getChronology

      public Chronology getChronology()
      Specified by:
      getChronology in interface ChronoPeriod

    • multipliedBy

      public Interval multipliedBy(int scalar)
      Specified by:
      multipliedBy in interface ChronoPeriod

    • normalized

      public Interval normalized()
      Specified by:
      normalized in interface ChronoPeriod

    • withYears

      public Interval withYears(int years)
      Return a copy instance of Interval applying the current interval and adjusting years given years.
      Parameters:
      years - the new years value to apply
      Returns:
      a new instance of Interval with years applied

    • withMonths

      public Interval withMonths(int months)
      Return a copy a new instance of Interval applying the current interval and adjusting years given months.
      Parameters:
      months - the new months value to apply
      Returns:
      a new instance of Interval with months applied

    • withDays

      public Interval withDays(int days)
      Return a new instance of Interval applying the current interval and adjusting years given days.
      Parameters:
      days - the new days value to apply
      Returns:
      a new instance of Interval with days applied

    • withHours

      public Interval withHours(int hours)
      Return a new instance of Interval applying the current interval and adjusting years given hours.
      Parameters:
      hours - the new hours value to apply
      Returns:
      a new instance of Interval with hours applied

    • withMinutes

      public Interval withMinutes(int minutes)
      Return a new instance of Interval applying the current interval and adjusting years given minutes.
      Parameters:
      minutes - the new minutes value to apply
      Returns:
      a new instance of Interval with minutes applied

    • withSeconds

      public Interval withSeconds(int seconds)
      Return a new instance of Interval applying the current interval and adjusting years given seconds.
      Parameters:
      seconds - the new seconds value to apply
      Returns:
      a new instance of Interval with seconds applied

    • withMicroseconds

      public Interval withMicroseconds(int microseconds)
      Return a new instance of Interval applying the current interval and adjusting years given microseconds.
      Parameters:
      microseconds - the new microseconds value to apply
      Returns:
      a new instance of Interval with seconds applied

    • getPeriod

      public Period getPeriod()
      Return the years, months, and days as Period.
      Returns:
      the years, months, and days as Period.

    • getDuration

      public Duration getDuration()
      Return the hours, minutes, seconds and microseconds as Duration.
      Returns:
      the hours, minutes, seconds and microseconds as Duration.

    • getValue

      public String getValue()
      Return a string representing the interval value.
      Returns:
      a string representing the interval value

    • equals

      public boolean equals(Object o)
      Specified by:
      equals in interface ChronoPeriod
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface ChronoPeriod
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Specified by:
      toString in interface ChronoPeriod
      Overrides:
      toString in class Object