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.
Exports
Section titled “Exports”struct Range
Section titled “struct Range”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
Range.from
Section titled “Range.from”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")
Range.naturals
Section titled “Range.naturals”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]
Range.step_by
Section titled “Range.step_by”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() == []
Range.is_bounded
Section titled “Range.is_bounded”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))
Range.start
Section titled “Range.start”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
Range.stop
Section titled “Range.stop”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
Range.is_inclusive
Section titled “Range.is_inclusive”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))
Range.contains
Section titled “Range.contains”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)
Range.to_string
Section titled “Range.to_string”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)
Range.inspect
Section titled “Range.inspect”impl Debug for Range<T>
fn inspect(r: Range<T>) -> String
impl Debug.inspect
Range.known_count
Section titled “Range.known_count”impl Iter for Range<T>
fn known_count(r: Range<T>) -> Maybe<Int>
impl Iter.known_count
Range.each_while
Section titled “Range.each_while”impl Iter for Range<T>
fn each_while(r: Range<T>, yield: (T) -> Bool) -> Bool
impl Iter.each_while
type NonEmptyRange
Section titled “type NonEmptyRange”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
NonEmptyRange.try_from
Section titled “NonEmptyRange.try_from”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.
type ClosedRange
Section titled “type ClosedRange”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))
ClosedRange.try_from
Section titled “ClosedRange.try_from”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.
type BoundedRange
Section titled “type BoundedRange”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
BoundedRange.try_from
Section titled “BoundedRange.try_from”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.