Modulepostgresql-simple-interval-1.0.1.2Haskell2010

Database.PostgreSQL.Simple.Interval.Unstable

2 types
50 values

Packagepostgresql-simple-interval-1.0.1.2
Exports52
LanguageHaskell2010
Licence0BSD
SourceUnstable.hs

datadata Interval

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:

Data.Time.NominalDiffTime: Does not handle days or months. Allows up to picosecond precision. Is not bounded.
Data.Time.CalendarDiffTime: Does not handle days. Embeds a NominalDiffTime. Is not bounded.
Data.Time.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

Constructors

MkInterval
- months :: !Int32
- days :: !Int32
- microseconds :: !Int64

Instances7Eq, Show, PersistField, PersistFieldSql, FromField, ToField, …

Eq IntervalDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable
Show IntervalDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable
PersistField IntervalDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable
Behaves the same as the FromField and ToField instances.
PersistFieldSql IntervalDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable
```
SqlOther "interval"
```
FromField IntervalDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable
Uses parse. Ensures that the OID is intervalOid.
ToField IntervalDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable
Uses render. Always includes an interval prefix, like interval ....
Lift IntervalDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable

valuezero :: Interval

The empty interval, representing no time at all.

Example1 expression

>>> zeroMkInterval {months = 0, days = 0, microseconds = 0}

valueinfinity :: Interval

The biggest possible interval.

Example1 expression

>>> infinityMkInterval {months = 2147483647, days = 2147483647, microseconds = 9223372036854775807}

valuenegativeInfinity :: Interval

The smallest possible interval.

Example1 expression

>>> negativeInfinityMkInterval {months = -2147483648, days = -2147483648, microseconds = -9223372036854775808}

valuefromMicroseconds :: Int64 -> Interval

Creates an interval from a number of microseconds.

Example1 expression

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

valuefromMilliseconds :: Int64 -> Maybe Interval

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

Example2 expressions

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

valuefromMillisecondsSaturating :: Int64 -> Interval

Like fromMilliseconds but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valuefromMillisecondsLiteral

:: (KnownNat n, n <= 9223372036854775)
=> proxy n
-> Interval

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

Example1 expression

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

valuefromSeconds :: Int64 -> Maybe Interval

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

Example2 expressions

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

valuefromSecondsSaturating :: Int64 -> Interval

Like fromSeconds but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valuefromSecondsLiteral

:: (KnownNat n, n <= 9223372036854)
=> proxy n
-> Interval

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

Example1 expression

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

valuefromMinutes :: Int64 -> Maybe Interval

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

Example2 expressions

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

valuefromMinutesSaturating :: Int64 -> Interval

Like fromMinutes but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valuefromMinutesLiteral :: (KnownNat n, n <= 153722867280) => proxy n -> Interval

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

Example1 expression

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

valuefromHours :: Int64 -> Maybe Interval

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

Example2 expressions

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

valuefromHoursSaturating :: Int64 -> Interval

Like fromHours but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valuefromHoursLiteral :: (KnownNat n, n <= 2562047788) => proxy n -> Interval

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

Example1 expression

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

valuefromDays :: Int32 -> Interval

Creates an interval from a number of days.

Example1 expression

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

valuefromWeeks :: Int32 -> Maybe Interval

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

Example2 expressions

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

valuefromWeeksSaturating :: Int32 -> Interval

Like fromWeeks but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valuefromWeeksLiteral :: (KnownNat n, n <= 306783378) => proxy n -> Interval

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

Example1 expression

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

valuefromMonths :: Int32 -> Interval

Creates an interval from a number of months.

Example1 expression

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

valuefromYears :: Int32 -> Maybe Interval

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

Example2 expressions

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

valuefromYearsSaturating :: Int32 -> Interval

Like fromYears but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valuefromYearsLiteral :: (KnownNat n, n <= 178956970) => proxy n -> Interval

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

Example1 expression

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

valuenegate :: Interval -> Maybe Interval

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

Example2 expressions

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

valuenegateSaturating :: Interval -> Interval

Like negate but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valueadd :: Interval -> Interval -> Maybe Interval

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

Example2 expressions

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

valueaddSaturating :: Interval -> Interval -> Interval

Like add but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valueintoTime :: Interval -> (CalendarDiffDays, NominalDiffTime)

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

Example1 expression

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

valuefromTime :: CalendarDiffDays -> NominalDiffTime -> Maybe Interval

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

Example1 expression

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

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

Example1 expression

>>> fromTime mempty 9223372036854.775808Nothing

Note that this truncates extra precision.

Example1 expression

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

valuefromTimeSaturating :: CalendarDiffDays -> NominalDiffTime -> Interval

Like fromTime but uses saturating arithmetic rather than returning Maybe.

Example2 expressions

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

valueintoMicro :: Integer -> Micro

valuefromMicro :: Micro -> Integer

valuescale :: Rational -> Interval -> Maybe Interval

Scales an interval by the given ratio.

Example2 expressions

>>> 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.

Example3 expressions

>>> scale 0.4 (MkInterval 0 0 1) -- rounds downJust (MkInterval {months = 0, days = 0, microseconds = 0})>>> scale 0.5 (MkInterval 0 0 1) -- rounds half to evenJust (MkInterval {months = 0, days = 0, microseconds = 0})>>> scale 0.6 (MkInterval 0 0 1) -- rounds upJust (MkInterval {months = 0, days = 0, microseconds = 1})

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

Example1 expression

>>> 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.

Example1 expression

>>> 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.

Example1 expression

>>> 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.

Example1 expression

>>> 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.

Example2 expressions

>>> 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}))

valuescaleSaturating :: Rational -> Interval -> Interval

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

Example1 expression

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

valuerender :: Interval -> Builder

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).

Example1 expression

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

valueparse :: Parser Interval

Parses an interval. This is not a general purpose parser. It only supports the formats that PostgreSQL generates.

valueparseInfinities :: Parser Interval

valueparseIso8601 :: Parser [Component]

valueparsePostgresVerbose :: Parser [Component]

valueparsePostgres :: Parser [Component]

valueparseSqlStandard :: Parser [Component]

valueparseTime :: Parser [Component]

valueparseSign :: Parser ByteString

valuemaybePlural :: ByteString -> Parser ByteString

datadata Component

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.

Constructors

Instances2Eq, Show

Eq ComponentDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable
Show ComponentDefined in postgresql-simple-interval-1.0.1.2 · Database.PostgreSQL.Simple.Interval.Unstable

valuefromComponent :: Component -> Maybe Interval

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

valuefromComponents

:: (Alternative f, Traversable t)
=> t Component
-> f Interval

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.

valuenegateComponent :: Component -> Component

valuenegateComponentsWhen :: Functor f => Bool -> f Component -> f Component

valuetoIntegralSaturating :: (Integral a, Integral b, Bounded b) => a -> b