Redesign Range with through and till constructors, remove Reverse

Replace Range and Reverse with a single Range type using two named constructors — till (exclusive) and through (inclusive) — with direction inferred from argument order and empty-range semantics for invalid inputs.
46 files changed +601 −563

Motivation

The old Range accepted a signed increment and used it for both direction and magnitude, which meant descending ranges required negative steps and the sign/direction coupling was error-prone. Reverse existed solely to paper over that by swapping argument order.

The redesign eliminates both problems: direction comes from the argument order, and the step is always a positive magnitude. A zero or negative step, or a non-finite float argument (NaN, infinity), produces an empty range rather than erroring.

File Map

Behavioral Changes

Named constructors replace default constructor

Range(0, 10) no longer compiles. Use Range[USize].till(0, 10) for exclusive or Range[USize].through(0, 10) for inclusive.

Explicit type parameter required

The type parameter no longer defaults to USize. Every call site must name the numeric type: Range[USize], Range[I32], Range[F64], etc.

Reverse removed

Reverse is deleted. Use Range.through(high, low) or Range.till(high, low) instead — direction is inferred when from > to.

Direction inference

When from < to the range ascends. When from > to it descends. Step is always a positive magnitude — no more negative increments.

Migration hazard: empty ranges that now descend

The old Range(a, b) produced an empty range when a > b. The new Range[T].till(a, b) infers a descending range instead. Code that passed dynamic bounds and relied on the empty-when-no-progress behavior needs an explicit if from < to guard.

Empty ranges on bad inputs

Constructors are non-partial. A zero or negative step, or non-finite float arguments, produce an empty range instead of erroring. rewind() cannot resurrect a range made empty by bad inputs.

Removed methods

is_empty() and is_infinite() are removed. Infinite ranges are no longer supported.

API Changes

▶ Changed Range — new constructors, removed methods
class Range[A: (Real[A] val & Number) = USize]
  is Iterator[A]

  new create(min: A = 0, max: A = 100, inc: A = 1)
  fun has_next(): Bool
  fun ref next(): A ?
  fun ref rewind()
  fun is_empty(): Bool
  fun is_infinite(): Bool
class Range[A: (Real[A] val & Number)]
  is Iterator[A]

  new through(from: A, to: A, step: A = 1)
  new till(from: A, to: A, step: A = 1)
  fun has_next(): Bool
  fun ref next(): A ?
  fun ref rewind()
▶ Removed Reverse — deleted entirely
class Reverse[A: (Real[A] val & Number) = USize]
  is Iterator[A]

  new create(first: A, last: A, dec: A = 1)
  fun has_next(): Bool
  fun ref next(): A ?
  fun ref rewind()
// Deleted. Use Range.through or Range.till
// with from > to for descending ranges.

for e in Range.through(10, 0) do ... end

Public API Surface

Changed class Range[A: (Real[A] val & Number)] is Iterator[A]
A bounded numeric sequence with a given step size. Two named constructors control whether the far bound is included. Direction is inferred: when from < to the range ascends, when from > to it descends. Step is always a positive magnitude. A zero or negative step, or a non-finite float argument (NaN or infinity), produces an empty range.
  • new through(from: A, to: A, step: A = 1)
    Inclusive of the far bound. Range.through(0, 3) yields 0, 1, 2, 3. Range.through(3, 0) yields 3, 2, 1, 0. Range.through(5, 5) yields 5.
  • new till(from: A, to: A, step: A = 1)
    Exclusive of the far bound. Range.till(0, 3) yields 0, 1, 2. Range.till(3, 0) yields 3, 2, 1. Range.till(5, 5) yields nothing.
  • fun has_next(): Bool
    True while there are values remaining in the sequence.
  • fun ref next(): A ?
    Return the current value and advance. Errors when exhausted.
  • fun ref rewind()
    Reset the iterator to its starting position.

Architecture

Range uses five internal fields. Three immutable (let) fields are set at construction and never change: _forward, _inclusive, and _empty. Two mutable (var) fields track iteration state: _idx (current position) and _done (overflow detection). rewind() resets the mutable fields but cannot touch the immutable ones.

Range internal state machine Constructor (through / till) Sets _forward, _inclusive (let) Sets _empty if step≤0 or !finite (let) Sets _idx = from, _done = false (var) has_next() if _empty or _done → false else: 4-way check (_forward × _inclusive) next() ? Advances _idx by ±_step Sets _done = true on arithmetic wrap rewind() Resets _idx = _from, _done = false Cannot clear _empty (immutable) restart

Release Notes

Redesign Range API

Range has been redesigned with two named constructors, and Reverse has been removed. Range[T].till(from, to) excludes the far bound; Range[T].through(from, to) includes it. Direction is inferred from the arguments, and the step is always a positive magnitude. A zero or negative step, or a non-finite float argument, produces an empty range.

The type parameter no longer defaults to USize — every call site must name the numeric type explicitly.

is_empty() and is_infinite() have been removed. Infinite ranges are no longer supported.

The old Range(a, b) produced an empty range when a > b. The new Range[T].till(a, b) infers a descending range instead. Code that passed dynamic bounds and relied on the empty-when-no-progress behavior needs an explicit guard:

// Old: Range(start, limit) was empty when start >= limit
// New: Range[USize].till(start, limit) descends when start > limit
if start < limit then
  for i in Range[USize].till(start, limit) do ... end
end

Before:

// ascending, exclusive of 10
for i in Range(0, 10) do ... end

// ascending with step
for i in Range(0, 10, 2) do ... end

// descending, inclusive of both endpoints
for e in Reverse(10, 0) do ... end

// descending with step
for e in Reverse(10, 0, 3) do ... end

After:

// ascending, exclusive of 10
for i in Range[USize].till(0, 10) do ... end

// ascending with step
for i in Range[USize].till(0, 10, 2) do ... end

// descending, inclusive of both endpoints
for e in Range[USize].through(10, 0) do ... end

// descending with step
for e in Range[USize].through(10, 0, 3) do ... end