8.9 Ranges

0.45+9.1.0.1

Rhombus

8.9 Ranges🔗ℹ

A rangeSee Ranges in the Rhombus Guide for an introduction to ranges. represents a contiguous set of integers between two points. When the starting point is not #neginf, the range can be used as a sequence; in addition, when the ending point is not #inf, the range is listable. Generally, the starting point must be less than or equal to the ending point, so that the lower bound is “less than or equal to” the upper bound by comparison on bounds.

A range supports membership tests using the in operator, which is the same as Range.contains.

annotation

Range

annotation

SequenceRange

annotation

ListRange

The Range annotation matches any range.

The SequenceRange annotation matches a range that can be used as a sequence. Such a range has a non-#neginf starting point.

The ListRange annotation matches a range that is listable. Such a range has a non-#neginf starting point and a non-#inf ending point.

Static information associated by SequenceRange or ListRange makes an expression acceptable as a sequence to for in static mode.

expression

start_expr .. end_expr

repetition

start_repet .. end_repet

binding operator

start_bind .. end_bind

expression

repetition

binding operator

expression

repetition

binding operator

expression

repetition

binding operator

~order: enumeration

The same as Range.from_to, Range.from, Range.to, and Range.full, respectively.

When start_expr .. end_expr or start_expr .. is used in an each clause of for, the optimization is more aggressive in that no intermediate range is created.

expression

start_expr ..= end_expr

repetition

start_repet ..= end_repet

binding operator

start_bind ..= end_bind

expression

..= end_expr

repetition

..= end_repet

binding operator

..= end_bind

~order: enumeration

The same as Range.from_to_inclusive and Range.to_inclusive, respectively.

When start_expr ..= end_expr is used in an each clause of for, the optimization is more aggressive in that no intermediate range is created.

expression

start_expr <.. end_expr

repetition

start_repet <.. end_repet

binding operator

start_bind <.. end_bind

expression

start_expr <..

repetition

start_repet <..

binding operator

start_bind <..

~order: enumeration

The same as Range.from_exclusive_to and Range.from_exclusive, respectively.

When start_expr <.. end_expr or start_expr <.. is used in an each clause of for, the optimization is more aggressive in that no intermediate range is created.

expression

start_expr <..= end_expr

repetition

start_repet <..= end_repet

binding operator

start_bind <..= end_bind

~order: enumeration

The same as Range.from_exclusive_to_inclusive.

When start_expr <..= end_expr is used in an each clause of for, the optimization is more aggressive in that no intermediate range is created.

function

fun Range.from_to(start :: Int, end :: Int) :: ListRange

binding operator

Range.from_to(start_bind, end_bind)

Constructs a range that includes start, but does not include end. The corresponding binding matches the constructed range.

function

fun Range.from_to_inclusive(start :: Int, end :: Int) :: ListRange

binding operator

Range.from_to_inclusive(start_bind, end_bind)

Constructs a range that includes both start and end. The corresponding binding matches the constructed range.

function

fun Range.from(start :: Int) :: SequenceRange

binding operator

Range.from(start_bind)

Constructs a range that includes start, and with #inf as the ending point. The corresponding binding matches the constructed range.

function

fun Range.from_exclusive_to(start :: Int, end :: Int) :: ListRange

binding operator

Range.from_exclusive_to(start_bind, end_bind)

Constructs a range that does not include either start or end. Unlike the other constructors, start must be less than (but not equal to) end, otherwise the lower bound would be “greater than” the upper bound. The corresponding binding matches the constructed range.

function

fun Range.from_exclusive_to_inclusive(start :: Int, end :: Int)

:: ListRange

binding operator

Range.from_exclusive_to_inclusive(start_bind, end_bind)

Constructs a range that does not include start, but includes end. The corresponding binding matches the constructed range.

function

fun Range.from_exclusive(start :: Int) :: SequenceRange

binding operator

Range.from_exclusive(start_bind)

Constructs a range that does not include start, and with #inf as the ending point. The corresponding binding matches the constructed range.

function

