Skip to content

std::ranges

Ranges: 1..5 holds 1 to 4, 1..=5 holds 1 to 5, and Range.from(n) has no end. A range’s own functions are contains, start, stop, is_inclusive, is_bounded, from, naturals and step_by.

A range over a type that implements Discrete, such as Int, is also an Iter, so every Iter function works on it: Iter.to_list(1..=3) is [1, 2, 3] and Iter.count(1..5) is 4. An unbounded range is Iter.is_infinite. Limit it with Iter.take or Iter.take_while before collecting it: Iter.to_list of one never finishes, which is a compile error where the compiler can see the range is unbounded and an error when the program runs otherwise. Iter.known_count(r) is Some(n) for a bounded range and None for an unbounded one.

Import with import std::ranges.

struct Range<T> where T: Comparable

opaque — construction surface is private to its defining module

A range of values of a Comparable type. A range literal makes one: 1..5, "a".."z" and 0.0..=1.0 hold their start, their end and whether the range includes its end. A range from Range.from(n) or Range.naturals() has no end.

A Range<T> is an Iter<T> when T is also Discrete. A range over any other comparable type, such as Float or String, still answers contains.

assert Iter.to_list(1..=3) == [1, 2, 3]
assert Iter.count(1..5) == 4
assert Range.from(10) |> Iter.take(3) |> Iter.to_list() == [10, 11, 12]
assert Iter.known_count(1..5) == Some(4)
assert Iter.known_count(Range.from(1)) == None
fn from<T>(n: T) -> ClosedRange<T> where T: Comparable

type function on Range

Returns the range that starts at n and has no end, a ClosedRange of n’s type. Where a ClosedRange<NonNegativeInt> is expected, Range.from(2) is one, and its literal start is checked when the program is compiled. As an iterator it is Iter.is_infinite: limit it with Iter.take before Iter.to_list or any other function that must reach the end, which never finishes on it. An Int has no largest value, so the range goes on past 64 bits.

assert Range.contains(Range.from(1), 100)
refute Range.is_bounded(Range.from(1))
assert Iter.is_infinite(Range.from(1))
assert Range.from(1) |> Range.step_by(2) |> Iter.is_infinite()
top = 9_223_372_036_854_775_807
assert Range.from(top) |> Iter.take(2) |> Iter.to_list() == [top, top + 1]
assert Range.contains(Range.from(0.5), 2.25)
refute Range.contains(Range.from("m"), "a")
fn naturals() -> ClosedRange<Int>

type function on Range

Returns the range of Ints that starts at 0 and has no end. Limit it with Iter.take before collecting it.

assert Range.contains(Range.naturals(), 0)
refute Range.contains(Range.naturals(), -1)
assert Range.naturals() |> Iter.take(3) |> Iter.to_list() == [0, 1, 2]
fn step_by<T, S>(r: Range<T>, by: S) -> Iter<T> where T: Comparable and Steppable<S>

type function on Range

Returns a lazy Iter that walks the range in steps of by.

A range iterates by itself only when its type is Discrete. step_by walks any range whose type is Steppable by the step’s type: a Range<Int> steps by an Int, a Range<Decimal> by a Decimal, exactly, and a calendar type steps by Days when it implements Steppable<Days>.

The walk goes the way by moves the start. A step that moves it down counts down from the start to the end, so Range.step_by(5..=1, -1) is 5, 4, 3, 2, 1, and 5..1 leaves out 1 as any exclusive range leaves out its end. A range whose end lies the other way from the step yields nothing (Range.step_by(1..=5, -1)), and so does a step that does not move. A plain 5..=1 is empty: only a step counts down.

assert 1.0d..=1.3d
    |> Range.step_by(0.1d)
    |> Iter.to_list()
    |> List.equal([1.0d, 1.1d, 1.2d, 1.3d])

assert 5..=1 |> Range.step_by(-1) |> Iter.to_list() == [5, 4, 3, 2, 1]
assert 10..0 |> Range.step_by(-3) |> Iter.to_list() == [10, 7, 4, 1]
assert 1..=5 |> Range.step_by(-1) |> Iter.to_list() == []
assert 1..=5 |> Range.step_by(0) |> Iter.to_list() == []
assert 5..=1 |> Iter.to_list() == []
fn is_bounded<T>(r: Range<T>) -> Bool

type function on Range

True if the range has an end. Check it before passing a range that may be unbounded to Iter.to_list.

assert Range.is_bounded(1..5)
refute Range.is_bounded(Range.from(1))
fn start<T>(r: Range<T>) -> T

type function on Range

The value the range starts at, which it always contains unless it is empty.

assert Range.start(2..5) == 2
assert Range.start(Range.from(7)) == 7
fn stop<T>(r: Range<T>) -> Maybe<T>

type function on Range

