tur/range

(defdata Bound :copy (Inclusive int) (Exclusive int) (Unbounded))

a range endpoint: inclusive, exclusive, or unbounded.

The internal endpoint representation (range-gadt-typeclass-migration-plan B1). Declared :copy so a shared endpoint can be read by many predicates without affine move tracking complaining; see docs/archive/history/defgadt-copy-and-shared-bounds.md.

It was (defgadt Bound [A] ...) with every constructor returning (Bound int): the parameter was pinned to int and never used, so it is gone (adt-gadt-unification-plan slice 3). A parametric type's bare name is the uniform carrier, so the phantom parameter alone kept every endpoint a malloc'd cell.

Since: LZ4 (sum form: range-gadt-typeclass-migration-plan B1)

(range-bound-new [inclusive :int value :int] :Bound)

build a Bound with given inclusivity and value.

Since: LZ4

(bound-unbounded? [b :Bound] :bool)

true if the endpoint is the Unbounded constructor.

Since: range-gadt-typeclass-migration-plan B1

(range-bound-inclusive? [b :Bound] :bool)

true if the bound is inclusive.

Since: LZ4

(range-bound-value [b :Bound] :int)

return the endpoint value of a bound.

Since: LZ4

(range-bound-flip [b :Bound] :Bound)

return a new bound with the same value but flipped inclusivity.

Since: LZ4

(definstance Eq [Bound])

structural equality on range endpoints.

Two bounds are equal when they share the same constructor and (for Inclusive / Exclusive) the same value. The Eq typeclass is auto-loaded, so this instance adds no new dependency to range.tur's wide auto-load path (range-gadt-typeclass-migration-plan B2).

(.eq? (Inclusive 3) (Inclusive 3))  ; => true
(.eq? (Inclusive 3) (Exclusive 3))  ; => false

Since: range-gadt-typeclass-migration-plan B2

(bound-show-fmt [kind :int v :int] :cstr)

(definstance Show [Bound])

render a lone endpoint: "[v" (Inclusive), "(v" (Exclusive), or "unbounded". This is the lower-side bracket form for a single endpoint; use range->str for a full interval like "[1, 5)".

Show lives in stdlib/typeclass.tur, loaded at the top of this file, so this instance can sit in Bound's own module as the orphan rule requires.

(show (Inclusive 3))  ; => "[3"
(show (Unbounded))    ; => "unbounded"

Since: range-gadt-typeclass-migration-plan B2

(bound-lt? [x :Bound y :Bound] :bool)

strict total order on Bound endpoints, backing Ord [Bound].

Orders endpoints by position on the number line: Unbounded is the least element (an open end extends past every bound), endpoints sort by value ascending, and at an equal value an Inclusive endpoint precedes an Exclusive one (the inclusive end covers its boundary point, so it lies "to the left"). This is a standalone total order; the directional set-operation selectors (range-lower-min / range-upper-max / ...) keep their own context-specific tie-breaking because "unbounded" means -inf on a lower side and +inf on an upper side -- a distinction a lone Bound cannot carry.

(bound-lt? (Unbounded) (Inclusive 0))    ; => true
(bound-lt? (Inclusive 5) (Exclusive 5))  ; => true

Since: range-gadt-typeclass-migration-plan B2

(definstance Ord [Bound])

total ordering on endpoints (see bound-lt? for semantics).

(defstruct Range :copy [lower :Bound upper :Bound])

a continuous interval: a lower and an upper Bound.

A :copy value, so one range can be tested and combined any number of times. Build one with the constructors below (closed-range, ...) or range-new, and read its ends with range-lower / range-upper.

Since: LZ4 (a typed record: adt-gadt-unification-plan slice 3)

(range-new [lower :Bound upper :Bound] :Range)

build a Range from lower and upper Bound endpoints.

(range-contains? (range-new (Inclusive 1) (Exclusive 5)) 4)  ; => true

Since: LZ4

(range-lower [r :Range] :Bound)

return the lower Bound endpoint.

Since: LZ4

(range-upper [r :Range] :Bound)

return the upper Bound endpoint.

Since: LZ4

(range-abort-not-connected :int)

(range-abort-connected :int)

(range-abort-unbounded-lower :int)

(closed-range [lo :int hi :int] :Range)

[lo, hi] both endpoints inclusive.

(closed-range 1 5)  ; => [1, 5]

Since: LZ4

(open-range [lo :int hi :int] :Range)

(lo, hi) both endpoints exclusive.

(open-range 1 5)  ; => (1, 5)

Since: LZ4

(closed-open-range [lo :int hi :int] :Range)

[lo, hi) inclusive lower, exclusive upper.

(closed-open-range 1 5)  ; => [1, 5)

Since: LZ4

(open-closed-range [lo :int hi :int] :Range)

(lo, hi] exclusive lower, inclusive upper.

(open-closed-range 1 5)  ; => (1, 5]

Since: LZ4

(at-least-range [lo :int] :Range)

[lo, +inf) inclusive lower, unbounded above.

(at-least-range 5)  ; => [5, +inf)

Since: LZ4

(greater-than-range [lo :int] :Range)

(lo, +inf) exclusive lower, unbounded above.

