PosixSpan

PosixSpan :: # (opaque)

A finite, nonempty half-open span on the POSIX microsecond axis.

Example

Construct a half-open interval: the start belongs to it and the end does not. Equal endpoints return EmptySpan; reversed endpoints return ReversedBounds.

import time.PosixBoundary
import time.PosixSpan

expect {
    start = PosixBoundary.from_microseconds(0)
    end = PosixBoundary.from_microseconds(1000000)
    span = PosixSpan.new(start, end)?
    PosixSpan.contains(span, start) and !PosixSpan.contains(span, end)
}

Examples assume a package dependency named time.

new : PosixBoundary, PosixBoundary -> Try(PosixSpan, [EmptySpan, ReversedBounds, ..])

Construct a nonempty half-open span [start, end). Equal endpoints return EmptySpan; a start after the end returns ReversedBounds.

from_seconds : Dec, Dec, Rounding -> Try(PosixSpan, [EmptySpan, ReversedBounds, Submicrosecond, OutOfRange, ..])

Interpret decimal seconds since the POSIX epoch with one rounding policy for both endpoints. Equal/reversed source bounds are rejected before conversion; rounding that collapses a nonempty span returns EmptySpan.

start : PosixSpan -> PosixBoundary

Read the inclusive lower boundary of this span.

end : PosixSpan -> PosixBoundary

Read the exclusive upper boundary; that position is not contained in the span.

coordinate_width : PosixSpan -> Try(PosixDelta, [OutOfRange, ..])

Return end minus start as a POSIX displacement. A valid span can still return OutOfRange when its width exceeds I64 microseconds.

microsecond_at : PosixBoundary -> Try(PosixSpan, [OutOfRange, ..])

Construct [point, point + one microsecond). The greatest representable position returns OutOfRange because its exclusive end cannot be represented.

to_hash : PosixSpan, Hasher -> Hasher

Hash both boundaries consistently with span equality for dictionary/set keys.

to_inspect : PosixSpan -> Str

Describe the half-open boundaries in POSIX microseconds for diagnostics. Use ExactInterval for supported interval text interchange.

is_eq : PosixSpan, PosixSpan -> Bool

Compare both boundaries for equal extent. Span identity and source spelling are not part of this equality.

hull : PosixSpan, PosixSpan -> PosixSpan

The smallest span containing both inputs, including any gap between them.

intersection : PosixSpan, PosixSpan -> [Empty, Span(PosixSpan)]

Return the common nonempty span, or Empty when inputs are disjoint or only touch at an endpoint.

overlaps : PosixSpan, PosixSpan -> Bool

Whether the spans share any occupied position. Touching endpoints alone do not overlap because the upper boundary is exclusive.

contains : PosixSpan, PosixBoundary -> Bool

Whether a position is at or after start and strictly before end.

relation : PosixSpan, PosixSpan -> [Before, Meets, Overlaps, Starts, During, Finishes, Equal, FinishedBy, Contains, StartedBy, OverlappedBy, MetBy, After]

Classify the first span relative to the second using the thirteen Allen interval relations. Meets and MetBy describe touching without overlap.