Standard Library

class Range

A run of consecutive integers written a..b, including both ends.

since 0.1.0-alpha.1linuxwindowswasm

bases

IIterable<int>

Overview

The expression 1..5 produces a Range that stands for 1, 2, 3, 4 and 5. A for loop over a range counts directly, and because a Range is also an IIterable<int> it can be passed anywhere an iterable is expected. When start is greater than end the range is empty. Inside an array literal a range spreads into its elements, so [1..3, 7] is [1, 2, 3, 7].

Description

a..b builds a Range of the integers from a up to and including b. Both ends are inclusive, so 1..3 contains 1, 2 and 3. A range whose start is greater than its end is empty: a loop over 5..4 never runs its body. The two ends are available as the fields start and end, and a range prints as 3..6.

A range is used in three ways.

• In a for loop. for (int i in 1..n) is a plain counted loop. The compiler recognises the range and counts inline, so no Range object is created and no iterator runs.
• In an array literal. A range inside [...] spreads into its elements: [0, 1..3, 9] is [0, 1, 2, 3, 9], and [1..n] is the array 1 through n.
• As an IIterable<int>. Range implements the iteration protocol, so a range value can be passed wherever an IIterable<int> is expected and driven by hand with iterator(), hasNext() and next().

Rules

• Both bounds are included. An empty range (start above end) has no elements.
• A Range holds only start and end; it never stores the integers between them.
• A for loop over a range literal or a Range value takes a built-in fast path and never calls iterator(). Only code that uses the range through the IIterable<int> interface goes through the iterator protocol.

Examples

Counting, spreading and iterating by hand

int n = 5;
int total = 0;
for (int i in 1..n) { total = total + i; }
console.writeln(total);
Range r = 3..6;
console.writeln("${r.start} to ${r.end}");
console.writeln([0, 1..3, 9]);
int empty = 0;
for (int i in 5..4) { empty = empty + 1; }
console.writeln(empty);
IIterable<int> source = r;
IIterator<int> it = source.iterator();
while (it.hasNext()) { console.writeln(it.next()); }

15
3 to 6
[0, 1, 2, 3, 9]
0
3
4
5
6

Examples

int total = 0;
for (int i in 1..5) {
    total = total + i;
}
console.writeln("sum of 1..5 = ${total}");

Range r = 3..6;
console.writeln("${r.start} to ${r.end}");
console.writeln([1..3, 7].joinToString(","));

int n = 0;
for (int i in 5..1) {
    n = n + 1;
}
console.writeln("iterations of 5..1: ${n}");

sum of 1..5 = 15
3 to 6
1,2,3,7
iterations of 5..1: 0

Constructors

new

new(int s, int e)

Create the range from s up to and including e.

Writing s..e is the usual way to get the same value.

Parameters

s

The first integer of the range.

e

The last integer of the range, which is included.

Examples

Range r = Range(2, 4);
for (int i in r) {
    console.writeln("item ${i}");
}

item 2
item 3
item 4

Fields

end

int end

The last integer of the range, which is included.

start

int start

The first integer of the range.

Methods

iterator

iterator() -> IIterator<int>

Create an iterator that steps through the range from start to end.

The iterator reports no elements when start is greater than end. A for loop does not need this call; it is for code that drives an iterator by hand.

Returns

A new iterator positioned before the first element.

Examples

IIterator<int> it = (3..5).iterator();
while (it.hasNext()) {
    console.writeln(it.next());
}

3
4
5

See also: IIterator

See also

• IIterable — A source of values that can be walked with for.
• Array — An ordered sequence of values of one type, Array<T>, with value semantics.