(greater-than-range 5)  ; => (5, +inf)

Since: LZ4

(at-most-range [hi :int] :Range)

(-inf, hi] unbounded below, inclusive upper.

(at-most-range 5)  ; => (-inf, 5]

Since: LZ4

(less-than-range [hi :int] :Range)

(-inf, hi) unbounded below, exclusive upper.

(less-than-range 5)  ; => (-inf, 5)

Since: LZ4

(singleton-range [v :int] :Range)

[v, v] a range containing exactly one value.

(singleton-range 3)  ; => [3, 3]

Since: LZ4

(unbounded-range :Range)

(-inf, +inf) no bounds at all.

(unbounded-range)  ; => (-inf, +inf)

Since: LZ4

(range-val-in-lower? [b :Bound v :int] :bool)

(range-val-in-upper? [b :Bound v :int] :bool)

(range-bound-strictly-before? [u :Bound l :Bound] :bool)

(range-bound-has-gap? [u :Bound l :Bound] :bool)

(range-contains? [r :Range v :int] :bool)

true if value v falls within range r.

(range-contains? (closed-range 1 5) 3)  ; => true
(range-contains? (open-range 1 5) 1)    ; => false

Since: LZ4

(range-encloses? [r :Range other :Range] :bool)

true if every value in other is also in r.

(range-encloses? (closed-range 0 10) (closed-range 2 8))  ; => true

Since: LZ4

(range-connected? [r1 :Range r2 :Range] :bool)

true if no gap exists between r1 and r2.

Two ranges are connected if their union forms a contiguous interval (they overlap, or touch at a point where at least one side is inclusive).

(range-connected? (closed-open-range 1 3) (closed-range 3 5))  ; => true
(range-connected? (less-than-range 3) (greater-than-range 3))  ; => false

Since: LZ4

(range-overlaps? [r1 :Range r2 :Range] :bool)

true if r1 and r2 share at least one common value.

Stronger than range-connected?: touching ranges like [1,3) and [3,5] are connected but do not overlap (no value is in both).

(range-overlaps? (closed-range 1 3) (closed-range 3 5))  ; => true
(range-overlaps? (closed-open-range 1 3) (closed-range 3 5))  ; => false

Since: LZ4

(bounded-range? [r :Range] :bool)

true if both endpoints are present.

Since: LZ4

(bounded-above? [r :Range] :bool)

true if r has an upper bound.

Since: LZ4

(bounded-below? [r :Range] :bool)

true if r has a lower bound.

Since: LZ4

(unbounded-above? [r :Range] :bool)

true if r has no upper bound.

Since: LZ4

(unbounded-below? [r :Range] :bool)

true if r has no lower bound.

Since: LZ4

(singleton-range? [r :Range] :bool)

true if r contains exactly one value.

A range is a singleton when both bounds are present, equal, and inclusive.

Since: LZ4

(empty-range? [r :Range] :bool)

true if r contains no values.

A bounded range is empty when the lower bound is strictly past the upper bound, or when both bounds share a value but at least one is exclusive.

Since: LZ4

(nonempty-range? [r :Range] :bool)

true if r contains at least one value.

Since: LZ4

(range-lower-min [b1 :Bound b2 :Bound] :Bound)

(range-upper-max [b1 :Bound b2 :Bound] :Bound)

(range-lower-max [b1 :Bound b2 :Bound] :Bound)

(range-upper-min [b1 :Bound b2 :Bound] :Bound)

(range-span [r1 :Range r2 :Range] :Range)

smallest range enclosing both r1 and r2 (convex hull).

(range-span (closed-range 1 3) (closed-range 5 8))  ; => [1, 8]

Since: LZ4

(range-intersection [r1 :Range r2 :Range] :Range)

largest range enclosed by both r1 and r2.

The ranges must be connected (overlapping or touching); if they are not connected, aborts with an error.

(range-intersection (closed-range 1 5) (closed-range 3 8))  ; => [3, 5]

Since: LZ4

(range-gap [r1 :Range r2 :Range] :Range)

largest range lying strictly between r1 and r2.

The ranges must NOT be connected (a gap must exist); if they are connected, aborts with an error.

(range-gap (closed-range 1 3) (closed-range 5 8))    ; => (3, 5)
(range-gap (closed-open-range 1 3) (open-range 3 8)) ; => [3, 3]

Since: LZ4

(seq/from-range [r :Range] :int)

convert a bounded integer Range to a lazy Seq.

The lower bound must be present (range must not be unbounded below). An unbounded upper bound produces an infinite sequence.

(seq-for-each println (seq/from-range (closed-range 1 4)))  ; => 1 2 3 4
(seq-for-each println (seq/from-range (open-range 1 5)))    ; => 2 3 4

Since: LZ4

(seq/from-range-step [step :int r :Range] :int)

convert a bounded integer Range to a Seq with a custom step.

The lower bound must be present. Positive step iterates upward; negative step iterates downward (in which case supply a range with lo > hi or use at-most / at-least accordingly). Step must not be zero.

(seq-for-each println (seq/from-range-step 2 (closed-range 0 8)))
; => 0 2 4 6 8

Since: LZ4