int-interval

A small, zero-allocation interval algebra library for primitive integer types.

This crate provides half-open intervals ([start, end)) with a minimal and predictable API, designed to be:

• branch-light
• allocation-free
• const fn friendly
• close to std::ops::Range performance

All integer primitives are supported via code generation.

u8   → U8CO
u16  → U16CO
u32  → U32CO
u64  → U64CO
u128 → U128CO
usize→ UsizeCO

i8   → I8CO
i16  → I16CO
i32  → I32CO
i64  → I64CO
i128 → I128CO
isize→ IsizeCO

The implementation focuses on simple interval algebra, not general interval sets.

---

Interval Model

Intervals are half-open:

[start, end)

Example:

U8CO::try_new(2, 5) = {2,3,4}

Properties:

• start < end
• len = end - start
• empty intervals are not representable

---

API

Construction

let x = U8CO::try_new(2, 8).unwrap();

Unchecked variant:

let x = U8CO::new_unchecked(2, 8);

---

Accessors

x.start()
x.end_excl()
x.len()
x.contains(v)
x.iter()

---

Predicates

x.intersects(y)
x.is_adjacent(y)
x.is_contiguous_with(y)

---

Interval Algebra

Intersection

[A ∩ B]

x.intersection(y) -> Option<U8CO>

---

Convex Hull

smallest interval containing both

x.convex_hull(y) -> U8CO

---

Between

gap between intervals

[a----b]   [c----d]

between = [b,c)

x.between(y) -> Option<U8CO>

---

Union

Union can produce one or two intervals:

[a----b] [c----d]   →  Two
[a----b][b----d]    →  One
[a--c----d--b]      →  One

x.union(y) -> OneTwo<U8CO>

---

Difference

A - B

Possible results:

Zero
One
Two

x.difference(y) -> ZeroOneTwo<U8CO>

---

Symmetric Difference

(A - B) ∪ (B - A)

x.symmetric_difference(y) -> ZeroOneTwo<U8CO>

---

Result Types

pub enum OneTwo<T> {
    One(T),
    Two(T, T),
}

pub enum ZeroOneTwo<T> {
    Zero,
    One(T),
    Two(T, T),
}

These enums avoid allocations and allow the API to remain fully stack-based.

---

Code Generation

All integer variants are generated from the u8 implementation.

src/u8.rs      ← template
src/u8/*       ← template tests

Generation is handled by:

xtask/codegen

Run:

cargo run -p codegen

This produces:

src/u16.rs
src/u32.rs
src/u64.rs
...

Each generated file includes:

@generated by xtask/codegen

Manual edits will be overwritten.

---

no_std

This crate is no_std compatible.

It depends only on core, performs no heap allocation, and does not require an allocator. All interval operations are stack-based and can be used in embedded or otherwise restricted environments.

---

rust-intervals

Some interval operation APIs were inspired by rust-intervals.

---

Benchmarks

Benchmarks compare against:

• std::ops::Range
• rust_intervals

Example results:

Construct

run by cargo bench --bench construct_only

construct_only

co              ~45 µs
rust_intervals  ~96 µs
std_range       ~43 µs

Interval Ops

run by cargo bench --bench interval_ops

intersection

co              ~62 µs
rust_intervals  ~354 µs
std_range       ~65 µs

union

co              ~147 µs
rust_intervals  ~251 µs
std_range       ~150 µs

Scenario Benchmarks

run by cargo bench --bench interval_scenarios

Common spatial relationships tested:

• adjacent
• containment
• overlap
• disjoint (near / far)

Typical result:

overlap_heavy_union

co              ~85 µs
rust_intervals  ~470 µs
std_range       ~65 µs

Observations:

• co performance is typically close to std::Range
• rust_intervals is 3-6× slower

---

Design Goals

This crate intentionally avoids:

• interval trees
• dynamic interval sets
• heap allocations
• trait abstraction layers

Instead it focuses on:

• fast primitive interval algebra
• predictable codegen
• simple semantics

---

When To Use

Suitable for:

• geometry / raster operations
• compiler span analysis
• scheduling ranges
• DNA / sequence slicing
• numeric algorithms

Not suitable for:

• large interval sets
• range indexing structures
• tree-based queries

---

License

MIT