# 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
```rust
let x = U8CO::try_new(2, 8).unwrap();
```
Unchecked variant:
```rust
let x = U8CO::new_unchecked(2, 8);
```
---
### Accessors
```rust
x.start()
x.end_excl()
x.len()
x.contains(v)
x.iter()
```
---
### Predicates
```rust
x.intersects(y)
x.is_adjacent(y)
x.is_contiguous_with(y)
```
---
### Interval Algebra
#### Intersection
```
[A ∩ B]
```
```rust
x.intersection(y) -> Option<U8CO>
```
---
#### Convex Hull
```
smallest interval containing both
```
```rust
x.convex_hull(y) -> U8CO
```
---
#### Between
```
gap between intervals
```
```
[a----b] [c----d]
between = [b,c)
```
```rust
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
```
```rust
x.union(y) -> OneTwo<U8CO>
```
---
#### Difference
```
A - B
```
Possible results:
```
Zero
One
Two
```
```rust
x.difference(y) -> ZeroOneTwo<U8CO>
```
---
#### Symmetric Difference
```
(A - B) ∪ (B - A)
```
```rust
x.symmetric_difference(y) -> ZeroOneTwo<U8CO>
```
---
## Result Types
```rust
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