fun Range.to(end :: Int) :: Range

binding operator

Range.to(end_bind)

Constructs a range with #neginf as the starting point, and does not include end. The corresponding binding matches the constructed range.

function

fun Range.to_inclusive(end :: Int) :: Range

binding operator

Range.to_inclusive(end_bind)

Constructs a range with #neginf as the starting point, and includes end. The corresponding binding matches the constructed range.

function

fun Range.full() :: Range

binding operator

Range.full()

Constructs a range with #neginf as the starting point and #inf as the ending point. The corresponding binding matches the constructed range.

method

method (rge :: Range).start() :: Int || matching(#neginf)

method

method (rge :: Range).end() :: Int || matching(#inf)

Returns the starting point and ending point of rge, respectively. The starting point can be #neginf, and the ending point can be #inf, indicating the lack of a starting point or ending point.

method

method (rge :: Range).includes_start() :: Boolean

method

method (rge :: Range).includes_end() :: Boolean

Returns #true if rge includes the starting point and the ending point, respectively, #false otherwise. A #neginf starting point or #inf ending point cannot be included.

method

method (rge :: Range).is_empty() :: Boolean

Returns #true if rge is an empty range, #false otherwise. An empty range is empty “by definition,” meaning that its lower bound is “equal to” its upper bound, and therefore it cannot have anything at all in the range that it represents. By contrast, a range may have no integers even if its lower bound is strictly “less than” its upper bound (but it may well have real numbers, in principle); in such case, use rge.canonicalize().is_empty() to check for its “emptiness.”

> (3..4).is_empty()
#false
> (3..=3).is_empty()
#false
> (3..3).is_empty()
#true
> (3 <..= 3).is_empty()
#true
> (3 <.. 4).is_empty()
#false
> (3 <.. 4).canonicalize().is_empty()
#true

method

method (rge :: Range).canonicalize() :: Range

Returns the canonical form of rge with respect to the discrete domain of integers. The canonical form has and only has all integers that rge has, and is guaranteed to be in one of the following forms:

start .. end, if rge.start() and rge.end() are both integers;
start .., if rge.start() is an integer and rge.end() is #inf;
.. end, if rge.start() is #neginf and rge.end() is an integer; or
.., if rge.start() is #neginf and rge.end() is #inf.

Furthermore, if rge is already in canonical form, it is returned as-is.

> (1..5).canonicalize()
1 .. 5
> (1..).canonicalize()
1 ..
> (..5).canonicalize()
.. 5
> (..).canonicalize()
..
> (1..=5).canonicalize()
1 .. 6
> (..=5).canonicalize()
.. 6
> (1 <.. 5).canonicalize()
2 .. 5
> (1 <..).canonicalize()
2 ..
> (1 <..= 5).canonicalize()
2 .. 6

method

method (rge :: Range).contains(int :: Int) :: Boolean

Checks whether rge has int in the range that it represents. See also in.

> (3..=7).contains(5)
#true
> (3..=7).contains(7)
#true
> (3..=7).contains(10)
#false
> 5 in 3..=7
#true

method

method (rge :: Range).encloses(another_rge :: Range, ...) :: Boolean

function

fun Range.encloses(rge :: Range, ...) :: Boolean

Checks whether the given ranges are in enclosing order. A range rge encloses another range rge2 when rge has every integer in rge2. Every range encloses itself, and empty ranges never enclose non-empty ranges.

> Range.encloses()
#true
> (2 <.. 8).encloses()
#true
> (2 <.. 8).encloses(4..=6)
#true
> (2 <.. 8).encloses(2..=6, 4..=6)
#false
> (2 <.. 8).encloses(5..)
#false
> (2 <..).encloses(5..)
#true

method

method (rge :: Range).is_connected(rge2 :: Range) :: Boolean

Checks whether rge is connected with rge2, that is, whether there exists a range (possibly empty) that is enclosed by both rge and rge2.

> (2..=7).is_connected(3 <.. 8)
#true
> (2..=5).is_connected(5 <.. 8)
#true
> (2 <.. 5).is_connected(5 <.. 8)
#false

method

method (rge :: Range).overlaps(rge2 :: Range) :: Boolean

Checks whether rge overlaps with rge2, that is, whether there exists a non-empty range that is enclosed by both rge and rge2.

> (2..=7).overlaps(3 <.. 8)
#true
> (2..=5).overlaps(5..=8)
#true
> (2..=5).overlaps(5 <.. 8)
#false

method

method (rge :: Range).span(another_rge :: Range, ...) :: Range

Returns the smallest range that encloses rge and all another_rges.

> (2..=5).span()
2 ..= 5
> (2..=5).span(8 <.. 9)
2 .. 9
> (..4).span(6..=6)
..= 6
> (2 <.. 8).span(..=5, 8 <.. 9)
.. 9

method

method (rge :: Range).gap(rge2 :: Range) :: maybe(Range)

Returns the largest range that lies between rge and rge2, or #false if no such range exists (precisely when rge overlaps with rge2).

> (2..=5).gap(8..=9)
5 <.. 8
> (..4).gap(6..=6)
4 .. 6
> (2 <.. 8).gap(8..=10)
8 .. 8
> (2..=8).gap(8..=10)
#false

method

method (rge :: Range).intersect(another_rge :: Range, ...)

:: maybe(Range)

function

fun Range.intersect(rge :: Range, ...)

:: maybe(Range)

Returns the intersection of the given ranges, or #false if no such range exists. The intersection of a range rge and another range rge2 is the largest range that is enclosed by both rge and rge2, which only exists when rge is connected with rge2.

> Range.intersect()
..
> (2..=8).intersect()
2 ..= 8
> (2..=8).intersect(4 <.. 16)
4 <..= 8
> (4 <..).intersect(..6, 2..=8)
4 <.. 6
> (2 <.. 8).intersect(..=5)
2 <..= 5
> (2 <.. 8).intersect(8 <.. 10)
#false

method

method (rge :: ListRange).to_list() :: List.of(Int)

Implements Listable by returning a list of integers in rge in ascending order.

> (0..5).to_list()
[0, 1, 2, 3, 4]
> [& 0..5]
[0, 1, 2, 3, 4]
> (0 <..= 5).to_list()
[1, 2, 3, 4, 5]

method

method (rge :: SequenceRange).to_sequence()

:: Sequence.expect_of(Int)

Implements Sequenceable by returning a sequence of integers in rge in ascending order. The sequence is infinite when rge lacks an ending point.

> for List (i in 0..5): // optimizing
i
[0, 1, 2, 3, 4]
> for List (i in (0..5).to_sequence()): // non-optimizing
i
[0, 1, 2, 3, 4]

method

method (rge :: SequenceRange).step_by(step :: PosInt)

:: Sequence.expect_of(Int)

Returns a sequence of integers in rge in ascending order, stepping by the given step size. The sequence is infinite when rge lacks an ending point.

When invoked as rge.step_by(step) in an each clause of for, the sequence is optimized, in cooperation with the optimization in .., ..=, <.., or <..=.

> for List (i in (0..5).step_by(2)):
i
[0, 2, 4]
> for List (i in (0 <..= 10).step_by(3)):
i
[1, 4, 7, 10]

annotation

DescendingRange

annotation

DescendingListRange

The DescendingRange annotation matches a “descending range” produced by >=.., >=..=, >.., >..=, or ListRange.descending. Such an object isn’t actually a range, but is merely created for the purpose of producing range-like sequences in descending order.

Since the resulting sequence is in descending order, generally, the starting point must be greater than (as opposed to less than) or equal to the ending point. Moreover, each DescendingRange form corresponds to one of the SequenceRange forms. In particular, the same kind of optimization in SequenceRange forms also applies to DescendingRange forms.

The DescendingListRange matches a DescendingRange object that is also listable. These are precisely the possible results of ListRange.descending.

expression

start_expr >=.. end_expr

repetition

start_repet >=.. end_repet

expression

start_expr >=..

repetition

start_repet >=..

function

fun DescendingRange.from_to(start :: Int, end :: Int)

:: DescendingListRange

function

fun DescendingRange.from(start :: Int)

:: DescendingRange

Corresponds to .., Range.from_to, and Range.from.

expression

start_expr >=..= end_expr

repetition

start_repet >=..= end_repet

function

fun DescendingRange.from_to_inclusive(start :: Int, end :: Int)

:: DescendingListRange

Corresponds to ..= and Range.from_to_inclusive.

expression

start_expr >.. end_expr

repetition

start_repet >.. end_repet

expression

start_expr >..

repetition

start_repet >..

function

fun DescendingRange.from_exclusive_to(start :: Int, end :: Int)

:: DescendingListRange

function

fun DescendingRange.from_exclusive(start :: Int)

:: DescendingRange

Corresponds to <.., Range.from_exclusive_to, and Range.from_exclusive.

expression

start_expr >..= end_expr

repetition

start_repet >..= end_repet

function

fun DescendingRange.from_exclusive_to_inclusive(start :: Int,

end :: Int)

:: DescendingListRange

Corresponds to <..= and Range.from_exclusive_to_inclusive.

method

method (rge :: ListRange).descending() :: DescendingListRange

Returns a DescendingListRange object that has the same integers as rge, by swapping the upper and lower bounds.

When invoked as rge.descending() in an each clause of for, the sequence is optimized, in cooperation with the optimization in .., ..=, <.., or <..=.

> for List (i in (0..5).descending()):
    i
[4, 3, 2, 1, 0]
> for List (i in (0..5).descending().step_by(-2)):
    i
[4, 2, 0]
> for List (i in (0 <..= 10).descending().step_by(-3)):
    i
[10, 7, 4, 1]
> (0..5).descending().to_list()
[4, 3, 2, 1, 0]
> [& (0..5).descending()]
[4, 3, 2, 1, 0]
> (0 <..= 5).descending().to_list()
[5, 4, 3, 2, 1]

method

method (rge :: DescendingListRange).to_list() :: List.of(Int)

Implements Listable by returning a list of integers in rge in descending order.

> (5 >=.. 0).to_list()
[5, 4, 3, 2, 1]
> [& 5 >=.. 0]
[5, 4, 3, 2, 1]
> (5 >..= 0).to_list()
[4, 3, 2, 1, 0]

method

method (rge :: DescendingRange).to_sequence()

:: Sequence.expect_of(Int)

Implements Sequenceable by returning a sequence of integers in rge in descending order. The sequence is infinite when rge lacks an ending point.

> for List (i in 5 >=.. 0): // optimizing
i
[5, 4, 3, 2, 1]
> for List (i in (5 >=.. 0).to_sequence()): // non-optimizing
i
[5, 4, 3, 2, 1]

method

method (rge :: DescendingRange).step_by(step :: NegInt)

:: Sequence.expect_of(Int)

Returns a sequence of integers in rge in descending order, stepping by the given step size. The sequence is infinite when rge lacks an ending point.

When invoked as rge.step_by(step) in an each clause of for, the sequence is optimized, in cooperation with the optimization in .., ..=, <.., <..=, or ListRange.descending.

> for List (i in (5 >=.. 0).step_by(-2)):
i
[5, 3, 1]
> for List (i in (10 >..= 0).step_by(-3)):
i
[9, 6, 3, 0]

1	Notation and Conventions
2	Implicits and Context
3	Names and Definitions
4	Functions and Operators
5	Comparison and Branching
6	Objects and Annotations
7	Basic Data
8	Collections and Iteration
9	Object Protocols
10	Higher-Order Control
11	Code as Data
12	String Formatting and Matching
13	Input and Output
14	Operating System
15	Threads and Concurrency
16	Reflection and Security
17	Runtime System

8.1	Lists
8.2	Pairs and Pair Lists
8.3	Mutable Lists
8.4	Arrays
8.5	Maps
8.6	Sets
8.7	Repetitions
8.8	Iteration
8.9	Ranges