Documentation

This type represents a PostgreSQL interval. Intervals can have month, day, and microsecond components. Each component is bounded, so they are not arbitrary precision. For more information about intervals, consult the PostgreSQL documentation: https://www.postgresql.org/docs/17/datatype-datetime.html#DATATYPE-INTERVAL-INPUT.

Note that the time library provides several duration types that are not appropriate to use as PostgreSQL intervals:

• NominalDiffTime: Does not handle days or months. Allows up to picosecond precision. Is not bounded.
• CalendarDiffTime: Does not handle days. Embeds a NominalDiffTime. Is not bounded.
• CalendarDiffDays: Does not handle seconds. Is not bounded.

WARNING: The PostgreSQL interval parser is broken in versions prior to 15. It is not possible to round trip all intervals through PostgreSQL on those versions. You should upgrade to at least PostgreSQL version 15. For more information, see this patch: https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=e39f99046

The empty interval, representing no time at all.

>>> zero
MkInterval {months = 0, days = 0, microseconds = 0}

Creates an interval from a number of microseconds.

>>> fromMicroseconds 1
MkInterval {months = 0, days = 0, microseconds = 1}

Creates an interval from a number of milliseconds. Returns Nothing if the interval would overflow.

>>> fromMilliseconds 1
Just (MkInterval {months = 0, days = 0, microseconds = 1000})
>>> fromMilliseconds 9223372036854776
Nothing

Like fromMilliseconds but uses saturating arithmetic rather than returning Maybe.

>>> fromMillisecondsSaturating 1
MkInterval {months = 0, days = 0, microseconds = 1000}
>>> fromMillisecondsSaturating 9223372036854776
MkInterval {months = 0, days = 0, microseconds = 9223372036854775807}

Like fromMilliseconds but takes a type-level natural number as input. This is useful for writing literals without risk of overflow.

>>> fromMillisecondsLiteral (Proxy :: Proxy 1)
MkInterval {months = 0, days = 0, microseconds = 1000}

Creates an interval from a number of seconds. Returns Nothing if the interval would overflow.

>>> fromSeconds 1
Just (MkInterval {months = 0, days = 0, microseconds = 1000000})
>>> fromSeconds 9223372036855
Nothing

Like fromSeconds but uses saturating arithmetic rather than returning Maybe.

>>> fromSecondsSaturating 1
MkInterval {months = 0, days = 0, microseconds = 1000000}
>>> fromSecondsSaturating 9223372036855
MkInterval {months = 0, days = 0, microseconds = 9223372036854775807}

Like fromSeconds but takes a type-level natural number as input. This is useful for writing literals without risk of overflow.

>>> fromSecondsLiteral (Proxy :: Proxy 1)
MkInterval {months = 0, days = 0, microseconds = 1000000}

Creates an interval from a number of minutes. Returns Nothing if the interval would overflow.

>>> fromMinutes 1
Just (MkInterval {months = 0, days = 0, microseconds = 60000000})
>>> fromMinutes 153722867281
Nothing

Like fromMinutes but uses saturating arithmetic rather than returning Maybe.

>>> fromMinutesSaturating 1
MkInterval {months = 0, days = 0, microseconds = 60000000}
>>> fromMinutesSaturating 153722867281
MkInterval {months = 0, days = 0, microseconds = 9223372036854775807}

Like fromMinutes but takes a type-level natural number as input. This is useful for writing literals without risk of overflow.

>>> fromMinutesLiteral (Proxy :: Proxy 1)
MkInterval {months = 0, days = 0, microseconds = 60000000}

Creates an interval from a number of hours. Returns Nothing if the interval would overflow.

>>> fromHours 1
Just (MkInterval {months = 0, days = 0, microseconds = 3600000000})
>>> fromHours 2562047789
Nothing

Like fromHours but uses saturating arithmetic rather than returning Maybe.

>>> fromHoursSaturating 1
MkInterval {months = 0, days = 0, microseconds = 3600000000}
>>> fromHoursSaturating 2562047789
MkInterval {months = 0, days = 0, microseconds = 9223372036854775807}

Like fromHours but takes a type-level natural number as input. This is useful for writing literals without risk of overflow.

>>> fromHoursLiteral (Proxy :: Proxy 1)
MkInterval {months = 0, days = 0, microseconds = 3600000000}

Creates an interval from a number of days.

>>> fromDays 1
MkInterval {months = 0, days = 1, microseconds = 0}

Creates an interval from a number of weeks. Returns Nothing if the interval would overflow.

>>> fromWeeks 1
Just (MkInterval {months = 0, days = 7, microseconds = 0})
>>> fromWeeks 306783379
Nothing

Like fromWeeks but uses saturating arithmetic rather than returning Maybe.

>>> fromWeeksSaturating 1
MkInterval {months = 0, days = 7, microseconds = 0}
>>> fromWeeksSaturating 306783379
MkInterval {months = 0, days = 2147483647, microseconds = 0}

Like fromWeeks but takes a type-level natural number as input. This is useful for writing literals without risk of overflow.

>>> fromWeeksLiteral (Proxy :: Proxy 1)
MkInterval {months = 0, days = 7, microseconds = 0}

Creates an interval from a number of months.

>>> fromMonths 1
MkInterval {months = 1, days = 0, microseconds = 0}

Creates an interval from a number of years. Returns Nothing if the interval would overflow.

>>> fromYears 1
Just (MkInterval {months = 12, days = 0, microseconds = 0})
>>> fromYears 178956971
Nothing

Like fromYears but uses saturating arithmetic rather than returning Maybe.

