Appearance
UnmodifiableListView<E>
class UnmodifiableListView<E> extends UnmodifiableListBase<E> implements List<E>An unmodifiable List view of another List.
The source of the elements may be a List or any Iterable with efficient Iterable.length and Iterable.elementAt.
dart
final numbers = <int>[10, 20, 30];
final unmodifiableListView = UnmodifiableListView(numbers);
// Insert new elements into the original list.
numbers.addAll([40, 50]);
print(unmodifiableListView); // [10, 20, 30, 40, 50]
unmodifiableListView.remove(20); // Throws.Inheritance
Object → ListBase<E> → UnmodifiableListView<E>
Implemented types
Available Extensions
Constructors
UnmodifiableListView()
UnmodifiableListView(Iterable<E> source)Creates an unmodifiable list backed by source.
The source of the elements may be a List or any Iterable with efficient Iterable.length and Iterable.elementAt.
Implementation
dart
UnmodifiableListView(Iterable<E> source) : _source = source;Properties
first read / write inherited
E get firstgetter:
The first element.
Throws a StateError if this is empty. Otherwise returns the first element in the iteration order, equivalent to this.elementAt(0).
setter:
The first element of the list.
The list must be non-empty when accessing its first element.
The first element of a list can be modified, unlike an Iterable. A list.first is equivalent to list[0], both for getting and setting the value.
dart
final numbers = <int>[1, 2, 3];
print(numbers.first); // 1
numbers.first = 10;
print(numbers.first); // 10
numbers.clear();
numbers.first; // Throws.Inherited from ListBase.
Implementation
dart
E get first {
if (length == 0) throw IterableElementError.noElement();
return this[0];
}
set first(E element) {
throw UnsupportedError("Cannot modify an unmodifiable list");
}firstOrNull extension no setter
T? get firstOrNullThe first element of this iterator, or null if the iterable is empty.
Available on Iterable<E>, provided by the IterableExtensions<T> extension
Implementation
dart
T? get firstOrNull {
var iterator = this.iterator;
if (iterator.moveNext()) return iterator.current;
return null;
}hashCode no setter inherited
int get hashCodeThe hash code for this object.
A hash code is a single integer which represents the state of the object that affects operator == comparisons.
All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).
If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.
Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.
Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.
If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.
Inherited from Object.
Implementation
dart
external int get hashCode;indexed extension no setter
Iterable<Record> get indexedPairs of elements of the indices and elements of this iterable.
The elements are (0, this.first) through (this.length - 1, this.last), in index/iteration order.
Available on Iterable<E>, provided by the IterableExtensions<T> extension
Implementation
dart
@pragma('vm:prefer-inline')
Iterable<(int, T)> get indexed => IndexedIterable<T>(this, 0);isEmpty no setter inherited
bool get isEmptyWhether this collection has no elements.
May be computed by checking if iterator.moveNext() returns false.
Example:
dart
final emptyList = <int>[];
print(emptyList.isEmpty); // true;
print(emptyList.iterator.moveNext()); // falseInherited from ListBase.
Implementation
dart
@pragma("vm:prefer-inline")
bool get isEmpty => length == 0;isNotEmpty no setter inherited
bool get isNotEmptyWhether this collection has at least one element.
May be computed by checking if iterator.moveNext() returns true.
Example:
dart
final numbers = <int>{1, 2, 3};
print(numbers.isNotEmpty); // true;
print(numbers.iterator.moveNext()); // trueInherited from ListBase.
Implementation
dart
bool get isNotEmpty => !isEmpty;iterator no setter inherited
Iterator<E> get iteratorA new Iterator that allows iterating the elements of this Iterable.
Iterable classes may specify the iteration order of their elements (for example List always iterate in index order), or they may leave it unspecified (for example a hash-based Set may iterate in any order).
Each time iterator is read, it returns a new iterator, which can be used to iterate through all the elements again. The iterators of the same iterable can be stepped through independently, but should return the same elements in the same order, as long as the underlying collection isn't changed.
Modifying the collection may cause new iterators to produce different elements, and may change the order of existing elements. A List specifies its iteration order precisely, so modifying the list changes the iteration order predictably. A hash-based Set may change its iteration order completely when adding a new element to the set.
Modifying the underlying collection after creating the new iterator may cause an error the next time Iterator.moveNext is called on that iterator. Any modifiable iterable class should specify which operations will break iteration.
Inherited from ListBase.
Implementation
dart
@pragma('vm:prefer-inline')
Iterator<E> get iterator => ListIterator<E>(this);last read / write inherited
E get lastgetter:
The last element.
Throws a StateError if this is empty. Otherwise may iterate through the elements and returns the last one seen. Some iterables may have more efficient ways to find the last element (for example a list can directly access the last element, without iterating through the previous ones).
setter:
The last element of the list.
The list must be non-empty when accessing its last element.
The last element of a list can be modified, unlike an Iterable. A list.last is equivalent to theList[theList.length - 1], both for getting and setting the value.
dart
final numbers = <int>[1, 2, 3];
print(numbers.last); // 3
numbers.last = 10;
print(numbers.last); // 10
numbers.clear();
numbers.last; // Throws.Inherited from ListBase.
Implementation
dart
E get last {
if (length == 0) throw IterableElementError.noElement();
return this[length - 1];
}
set last(E element) {
throw UnsupportedError("Cannot modify an unmodifiable list");
}lastOrNull extension no setter
T? get lastOrNullThe last element of this iterable, or null if the iterable is empty.
This computation may not be efficient. The last value is potentially found by iterating the entire iterable and temporarily storing every value. The process only iterates the iterable once. If iterating more than once is not a problem, it may be more efficient for some iterables to do:
dart
var lastOrNull = iterable.isEmpty ? null : iterable.last;Available on Iterable<E>, provided by the IterableExtensions<T> extension
Implementation
dart
T? get lastOrNull {
if (this is EfficientLengthIterable) {
if (isEmpty) return null;
return last;
}
var iterator = this.iterator;
if (!iterator.moveNext()) return null;
T result;
do {
result = iterator.current;
} while (iterator.moveNext());
return result;
}length read / write inherited-setter override-getter
int get lengthgetter:
The number of objects in this list.
The valid indices for a list are 0 through length - 1.
dart
final numbers = <int>[1, 2, 3];
print(numbers.length); // 3setter:
This operation is not supported by an unmodifiable list.
Implementation
dart
int get length => _source.length;
set length(int newLength) {
throw UnsupportedError("Cannot change the length of an unmodifiable list");
}nonNulls extension no setter
Iterable<T> get nonNullsThe non-null elements of this iterable.
The same elements as this iterable, except that null values are omitted.
Available on Iterable<E>, provided by the NullableIterableExtensions<T extends Object> extension
Implementation
dart
Iterable<T> get nonNulls => NonNullsIterable<T>(this);reversed no setter inherited
Iterable<E> get reversedAn Iterable of the objects in this list in reverse order.
dart
final numbers = <String>['two', 'three', 'four'];
final reverseOrder = numbers.reversed;
print(reverseOrder.toList()); // [four, three, two]Inherited from ListBase.
Implementation
dart
Iterable<E> get reversed => ReversedListIterable<E>(this);runtimeType no setter inherited
Type get runtimeTypeA representation of the runtime type of the object.
Inherited from Object.
Implementation
dart
external Type get runtimeType;single no setter inherited
E get singleChecks that this iterable has only one element, and returns that element.
Throws a StateError if this is empty or has more than one element. This operation will not iterate past the second element.
Inherited from ListBase.
Implementation
dart
E get single {
if (length == 0) throw IterableElementError.noElement();
if (length > 1) throw IterableElementError.tooMany();
return this[0];
}singleOrNull extension no setter
T? get singleOrNullThe single element of this iterator, or null.
If the iterator has precisely one element, this is that element. Otherwise, if the iterator has zero elements, or it has two or more, the value is null.
Available on Iterable<E>, provided by the IterableExtensions<T> extension
Implementation
dart
T? get singleOrNull {
var iterator = this.iterator;
if (iterator.moveNext()) {
var result = iterator.current;
if (!iterator.moveNext()) return result;
}
return null;
}toJS extension no setter
JSArray<T> get toJSConverts this List to a JSArray by either casting, unwrapping, or cloning the List.
INFO
Depending on whether code is compiled to JavaScript or Wasm, this conversion will have different semantics.
When compiling to JavaScript, the core List is a JavaScript Array, and therefore this getter simply casts. If the List is not a core List e.g. a user-defined list, this getter throws with a cast error.
When compiling to Wasm, this List is a wrapper around an Array if it was converted via JSArrayToList.toDart. If it's a wrapper, this getter unwraps it and returns the Array. If it's instantiated in Dart, this getter clones this List's values into a new JSArray.
Avoid assuming that modifications to this List will affect the returned JSArray and vice versa in all compilers unless it was first converted via JSArrayToList.toDart.
Available on List<E>, provided by the ListToJSArray<T extends JSAny?> extension
Implementation
dart
external JSArray<T> get toJS;toJSProxyOrRef extension no setter
JSArray<T> get toJSProxyOrRefConverts this List to a JSArray by either casting, unwrapping, or proxying the List.
INFO
Depending on whether code is compiled to JavaScript or Wasm, this conversion will have different semantics.
When compiling to JavaScript, the core List is a JavaScript Array, and therefore this getter simply casts. If the List is not a core List e.g. a user-defined list, this getter throws with a cast error.
When compiling to Wasm, this List is a wrapper around an Array if it was converted via JSArrayToList.toDart. If it's a wrapper, this getter unwraps it and returns the Array. If it's instantiated in Dart, this getter proxies the List using a heavyweight Array wrapper. Access to the original List's elements may be very unperformant.
Modifications to this List will affect the returned JSArray and vice versa.
Available on List<E>, provided by the ListToJSArray<T extends JSAny?> extension
Implementation
dart
external JSArray<T> get toJSProxyOrRef;wait extension no setter
Waits for futures in parallel.
Waits for all the futures in this iterable. Returns a list of the resulting values, in the same order as the futures which created them, if all futures are successful.
Similar to Future.wait, but reports errors using a ParallelWaitError, which allows the caller to handle errors and dispose successful results if necessary.
The returned future is completed when all the futures have completed. If any of the futures do not complete, nor does the returned future.
If any future completes with an error, the returned future completes with a ParallelWaitError. The ParallelWaitError.values is a list of the values for successful futures and null for futures with errors. The ParallelWaitError.errors is a list of the same length, with null values for the successful futures and an AsyncError with the error for futures which completed with an error.
Available on Iterable<E>, provided by the FutureIterable<T> extension
Implementation
dart
Future<List<T>> get wait {
var results = [for (var f in this) _FutureResult<T>(f)];
if (results.isEmpty) return Future<List<T>>.value(<T>[]);
@pragma('vm:awaiter-link')
final c = Completer<List<T>>.sync();
_FutureResult._waitAll(results, (errors) {
if (errors == 0) {
c.complete([for (var r in results) r.value]);
} else {
var errorList = [for (var r in results) r.errorOrNull];
c.completeError(
ParallelWaitError<List<T?>, List<AsyncError?>>(
[for (var r in results) r.valueOrNull],
errorList,
errorCount: errors,
defaultError: errorList.firstWhere(_notNull),
),
);
}
});
return c.future;
}Methods
add() inherited
void add(E value)This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void add(E value) {
throw UnsupportedError("Cannot add to an unmodifiable list");
}addAll() inherited
void addAll(Iterable<E> iterable)This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void addAll(Iterable<E> iterable) {
throw UnsupportedError("Cannot add to an unmodifiable list");
}any() inherited
Checks whether any element of this iterable satisfies test.
Checks every element in iteration order, and returns true if any of them make test return true, otherwise returns false. Returns false if the iterable is empty.
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
var result = numbers.any((element) => element >= 5); // true;
result = numbers.any((element) => element >= 10); // false;Inherited from ListBase.
Implementation
dart
bool any(bool test(E element)) {
int length = this.length;
for (int i = 0; i < length; i++) {
if (test(this[i])) return true;
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
return false;
}asMap() inherited
An unmodifiable Map view of this list.
The map uses the indices of this list as keys and the corresponding objects as values. The Map.keys Iterable iterates the indices of this list in numerical order.
dart
var words = <String>['fee', 'fi', 'fo', 'fum'];
var map = words.asMap(); // {0: fee, 1: fi, 2: fo, 3: fum}
map.keys.toList(); // [0, 1, 2, 3]Inherited from ListBase.
Implementation
dart
Map<int, E> asMap() {
return ListMapView<E>(this);
}asNameMap() extension
Creates a map from the names of enum values to the values.
The collection that this method is called on is expected to have enums with distinct names, like the values list of an enum class. Only one value for each name can occur in the created map, so if two or more enum values have the same name (either being the same value, or being values of different enum type), at most one of them will be represented in the returned map.
Available on Iterable<E>, provided by the EnumByName<T extends Enum> extension
Implementation
dart
Map<String, T> asNameMap() => <String, T>{
for (var value in this) value._name: value,
};byName() extension
T byName(String name)Finds the enum value in this list with name name.
Goes through this collection looking for an enum with name name, as reported by EnumName.name. Returns the first value with the given name. Such a value must be found.
Available on Iterable<E>, provided by the EnumByName<T extends Enum> extension
Implementation
dart
T byName(String name) {
for (var value in this) {
if (value._name == name) return value;
}
throw ArgumentError.value(name, "name", "No enum value with that name");
}cast() override
List<R> cast<R>()Returns a view of this list as a list of R instances.
If this list contains only instances of R, all read operations will work correctly. If any operation tries to read an element that is not an instance of R, the access will throw instead.
Elements added to the list (e.g., by using add or addAll) must be instances of R to be valid arguments to the adding function, and they must also be instances of E to be accepted by this list as well.
Methods which accept Object? as argument, like contains and remove, will pass the argument directly to the this list's method without any checks. That means that you can do listOfStrings.cast<int>().remove("a") successfully, even if it looks like it shouldn't have any effect.
Typically implemented as List.castFrom<E, R>(this).
Implementation
dart
List<R> cast<R>() => UnmodifiableListView(_source.cast<R>());clear() inherited
void clear()This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void clear() {
throw UnsupportedError("Cannot clear an unmodifiable list");
}contains() inherited
Whether the collection contains an element equal to element.
This operation will check each element in order for being equal to element, unless it has a more efficient way to find an element equal to element. Stops iterating on the first equal element.
The equality used to determine whether element is equal to an element of the iterable defaults to the Object.== of the element.
Some types of iterable may have a different equality used for its elements. For example, a Set may have a custom equality (see Set.identity) that its contains uses. Likewise the Iterable returned by a Map.keys call should use the same equality that the Map uses for keys.
Example:
dart
final gasPlanets = <int, String>{1: 'Jupiter', 2: 'Saturn'};
final containsOne = gasPlanets.keys.contains(1); // true
final containsFive = gasPlanets.keys.contains(5); // false
final containsJupiter = gasPlanets.values.contains('Jupiter'); // true
final containsMercury = gasPlanets.values.contains('Mercury'); // falseInherited from ListBase.
Implementation
dart
bool contains(Object? element) {
int length = this.length;
for (int i = 0; i < length; i++) {
if (this[i] == element) return true;
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
return false;
}elementAt() inherited
E elementAt(int index)Returns the indexth element.
The index must be non-negative and less than length. Index zero represents the first element (so iterable.elementAt(0) is equivalent to iterable.first).
May iterate through the elements in iteration order, ignoring the first index elements and then returning the next. Some iterables may have a more efficient way to find the element.
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
final elementAt = numbers.elementAt(4); // 6Inherited from ListBase.
Implementation
dart
E elementAt(int index) => this[index];elementAtOrNull() extension
T? elementAtOrNull(int index)The element at position index of this iterable, or null.
The index is zero based, and must be non-negative.
Returns the result of elementAt(index) if the iterable has at least index + 1 elements, and null otherwise.
Available on Iterable<E>, provided by the IterableExtensions<T> extension
Implementation
dart
T? elementAtOrNull(int index) {
RangeError.checkNotNegative(index, "index");
if (this is EfficientLengthIterable) {
if (index >= length) return null;
return elementAt(index);
}
var iterator = this.iterator;
do {
if (!iterator.moveNext()) return null;
} while (--index >= 0);
return iterator.current;
}every() inherited
Checks whether every element of this iterable satisfies test.
Checks every element in iteration order, and returns false if any of them make test return false, otherwise returns true. Returns true if the iterable is empty.
Example:
dart
final planetsByMass = <double, String>{0.06: 'Mercury', 0.81: 'Venus',
0.11: 'Mars'};
// Checks whether all keys are smaller than 1.
final every = planetsByMass.keys.every((key) => key < 1.0); // trueInherited from ListBase.
Implementation
dart
bool every(bool test(E element)) {
int length = this.length;
for (int i = 0; i < length; i++) {
if (!test(this[i])) return false;
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
return true;
}expand() inherited
Expands each element of this Iterable into zero or more elements.
The resulting Iterable runs through the elements returned by toElements for each element of this, in iteration order.
The returned Iterable is lazy, and calls toElements for each element of this iterable every time the returned iterable is iterated.
Example:
dart
Iterable<int> count(int n) sync* {
for (var i = 1; i <= n; i++) {
yield i;
}
}
var numbers = [1, 3, 0, 2];
print(numbers.expand(count)); // (1, 1, 2, 3, 1, 2)Equivalent to:
dart
Iterable<T> expand<T>(Iterable<T> toElements(E e)) sync* {
for (var value in this) {
yield* toElements(value);
}
}Inherited from ListBase.
Implementation
dart
Iterable<T> expand<T>(Iterable<T> f(E element)) =>
ExpandIterable<E, T>(this, f);fillRange() inherited
This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void fillRange(int start, int end, [E? fillValue]) {
throw UnsupportedError("Cannot modify an unmodifiable list");
}firstWhere() inherited
E firstWhere(bool Function(E element) test, {(E Function())? orElse})The first element that satisfies the given predicate test.
Iterates through elements and returns the first to satisfy test.
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
var result = numbers.firstWhere((element) => element < 5); // 1
result = numbers.firstWhere((element) => element > 5); // 6
result =
numbers.firstWhere((element) => element > 10, orElse: () => -1); // -1If no element satisfies test, the result of invoking the orElse function is returned. If orElse is omitted, it defaults to throwing a StateError. Stops iterating on the first matching element.
Inherited from ListBase.
Implementation
dart
E firstWhere(bool test(E element), {E Function()? orElse}) {
int length = this.length;
for (int i = 0; i < length; i++) {
E element = this[i];
if (test(element)) return element;
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
if (orElse != null) return orElse();
throw IterableElementError.noElement();
}fold() inherited
T fold<T>(T initialValue, T Function(T previousValue, E element) combine)Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
Uses initialValue as the initial value, then iterates through the elements and updates the value with each element using the combine function, as if by:
dart
var value = initialValue;
for (E element in this) {
value = combine(value, element);
}
return value;Example of calculating the sum of an iterable:
dart
final numbers = <double>[10, 2, 5, 0.5];
const initialValue = 100.0;
final result = numbers.fold<double>(
initialValue, (previousValue, element) => previousValue + element);
print(result); // 117.5Inherited from ListBase.
Implementation
dart
T fold<T>(T initialValue, T combine(T previousValue, E element)) {
var value = initialValue;
int length = this.length;
for (int i = 0; i < length; i++) {
value = combine(value, this[i]);
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
return value;
}followedBy() inherited
Creates the lazy concatenation of this iterable and other.
The returned iterable will provide the same elements as this iterable, and, after that, the elements of other, in the same order as in the original iterables.
Example:
dart
var planets = <String>['Earth', 'Jupiter'];
var updated = planets.followedBy(['Mars', 'Venus']);
print(updated); // (Earth, Jupiter, Mars, Venus)Inherited from ListBase.
Implementation
dart
Iterable<E> followedBy(Iterable<E> other) =>
FollowedByIterable<E>.firstEfficient(this, other);forEach() inherited
void forEach(void Function(E value) action)Invokes action on each element of this iterable in iteration order.
Example:
dart
final numbers = <int>[1, 2, 6, 7];
numbers.forEach(print);
// 1
// 2
// 6
// 7Inherited from ListBase.
Implementation
dart
void forEach(void action(E element)) {
int length = this.length;
for (int i = 0; i < length; i++) {
action(this[i]);
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
}getRange() inherited
Creates an Iterable that iterates over a range of elements.
The returned iterable iterates over the elements of this list with positions greater than or equal to start and less than end.
The provided range, start and end, must be valid at the time of the call. A range from start to end is valid if 0 ≤ start ≤ end ≤ length. An empty range (with end == start) is valid.
The returned Iterable behaves like skip(start).take(end - start). That is, it does not break if this list changes size, it just ends early if it reaches the end of the list early (if end, or even start, becomes greater than length).
dart
final colors = <String>['red', 'green', 'blue', 'orange', 'pink'];
final firstRange = colors.getRange(0, 3);
print(firstRange.join(', ')); // red, green, blue
final secondRange = colors.getRange(2, 5);
print(secondRange.join(', ')); // blue, orange, pinkInherited from ListBase.
Implementation
dart
Iterable<E> getRange(int start, int end) {
RangeError.checkValidRange(start, end, this.length);
return SubListIterable<E>(this, start, end);
}indexOf() inherited
The first index of element in this list.
Searches the list from index start to the end of the list. The first time an object o is encountered so that o == element, the index of o is returned.
dart
final notes = <String>['do', 're', 'mi', 're'];
print(notes.indexOf('re')); // 1
final indexWithStart = notes.indexOf('re', 2); // 3Returns -1 if element is not found.
dart
final notes = <String>['do', 're', 'mi', 're'];
final index = notes.indexOf('fa'); // -1Inherited from ListBase.
Implementation
dart
int indexOf(Object? element, [int start = 0]) {
if (start < 0) start = 0;
for (int i = start; i < this.length; i++) {
if (this[i] == element) return i;
}
return -1;
}indexWhere() inherited
The first index in the list that satisfies the provided test.
Searches the list from index start to the end of the list. The first time an object o is encountered so that test(o) is true, the index of o is returned.
dart
final notes = <String>['do', 're', 'mi', 're'];
final first = notes.indexWhere((note) => note.startsWith('r')); // 1
final second = notes.indexWhere((note) => note.startsWith('r'), 2); // 3Returns -1 if element is not found.
dart
final notes = <String>['do', 're', 'mi', 're'];
final index = notes.indexWhere((note) => note.startsWith('k')); // -1Inherited from ListBase.
Implementation
dart
int indexWhere(bool test(E element), [int start = 0]) {
if (start < 0) start = 0;
for (int i = start; i < this.length; i++) {
if (test(this[i])) return i;
}
return -1;
}insert() inherited
void insert(int index, E element)This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void insert(int index, E element) {
throw UnsupportedError("Cannot add to an unmodifiable list");
}insertAll() inherited
This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void insertAll(int at, Iterable<E> iterable) {
throw UnsupportedError("Cannot add to an unmodifiable list");
}join() inherited
Converts each element to a String and concatenates the strings.
Iterates through elements of this iterable, converts each one to a String by calling Object.toString, and then concatenates the strings, with the separator string interleaved between the elements.
Example:
dart
final planetsByMass = <double, String>{0.06: 'Mercury', 0.81: 'Venus',
0.11: 'Mars'};
final joinedNames = planetsByMass.values.join('-'); // Mercury-Venus-MarsInherited from ListBase.
Implementation
dart
String join([String separator = ""]) {
if (length == 0) return "";
StringBuffer buffer = StringBuffer()..writeAll(this, separator);
return buffer.toString();
}lastIndexOf() inherited
The last index of element in this list.
Searches the list backwards from index start to 0.
The first time an object o is encountered so that o == element, the index of o is returned.
dart
final notes = <String>['do', 're', 'mi', 're'];
const startIndex = 2;
final index = notes.lastIndexOf('re', startIndex); // 1If start is not provided, this method searches from the end of the list.
dart
final notes = <String>['do', 're', 'mi', 're'];
final index = notes.lastIndexOf('re'); // 3Returns -1 if element is not found.
dart
final notes = <String>['do', 're', 'mi', 're'];
final index = notes.lastIndexOf('fa'); // -1Inherited from ListBase.
Implementation
dart
int lastIndexOf(Object? element, [int? start]) {
if (start == null || start >= this.length) start = this.length - 1;
for (int i = start; i >= 0; i--) {
if (this[i] == element) return i;
}
return -1;
}lastIndexWhere() inherited
The last index in the list that satisfies the provided test.
Searches the list from index start to 0. The first time an object o is encountered so that test(o) is true, the index of o is returned. If start is omitted, it defaults to the length of the list.
dart
final notes = <String>['do', 're', 'mi', 're'];
final first = notes.lastIndexWhere((note) => note.startsWith('r')); // 3
final second = notes.lastIndexWhere((note) => note.startsWith('r'),
2); // 1Returns -1 if element is not found.
dart
final notes = <String>['do', 're', 'mi', 're'];
final index = notes.lastIndexWhere((note) => note.startsWith('k'));
print(index); // -1Inherited from ListBase.
Implementation
dart
int lastIndexWhere(bool test(E element), [int? start]) {
if (start == null || start >= this.length) start = this.length - 1;
for (int i = start; i >= 0; i--) {
if (test(this[i])) return i;
}
return -1;
}lastWhere() inherited
E lastWhere(bool Function(E element) test, {(E Function())? orElse})The last element that satisfies the given predicate test.
An iterable that can access its elements directly may check its elements in any order (for example a list starts by checking the last element and then moves towards the start of the list). The default implementation iterates elements in iteration order, checks test(element) for each, and finally returns that last one that matched.
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
var result = numbers.lastWhere((element) => element < 5); // 3
result = numbers.lastWhere((element) => element > 5); // 7
result = numbers.lastWhere((element) => element > 10,
orElse: () => -1); // -1If no element satisfies test, the result of invoking the orElse function is returned. If orElse is omitted, it defaults to throwing a StateError.
Inherited from ListBase.
Implementation
dart
E lastWhere(bool test(E element), {E Function()? orElse}) {
int length = this.length;
for (int i = length - 1; i >= 0; i--) {
E element = this[i];
if (test(element)) return element;
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
if (orElse != null) return orElse();
throw IterableElementError.noElement();
}map() inherited
Iterable<T> map<T>(T Function(E element) f)The current elements of this iterable modified by toElement.
Returns a new lazy Iterable with elements that are created by calling toElement on each element of this Iterable in iteration order.
The returned iterable is lazy, so it won't iterate the elements of this iterable until it is itself iterated, and then it will apply toElement to create one element at a time. The converted elements are not cached. Iterating multiple times over the returned Iterable will invoke the supplied toElement function once per element for on each iteration.
Methods on the returned iterable are allowed to omit calling toElement on any element where the result isn't needed. For example, elementAt may call toElement only once.
Equivalent to:
dart
Iterable<T> map<T>(T toElement(E e)) sync* {
for (var value in this) {
yield toElement(value);
}
}Example:
dart
var products = jsonDecode('''
[
{"name": "Screwdriver", "price": 42.00},
{"name": "Wingnut", "price": 0.50}
]
''');
var values = products.map((product) => product['price'] as double);
var totalPrice = values.fold(0.0, (a, b) => a + b); // 42.5.Inherited from ListBase.
Implementation
dart
Iterable<T> map<T>(T f(E element)) => MappedListIterable<E, T>(this, f);noSuchMethod() inherited
dynamic noSuchMethod(Invocation invocation)Invoked when a nonexistent method or property is accessed.
A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:
dart
dynamic object = 1;
object.add(42); // Statically allowed, run-time errorThis invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).
Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.
A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:
dart
class MockList<T> implements List<T> {
noSuchMethod(Invocation invocation) {
log(invocation);
super.noSuchMethod(invocation); // Will throw.
}
}
void main() {
MockList().add(42);
}This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.
If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.
The default behavior is to throw a NoSuchMethodError.
Inherited from Object.
Implementation
dart
@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);reduce() inherited
E reduce(E Function(E previousValue, E element) combine)Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
The iterable must have at least one element. If it has only one element, that element is returned.
Otherwise this method starts with the first element from the iterator, and then combines it with the remaining elements in iteration order, as if by:
dart
E value = iterable.first;
iterable.skip(1).forEach((element) {
value = combine(value, element);
});
return value;Example of calculating the sum of an iterable:
dart
final numbers = <double>[10, 2, 5, 0.5];
final result = numbers.reduce((value, element) => value + element);
print(result); // 17.5Consider using fold if the iterable can be empty.
Inherited from ListBase.
Implementation
dart
E reduce(E combine(E previousValue, E element)) {
int length = this.length;
if (length == 0) throw IterableElementError.noElement();
E value = this[0];
for (int i = 1; i < length; i++) {
value = combine(value, this[i]);
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
return value;
}remove() inherited
This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
bool remove(Object? element) {
throw UnsupportedError("Cannot remove from an unmodifiable list");
}removeAt() inherited
E removeAt(int index)This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
E removeAt(int index) {
throw UnsupportedError("Cannot remove from an unmodifiable list");
}removeLast() inherited
E removeLast()This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
E removeLast() {
throw UnsupportedError("Cannot remove from an unmodifiable list");
}removeRange() inherited
This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void removeRange(int start, int end) {
throw UnsupportedError("Cannot remove from an unmodifiable list");
}removeWhere() inherited
void removeWhere(bool Function(E element) test)This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void removeWhere(bool test(E element)) {
throw UnsupportedError("Cannot remove from an unmodifiable list");
}replaceRange() inherited
This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void replaceRange(int start, int end, Iterable<E> iterable) {
throw UnsupportedError("Cannot remove from an unmodifiable list");
}retainWhere() inherited
void retainWhere(bool Function(E element) test)This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void retainWhere(bool test(E element)) {
throw UnsupportedError("Cannot remove from an unmodifiable list");
}setAll() inherited
This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void setAll(int at, Iterable<E> iterable) {
throw UnsupportedError("Cannot modify an unmodifiable list");
}setRange() inherited
This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void setRange(int start, int end, Iterable<E> iterable, [int skipCount = 0]) {
throw UnsupportedError("Cannot modify an unmodifiable list");
}shuffle() inherited
void shuffle([Random? random])This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void shuffle([Random? random]) {
throw UnsupportedError("Cannot modify an unmodifiable list");
}singleWhere() inherited
E singleWhere(bool Function(E element) test, {(E Function())? orElse})The single element that satisfies test.
Checks elements to see if test(element) returns true. If exactly one element satisfies test, that element is returned. If more than one matching element is found, throws StateError. If no matching element is found, returns the result of orElse. If orElse is omitted, it defaults to throwing a StateError.
Example:
dart
final numbers = <int>[2, 2, 10];
var result = numbers.singleWhere((element) => element > 5); // 10When no matching element is found, the result of calling orElse is returned instead.
dart
result = numbers.singleWhere((element) => element == 1,
orElse: () => -1); // -1There must not be more than one matching element.
dart
result = numbers.singleWhere((element) => element == 2); // Throws Error.Inherited from ListBase.
Implementation
dart
E singleWhere(bool test(E element), {E Function()? orElse}) {
int length = this.length;
late E match;
bool matchFound = false;
for (int i = 0; i < length; i++) {
E element = this[i];
if (test(element)) {
if (matchFound) {
throw IterableElementError.tooMany();
}
matchFound = true;
match = element;
}
if (length != this.length) {
throw ConcurrentModificationError(this);
}
}
if (matchFound) return match;
if (orElse != null) return orElse();
throw IterableElementError.noElement();
}skip() inherited
Creates an Iterable that provides all but the first count elements.
When the returned iterable is iterated, it starts iterating over this, first skipping past the initial count elements. If this has fewer than count elements, then the resulting Iterable is empty. After that, the remaining elements are iterated in the same order as in this iterable.
Some iterables may be able to find later elements without first iterating through earlier elements, for example when iterating a List. Such iterables are allowed to ignore the initial skipped elements.
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
final result = numbers.skip(4); // (6, 7)
final skipAll = numbers.skip(100); // () - no elements.The count must not be negative.
Inherited from ListBase.
Implementation
dart
Iterable<E> skip(int count) => SubListIterable<E>(this, count, null);skipWhile() inherited
Creates an Iterable that skips leading elements while test is satisfied.
The filtering happens lazily. Every new Iterator of the returned iterable iterates over all elements of this.
The returned iterable provides elements by iterating this iterable, but skipping over all initial elements where test(element) returns true. If all elements satisfy test the resulting iterable is empty, otherwise it iterates the remaining elements in their original order, starting with the first element for which test(element) returns false.
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
var result = numbers.skipWhile((x) => x < 5); // (5, 6, 7)
result = numbers.skipWhile((x) => x != 3); // (3, 5, 6, 7)
result = numbers.skipWhile((x) => x != 4); // ()
result = numbers.skipWhile((x) => x.isOdd); // (2, 3, 5, 6, 7)Inherited from ListBase.
Implementation
dart
Iterable<E> skipWhile(bool test(E element)) {
return SkipWhileIterable<E>(this, test);
}sort() inherited
void sort([(int Function(E a, E b))? compare])This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void sort([Comparator<E>? compare]) {
throw UnsupportedError("Cannot modify an unmodifiable list");
}sublist() inherited
Returns a new list containing the elements between start and end.
The new list is a List<E> containing the elements of this list at positions greater than or equal to start and less than end in the same order as they occur in this list.
dart
final colors = <String>['red', 'green', 'blue', 'orange', 'pink'];
print(colors.sublist(1, 3)); // [green, blue]If end is omitted, it defaults to the length of this list.
dart
final colors = <String>['red', 'green', 'blue', 'orange', 'pink'];
print(colors.sublist(3)); // [orange, pink]The start and end positions must satisfy the relations 0 ≤ start ≤ end ≤ length. If end is equal to start, then the returned list is empty.
Inherited from ListBase.
Implementation
dart
List<E> sublist(int start, [int? end]) {
int listLength = this.length;
end ??= listLength;
RangeError.checkValidRange(start, end, listLength);
return List.of(getRange(start, end));
}take() inherited
Creates a lazy iterable of the count first elements of this iterable.
The returned Iterable may contain fewer than count elements, if this contains fewer than count elements.
The elements can be computed by stepping through iterator until count elements have been seen.
The count must not be negative.
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
final result = numbers.take(4); // (1, 2, 3, 5)
final takeAll = numbers.take(100); // (1, 2, 3, 5, 6, 7)Inherited from ListBase.
Implementation
dart
Iterable<E> take(int count) =>
SubListIterable<E>(this, 0, checkNotNullable(count, "count"));takeWhile() inherited
Creates a lazy iterable of the leading elements satisfying test.
The filtering happens lazily. Every new iterator of the returned iterable starts iterating over the elements of this.
The elements can be computed by stepping through iterator until an element is found where test(element) is false. At that point, the returned iterable stops (its moveNext() returns false).
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
var result = numbers.takeWhile((x) => x < 5); // (1, 2, 3)
result = numbers.takeWhile((x) => x != 3); // (1, 2)
result = numbers.takeWhile((x) => x != 4); // (1, 2, 3, 5, 6, 7)
result = numbers.takeWhile((x) => x.isOdd); // (1)Inherited from ListBase.
Implementation
dart
Iterable<E> takeWhile(bool test(E element)) {
return TakeWhileIterable<E>(this, test);
}toList() inherited
Creates a List containing the elements of this Iterable.
The elements are in iteration order. The list is fixed-length if growable is false.
Example:
dart
final planets = <int, String>{1: 'Mercury', 2: 'Venus', 3: 'Mars'};
final keysList = planets.keys.toList(growable: false); // [1, 2, 3]
final valuesList =
planets.values.toList(growable: false); // [Mercury, Venus, Mars]Inherited from ListBase.
Implementation
dart
List<E> toList({bool growable = true}) {
if (this.isEmpty) return List<E>.empty(growable: growable);
var first = this[0];
var result = List<E>.filled(this.length, first, growable: growable);
for (int i = 1; i < this.length; i++) {
result[i] = this[i];
}
return result;
}toSet() inherited
Set<E> toSet()Creates a Set containing the same elements as this iterable.
The set may contain fewer elements than the iterable, if the iterable contains an element more than once, or it contains one or more elements that are equal. The order of the elements in the set is not guaranteed to be the same as for the iterable.
Example:
dart
final planets = <int, String>{1: 'Mercury', 2: 'Venus', 3: 'Mars'};
final valueSet = planets.values.toSet(); // {Mercury, Venus, Mars}Inherited from ListBase.
Implementation
dart
Set<E> toSet() {
Set<E> result = Set<E>();
for (int i = 0; i < length; i++) {
result.add(this[i]);
}
return result;
}toString() inherited
String toString()A string representation of this object.
Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.
Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.
Inherited from ListBase.
Implementation
dart
String toString() => listToString(this);where() inherited
Creates a new lazy Iterable with all elements that satisfy the predicate test.
The matching elements have the same order in the returned iterable as they have in iterator.
This method returns a view of the mapped elements. As long as the returned Iterable is not iterated over, the supplied function test will not be invoked. Iterating will not cache results, and thus iterating multiple times over the returned Iterable may invoke the supplied function test multiple times on the same element.
Example:
dart
final numbers = <int>[1, 2, 3, 5, 6, 7];
var result = numbers.where((x) => x < 5); // (1, 2, 3)
result = numbers.where((x) => x > 5); // (6, 7)
result = numbers.where((x) => x.isEven); // (2, 6)Inherited from ListBase.
Implementation
dart
Iterable<E> where(bool test(E element)) => WhereIterable<E>(this, test);whereType() inherited
Iterable<T> whereType<T>()Creates a new lazy Iterable with all elements that have type T.
The matching elements have the same order in the returned iterable as they have in iterator.
This method returns a view of the mapped elements. Iterating will not cache results, and thus iterating multiple times over the returned Iterable may yield different results, if the underlying elements change between iterations.
Inherited from ListBase.
Implementation
dart
Iterable<T> whereType<T>() => WhereTypeIterable<T>(this);Operators
operator +() inherited
Returns the concatenation of this list and other.
Returns a new list containing the elements of this list followed by the elements of other.
The default behavior is to return a normal growable list. Some list types may choose to return a list of the same type as themselves (see Uint8List.+);
Inherited from ListBase.
Implementation
dart
List<E> operator +(List<E> other) => [...this, ...other];operator ==() inherited
The equality operator.
The default behavior for all Objects is to return true if and only if this object and other are the same object.
Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:
Total: It must return a boolean for all arguments. It should never throw.
Reflexive: For all objects
o,o == omust be true.Symmetric: For all objects
o1ando2,o1 == o2ando2 == o1must either both be true, or both be false.Transitive: For all objects
o1,o2, ando3, ifo1 == o2ando2 == o3are true, theno1 == o3must be true.
The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.
If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.
Inherited from Object.
Implementation
dart
external bool operator ==(Object other);operator override
E operator [](int index)The object at the given index in the list.
The index must be a valid index of this list, which means that index must be non-negative and less than length.
Implementation
dart
E operator [](int index) => _source.elementAt(index);operator []=() inherited
void operator []=(int index, E value)This operation is not supported by an unmodifiable list.
Inherited from UnmodifiableListMixin.
Implementation
dart
void operator []=(int index, E value) {
throw UnsupportedError("Cannot modify an unmodifiable list");
}