Range class

A robust, memory-efficient arithmetic progression class for Dart.

Range generates a sequence of numbers (integers or doubles) on the fly without storing them in memory. It extends IterableMixin, allowing usage with standard Dart iterable methods (map, where, reduce) while providing optimized $O(1)$ implementations for mathematical operations like sum, length, and contains.

Key Features:

Lazy Evaluation: Can represent ranges of billions of numbers with almost zero memory usage.
Performance: length, sum, average, and contains are calculated mathematically in constant time $O(1)$.
Flexibility: Supports integers, doubles, negative steps, and linear interpolation (Range.linspace).

Modes of Operation:

Math Mode: Floating point numbers, infinite generators, calculus.
Slice Mode: Integer generation relative to an array size (supporting negative indices).

Examples

Math Mode:

// Standard integer loop
for (final i in Range(0, 5)) {
  print(i); // 0, 1, 2, 3, 4
}

// Floating point step
final doubles = Range(0.0, 1.0, 0.2); // 0.0, 0.2, 0.4, 0.6, 0.8

// Instant math on massive ranges
final huge = Range(0, 1000000);
print(huge.sum); // Calculated instantly

Parsing Mode:

// Parse standard Python syntax
final r = Range.parse("0:10:2");

Slicing Mode (The "View" Feature):

List<String> data = ['A', 'B', 'C', 'D', 'E'];

// Create a range that represents "All items, reversed"
// We pass data.length so it knows how to resolve "-1"
final r = Range.bounds(data.length, "::-1");

print(r.toList()); // [4, 3, 2, 1, 0]

Inheritance

Constructors

Range(num start, num end, [num step = 1]): Creates a range from start to end (exclusive).
Range.bounds(int length, String spec): Creates a Range by resolving a slice string against a specific length.
factory
Range.inclusive(num start, num end, [num step = 1]): Creates a range from start to end (inclusive).
Range.linspace(num start, num end, int count): Creates a range with exactly count values evenly spaced between start and end.
factory
Range.parse(String spec): Parses a concrete string spec like "0:10:2".
factory

Properties

average → num: Calculates the arithmetic mean (average) of the range.
no setter
end → num: The bound of the range. Depending on the constructor, this may be inclusive or exclusive.
final
first → num: The first element.
no setterinherited
hashCode → int: The hash code for this object.
no setterinherited
isEmpty → bool: Whether this collection has no elements.
no setterinherited
isInclusive → bool: Whether end is included in the range.
final
isNotEmpty → bool: Whether this collection has at least one element.
no setterinherited
iterator → Iterator<num>: A new Iterator that allows iterating the elements of this Iterable.
no setteroverride
last → num: The last element.
no setterinherited
lastValue → num: Returns the actual last value in the sequence.
no setter
length → int: Returns the number of elements in the range.
no setteroverride
max → num: Returns the largest value in the range.
no setter
min → num: Returns the smallest value in the range.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
single → num: Checks that this iterable has only one element, and returns that element.
no setterinherited
start → num: The starting value of the range.
final
step → num: The difference between each value in the sequence.
final
sum → num: Calculates the arithmetic sum of the range.
no setter
toInts → Iterable<int>: Returns integers only. Throws if range contains fractions.
no setter

Methods

any(bool test(num element)) → bool: Checks whether any element of this iterable satisfies test.
inherited
cast<R>() → Iterable<R>: A view of this iterable as an iterable of R instances.
inherited
contains(Object? element) → bool: Checks if element is contained in the range.
override
elementAt(int index) → num: Returns the indexth element.
inherited
every(bool test(num element)) → bool: Checks whether every element of this iterable satisfies test.
inherited
expand<T>(Iterable<T> toElements(num element)) → Iterable<T>: Expands each element of this Iterable into zero or more elements.
inherited
firstWhere(bool test(num element), {num orElse()?}) → num: The first element that satisfies the given predicate test.
inherited
fold<T>(T initialValue, T combine(T previousValue, num element)) → T: Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
inherited
followedBy(Iterable<num> other) → Iterable<num>: Creates the lazy concatenation of this iterable and other.
inherited
forEach(void action(num element)) → void: Invokes action on each element of this iterable in iteration order.
inherited
join([String separator = ""]) → String: Converts each element to a String and concatenates the strings.
inherited
lastWhere(bool test(num element), {num orElse()?}) → num: The last element that satisfies the given predicate test.
inherited
map<T>(T toElement(num e)) → Iterable<T>: The current elements of this iterable modified by toElement.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
random([Random? random]) → num: Returns a valid random number from within this specific range.
reduce(num combine(num value, num element)) → num: Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
inherited
singleWhere(bool test(num element), {num orElse()?}) → num: The single element that satisfies test.
inherited
skip(int count) → Iterable<num>: Creates an Iterable that provides all but the first count elements.
inherited
skipWhile(bool test(num value)) → Iterable<num>: Creates an Iterable that skips leading elements while test is satisfied.
inherited
take(int count) → Iterable<num>: Creates a lazy iterable of the count first elements of this iterable.
inherited
takeWhile(bool test(num value)) → Iterable<num>: Creates a lazy iterable of the leading elements satisfying test.
inherited
toList({bool growable = true}) → List<num>: Creates a List containing the elements of this Iterable.
inherited
toSet() → Set<num>: Creates a Set containing the same elements as this iterable.
inherited
toStream({Duration? interval}) → Stream<num>: Converts the range into an asynchronous Stream.
toString() → String: Returns a string representation of (some of) the elements of this.
override
where(bool test(num element)) → Iterable<num>: Creates a new lazy Iterable with all elements that satisfy the predicate test.
inherited
whereType<T>() → Iterable<T>: Creates a new lazy Iterable with all elements that have type T.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited
operator [](int index) → num: Returns the value at index index in the generated sequence. Throws if index is out of bounds.