>>> fromYearsSaturating 1
MkInterval {months = 12, days = 0, microseconds = 0}
>>> fromYearsSaturating 178956971
MkInterval {months = 2147483647, days = 0, microseconds = 0}

Like fromYears but takes a type-level natural number as input. This is useful for writing literals without risk of overflow.

>>> fromYearsLiteral (Proxy :: Proxy 1)
MkInterval {months = 12, days = 0, microseconds = 0}

Negates an interval. Returns Nothing if the result would overflow.

>>> negate (MkInterval 1 2 3)
Just (MkInterval {months = -1, days = -2, microseconds = -3})
>>> negate (MkInterval (-2147483648) 0 0)
Nothing

Like negate but uses saturating arithmetic rather than returning Maybe.

>>> negateSaturating (MkInterval 1 2 3)
MkInterval {months = -1, days = -2, microseconds = -3}
>>> negateSaturating (MkInterval (-2147483648) 0 0)
MkInterval {months = 2147483647, days = 0, microseconds = 0}

Adds two intervals. Returns Nothing if the result would overflow.

>>> add (fromMonths 1) (fromDays 2)
Just (MkInterval {months = 1, days = 2, microseconds = 0})
>>> add (fromDays 2147483647) (fromDays 1)
Nothing

Like add but uses saturating arithmetic rather than returning Maybe.

>>> addSaturating (fromMonths 1) (fromDays 2)
MkInterval {months = 1, days = 2, microseconds = 0}
>>> addSaturating (fromDays 2147483647) (fromDays 1)
MkInterval {months = 0, days = 2147483647, microseconds = 0}

Converts an interval into types from the time library. See fromTime for the opposite conversion.

>>> intoTime (MkInterval 1 2 3)
(P1M2D,0.000003s)

Converts types from the time library into an interval. See intoTime for the opposite conversion.

>>> fromTime ('Time.CalendarDiffDays' 1 2) 3
Just (MkInterval {months = 1, days = 2, microseconds = 3000000})

Returns Nothing if the result would overflow. See fromTimeSaturating for a version that uses saturating arithmetic instead.

>>> fromTime mempty 9223372036854.775808
Nothing

Note that this truncates extra precision.

>>> fromTime mempty 0.0000009
Just (MkInterval {months = 0, days = 0, microseconds = 0})

Like fromTime but uses saturating arithmetic rather than returning Maybe.

>>> fromTimeSaturating ('Time.CalendarDiffDays' 1 2) 3
MkInterval {months = 1, days = 2, microseconds = 3000000}
>>> fromTimeSaturating mempty 9223372036854.775808
MkInterval {months = 1, days = 2, microseconds = 9223372036854775807}

Scales an interval by the given ratio.

>>> scale 0.5 (MkInterval 2 4 8)
Just (MkInterval {months = 1, days = 2, microseconds = 4})
>>> scale 2 (MkInterval 2 4 8)
Just (MkInterval {months = 4, days = 8, microseconds = 16})

Each component is rounded.

>>> scale 0.4 (MkInterval 0 0 1) -- rounds down
Just (MkInterval {months = 0, days = 0, microseconds = 0})
>>> scale 0.5 (MkInterval 0 0 1) -- rounds half to even
Just (MkInterval {months = 0, days = 0, microseconds = 0})
>>> scale 0.6 (MkInterval 0 0 1) -- rounds up
Just (MkInterval {months = 0, days = 0, microseconds = 1})

Fractional days are converted into microseconds, assuming 24 hours per day.

>>> scale 0.5 (MkInterval 0 1 0)
Just (MkInterval {months = 0, days = 0, microseconds = 43200000000})

Fractional months are converted into days, assuming 30 days per month.

>>> scale 0.5 (MkInterval 1 0 0)
Just (MkInterval {months = 0, days = 15, microseconds = 0})

If this conversion produces fractional days, those are converted into microseconds.

>>> scale 0.05 (MkInterval 1 0 0)
Just (MkInterval {months = 0, days = 1, microseconds = 43200000000})

Returns Nothing if any component would overflow. See scaleSaturating for a version that uses saturating arithmetic instead.

>>> scale 2 (MkInterval 0 0 4611686018427387904)
Nothing

Note that due to rounding and conversion, scaling down and then up will not necessarily return the original interval.

>>> fmap (scale 2) (scale 0.5 (MkInterval 0 0 1))
Just (Just (MkInterval {months = 0, days = 0, microseconds = 0}))
>>> fmap (scale 2) (scale 0.5 (MkInterval 1 0 0))
Just (Just (MkInterval {months = 0, days = 30, microseconds = 0}))

Like scale but uses saturating arithmetic rather than returning Nothing on overflow.

>>> scaleSaturating 2 (MkInterval 0 0 4611686018427387904)
MkInterval {months = 0, days = 0, microseconds = 9223372036854775807}

Renders an interval to a Builder. This always has the same format: "@ A mon B day C hour D min E sec F us", where A, B, C, D, E, and F are signed integers.

This is not the most compact format, but it is very easy to interpret and does not require dealing with decimals (which could introduce precision problems).

>>> render MkInterval { months = 0, days = -1, microseconds = 2 }
"@ 0 mon -1 day 0 hour 0 min 0 sec +2 us"

Parses an interval. This is not a general purpose parser. It only supports the formats that PostgreSQL generates. For example, it will fail to parse an interval like "1 week" because PostgreSQL never uses weeks when rendering intervals.

One component of an interval. This is used to retain arbitrary precision for as long as possible before converting. It also shows which components are accepted, like years and months.

Converts a Component to an Interval. Returns Nothing if the component would overflow.

Converts a list of Components to an Interval. Returns Nothing if any of the components would overflow, or if adding any of them together would overflow.