The range’s end, None for an unbounded range. Whether the range holds it is Range.is_inclusive.

assert Range.stop(2..5) == Some(5)
assert Range.stop(2..=5) == Some(5)
assert Range.stop(Range.from(7)) == None
fn is_inclusive<T>(r: Range<T>) -> Bool

type function on Range

Whether the range holds its end: True for a..=b, False for a..b and for an unbounded range, which has no end to hold.

assert Range.is_inclusive(2..=5)
refute Range.is_inclusive(2..5)
refute Range.is_inclusive(Range.from(7))

impl Contains for Range<T>

fn contains(c: Range<T>, x: T) -> Bool

impl Contains.contains

Whether x is in the range: two comparisons. An exclusive range leaves out its end, and an unbounded range checks only the start.

assert Range.contains(1..5, 1)
assert Range.contains(1..5, 3)
refute Range.contains(1..5, 5)
refute Range.contains(1..5, 0)
assert Range.contains(1..=5, 5)
refute Range.contains(1..=5, 6)
assert Range.contains(1.25d..=2.50d, 1.50d)

impl Display for Range<T>

fn to_string(r: Range<T>) -> String

impl Display.to_string

The range as its literal, each endpoint in its Debug form: start..end, start..=end, or start.. for an unbounded range. Debug renders a range the same way.

assert Display.to_string(1..5) == "1..5"
assert Display.to_string("a"..="z") == "\"a\"..=\"z\""
assert Display.to_string(Range.from(3)) == "3.."
assert Debug.inspect(1..=5) == Display.to_string(1..=5)

impl Debug for Range<T>

fn inspect(r: Range<T>) -> String

impl Debug.inspect

impl Iter for Range<T>

fn known_count(r: Range<T>) -> Maybe<Int>

impl Iter.known_count

impl Iter for Range<T>

fn each_while(r: Range<T>, yield: (T) -> Bool) -> Bool

impl Iter.each_while

subtype NonEmptyRange<T> Range<T> where T: Comparable when fn r -> Range.contains(r, Range.start(r))

A range that holds at least one value: a..b with a < b, a..=b with a <= b, or an unbounded Range.from(n). It is the parent of ClosedRange and BoundedRange, so an error for a backwards literal names this rule. A Float range with a NaN end holds nothing, since no value is <= NaN, so it is no NonEmptyRange. It is in the prelude.

subtype: NonEmptyRange is a subtype of Range<T>. A literal where a NonEmptyRange is expected is checked when the program is compiled; NonEmptyRange.try_from(...) checks a value when it runs.

import std::float.Float

r: NonEmptyRange<Int> = 3..4
assert Range.contains(r, Range.start(r))
assert NonEmptyRange.try_from(4..4) == None
assert NonEmptyRange.try_from(4..=4) == Some(4..=4)
assert NonEmptyRange.try_from(0.0..=Float.nan()) == None
fn try_from<T>(value: Range<T>) -> Maybe<NonEmptyRange<T>> where T: Comparable

type function on NonEmptyRange

Some of the value when it satisfies NonEmptyRange’s rules, None when it does not.

subtype ClosedRange<T> NonEmptyRange<T> where T: Comparable when fn r -> Range.is_inclusive(r) or not Range.is_bounded(r)

A non-empty range that holds its end, a..=b with a <= b, or an unbounded Range.from(n), which has no end. It is what clamp takes: a value past an exclusive end has no last value in the range to go to. It is in the prelude.

subtype: ClosedRange is a subtype of NonEmptyRange<T> is a subtype of Range<T>. A literal where a ClosedRange is expected is checked when the program is compiled; ClosedRange.try_from(...) checks a value when it runs.

assert Int.clamp(15, 0..=10) == 10
assert ClosedRange.try_from(0..10) == None
assert ClosedRange.try_from(Range.from(0)) == Some(Range.from(0))
fn try_from<T>(value: Range<T>) -> Maybe<ClosedRange<T>> where T: Comparable

type function on ClosedRange

Some of the value when it satisfies ClosedRange’s rules, None when it does not.

subtype BoundedRange<T> NonEmptyRange<T> where T: Comparable when fn r -> Range.is_bounded(r)

A non-empty range with an end, a..b with a < b or a..=b with a <= b. It is what random draws from. It is in the prelude.

subtype: BoundedRange is a subtype of NonEmptyRange<T> is a subtype of Range<T>. A literal where a BoundedRange is expected is checked when the program is compiled; BoundedRange.try_from(...) checks a value when it runs.

assert BoundedRange.try_from(1..=6) == Some(1..=6)
assert BoundedRange.try_from(Range.from(1)) == None
fn try_from<T>(value: Range<T>) -> Maybe<BoundedRange<T>> where T: Comparable

type function on BoundedRange

Some of the value when it satisfies BoundedRange’s rules, None when it does not.