Module

Temporal.Interval

Package: purescript-temporal
Repository: philippedev101/purescript-temporal

Half-open intervals [start, end) with Allen's interval algebra.

All intervals use half-open semantics: the start is included, the end is excluded. This is the standard convention for temporal intervals and composes cleanly — adjacent intervals share a boundary with no gap or overlap.

For date ranges, use [Jan 1, Feb 1) to mean "all of January" rather than the closed [Jan 1, Jan 31].

#Interval Source

newtype Interval a

A half-open interval [start, end). The start is included, the end is excluded. An interval where start >= end is considered empty/invalid and cannot be constructed via interval.

Constructors

Interval { end :: a, start :: a }

Instances

(EncodeJson a) => EncodeJson (Interval a)
(DecodeJson a) => DecodeJson (Interval a)
(Eq a) => Eq (Interval a)
(Show a) => Show (Interval a)

#interval Source

interval :: forall a. Ord a => a -> a -> Maybe (Interval a)

Construct an interval. Returns Nothing if start >= end (which would be empty in half-open semantics).

#unsafeInterval Source

unsafeInterval :: forall a. a -> a -> Interval a

Construct an interval without validation. The caller must ensure start < end.

#start Source

start :: forall a. Interval a -> a

The inclusive start of the interval.

#end Source

end :: forall a. Interval a -> a

The exclusive end of the interval.

#Relation Source

data Relation

Allen's 13 interval relations. Any two non-empty intervals are in exactly one of these relations.

Given intervals X and Y:

Before       : X entirely before Y (gap between)
Meets        : X.end == Y.start (adjacent, X first)
Overlaps     : X starts first, X.end inside Y
Starts       : same start, X ends before Y
During       : X fully inside Y
Finishes     : X starts after Y.start, same end
Equals       : identical start and end
FinishedBy   : inverse of Finishes
Contains     : inverse of During
StartedBy    : inverse of Starts
OverlappedBy : inverse of Overlaps
MetBy        : inverse of Meets
After        : inverse of Before

Constructors

Instances

#relate Source

relate :: forall a. Ord a => Interval a -> Interval a -> Relation

Determine the Allen relation between two intervals.

relate [1, 3) [5, 7) == Before
relate [1, 5) [3, 7) == Overlaps
relate [1, 7) [3, 5) == Contains

#contains Source

contains :: forall a. Ord a => a -> Interval a -> Boolean

Whether a point falls within the interval (half-open: start <= x < end).

#overlaps Source

overlaps :: forall a. Ord a => Interval a -> Interval a -> Boolean

Whether two intervals share any time (colloquial "overlaps"). Adjacent intervals (Meets/MetBy) do NOT overlap in half-open semantics.

#encloses Source

encloses :: forall a. Ord a => Interval a -> Interval a -> Boolean

Whether the first interval fully contains the second.

#abuts Source

abuts :: forall a. Ord a => Interval a -> Interval a -> Boolean

Whether two intervals are adjacent with no gap (one's end is the other's start). Adjacent half-open intervals compose cleanly: [a, b) abuts [b, c).

#isBefore Source

isBefore :: forall a. Ord a => Interval a -> Interval a -> Boolean

Whether the first interval is entirely before the second (with or without gap).

#isAfter Source

isAfter :: forall a. Ord a => Interval a -> Interval a -> Boolean

Whether the first interval is entirely after the second (with or without gap).

#intersection Source

intersection :: forall a. Ord a => Interval a -> Interval a -> Maybe (Interval a)

The overlapping portion of two intervals, if any.

#union Source

union :: forall a. Ord a => Interval a -> Interval a -> Maybe (Interval a)

Merge two intervals into one. Returns Nothing if the intervals neither overlap nor are adjacent (i.e., there is a gap between them).

#hull Source

hull :: forall a. Ord a => Interval a -> Interval a -> Interval a

The smallest interval that encloses both inputs, ignoring any gap. Always succeeds.

hull [1, 3) [5, 7) == [1, 7)  -- includes the gap

#gap Source

gap :: forall a. Ord a => Interval a -> Interval a -> Maybe (Interval a)

The gap between two non-overlapping intervals, if any. Returns Nothing if the intervals overlap or are adjacent.

#difference Source

difference :: forall a. Ord a => Interval a -> Interval a -> Array (Interval a)

The parts of the first interval not in the second. Returns 0, 1, or 2 intervals.

difference [1, 10) [3, 7) == [ [1, 3), [7, 10) ]  -- hole punched
difference [1, 5) [3, 7)  == [ [1, 3) ]            -- trimmed
difference [5, 7) [1, 10) == []                     -- fully consumed