diff --git a/sdk/lib/core/list.dart b/sdk/lib/core/list.dart index dc0ccfab1be..af9f8950f23 100644 --- a/sdk/lib/core/list.dart +++ b/sdk/lib/core/list.dart @@ -5,72 +5,66 @@ part of dart.core; /** - * A [List] is an indexable collection with a length. + * An indexable collection of objects with a length. * - * A `List` implementation can choose not to support all methods - * of the `List` interface. + * Subclasses of this class implement different kinds of lists. + * The most common kinds of lists are: * - * The most common list types are: - * * Fixed length list. It is an error to use operations that can change - * the list's length. - * * Growable list. Full implementation of the interface. - * * Unmodifiable list. It is an error to use operations that can change - * the list's length, or that can change the values of the list. - * If an unmodifable list is backed by another modifiable data structure, - * the values read from it may still change over time. + * * Fixed-length list. + * An error occurs when attempting to use operations + * that can change the length of the list. * - * Example: + * * Growable list. Full implementation of the API defined in this class. + * + * The following code illustrates that some List implementations support + * only a subset of the API. * * var fixedLengthList = new List(5); - * fixedLengthList.length = 0; // throws. - * fixedLengthList.add(499); // throws + * fixedLengthList.length = 0; // Error. + * fixedLengthList.add(499); // Error. * fixedLengthList[0] = 87; + * * var growableList = [1, 2]; * growableList.length = 0; * growableList.add(499); * growableList[0] = 87; - * var unmodifiableList = const [1, 2]; - * unmodifiableList.length = 0; // throws. - * unmodifiableList.add(499); // throws - * unmodifiableList[0] = 87; // throws. * * Lists are [Iterable]. - * List iteration iterates over values in index order. - * Changing the values will not affect iteration, - * but changing the valid indices - - * that is, changing the list's length - - * between iteration steps - * will cause a [ConcurrentModificationError]. - * This means that only growable lists can throw [ConcurrentModificationError]. + * Iteration occurs over values in index order. + * Changing the values does not affect iteration, + * but changing the valid indices—that is, + * changing the list's length—between + * iteration steps + * causes a [ConcurrentModificationError]. + * This means that only growable lists can throw ConcurrentModificationError. * If the length changes temporarily * and is restored before continuing the iteration, - * the iterator will not detect it. + * the iterator does not detect it. */ abstract class List implements Iterable { /** - * Creates a list of the given [length]. + * Creates a list of the given _length_. * - * The list is a fixed-length list if [length] is provided, and an empty - * growable list if [length] is omitted. + * The created list is fixed-length if _length_ is provided. + * The list has length 0 and is growable if _length_ is omitted. * - * It is an error if [length] is not a non-negative integer. + * An error occurs if _length_ is negative. */ external factory List([int length]); /** - * Creates a fixed-length list of the given [length] where each entry - * contains [fill]. + * Creates a fixed-length list of the given _length_ + * and initializes the value at each position with [fill]. */ external factory List.filled(int length, E fill); /** - * Creates an list with the elements of [other]. + * Creates a list and initializes it using the contents of [other]. * - * The order in the list will be - * the order provided by the iterator of [other]. + * The [Iterator] of [other] provides the order of the objects. * - * The returned list is growable if [growable] is true, otherwise it's - * a fixed length list. + * This constructor returns a growable list if [growable] is true; + * otherwise, it returns a fixed-length list. */ factory List.from(Iterable other, { bool growable: true }) { List list = new List(); @@ -87,14 +81,14 @@ abstract class List implements Iterable { } /** - * Generate a `List` of values. + * Generates a list of values. * - * Creates a list with [length] positions - * and fills them by values created by calling [generator] - * for each index in the range `0` .. `[length] - 1` + * Creates a list with _length_ positions + * and fills it with values created by calling [generator] + * for each index in the range `0` .. `length - 1` * in increasing order. * - * The created list's length is fixed unless [growable] is true. + * The created list is fixed-length unless [growable] is true. */ factory List.generate(int length, E generator(int index), { bool growable: true }) { @@ -111,202 +105,202 @@ abstract class List implements Iterable { } /** - * Returns the element at the given [index] in the list or throws - * an [RangeError] if [index] is out of bounds. + * Returns the object at the given [index] in the list + * or throws a [RangeError] if [index] is out of bounds. */ E operator [](int index); /** - * Sets the entry at the given [index] in the list to [value]. - * - * Throws an [RangeError] if [index] is out of bounds. + * Sets the value at the given [index] in the list to [value] + * or throws a [RangeError] if [index] is out of bounds. */ void operator []=(int index, E value); /** - * Returns the number of elements in the list. + * Returns the number of objects in this list. * - * The valid indices for a list are 0 through `length - 1`. + * The valid indices for a list are `0` through `length - 1`. */ int get length; /** - * Changes the length of the list. If [newLength] is greater than + * Changes the length of this list. + * + * If [newLength] is greater than * the current [length], entries are initialized to [:null:]. * - * Throws an [UnsupportedError] if the list is not extendable. + * Throws an [UnsupportedError] if the list is fixed-length. */ void set length(int newLength); /** - * Adds [value] at the end of the list, extending the length by - * one. + * Adds [value] to the end of this list, + * extending the length by one. * - * Throws an [UnsupportedError] if the list is not extendable. + * Throws an [UnsupportedError] if the list is fixed-length. */ void add(E value); /** - * Appends all elements of the [iterable] to the end of this list. + * Appends all objects of [iterable] to the end of this list. * - * Extends the length of the list by the number of elements in [iterable]. - * Throws an [UnsupportedError] if this list is not extensible. + * Extends the length of the list by the number of objects in [iterable]. + * Throws an [UnsupportedError] if this list is fixed-length. */ void addAll(Iterable iterable); /** - * Returns an [Iterable] of the elements of this [List] in reverse order. + * Returns an [Iterable] of the objects in this list in reverse order. */ Iterable get reversed; /** - * Sorts the list according to the order specified by the [compare] function. + * Sorts this list according to the order specified by the [compare] function. * * The [compare] function must act as a [Comparator]. * - * The default [List] implementations use [Comparable.compare] if + * The default List implementations use [Comparable.compare] if * [compare] is omitted. */ void sort([int compare(E a, E b)]); /** - * Returns the first index of [element] in the list. + * Returns the first index of [element] in this list. * * Searches the list from index [start] to the length of the list. - * The first time an element [:e:] is encountered so that [:e == element:], - * the index of [:e:] is returned. + * The first time an object [:o:] is encountered so that [:o == element:], + * the index of [:o:] is returned. * Returns -1 if [element] is not found. */ int indexOf(E element, [int start = 0]); /** - * Returns the last index of [element] in the list. + * Returns the last index of [element] in this list. * - * Searches the list backwards from index [start] (inclusive) to 0. + * Searches the list backwards from index [start] to 0. * - * The first time an element [:e:] is encountered so that [:e == element:], - * the index of [:e:] is returned. + * The first time an object [:o:] is encountered so that [:o == element:], + * the index of [:o:] is returned. * - * If start is not provided, it defaults to [:this.length - 1:]. + * If [start] is not provided, it defaults to [:this.length - 1:]. * * Returns -1 if [element] is not found. */ int lastIndexOf(E element, [int start]); /** - * Removes all elements in the list. + * Removes all objects from this list; + * the length of the list becomes zero. * - * The length of the list becomes zero. - * - * Throws an [UnsupportedError], and retains all elements, if the - * length of the list cannot be changed. + * Throws an [UnsupportedError], and retains all objects, if this + * is a fixed-length list. */ void clear(); /** - * Inserts the element at position [index] in the list. + * Inserts the object at position [index] in this list. * - * This increases the length of the list by one and shifts all elements + * This increases the length of the list by one and shifts all objects * at or after the index towards the end of the list. * - * It is an error if the [index] does not point inside the list or at the - * position after the last element. + * An error occurs if the [index] is less than 0 or greater than length. + * An [UnsupportedError] occurs if the list is fixed-length. */ void insert(int index, E element); /** - * Inserts all elements of [iterable] at position [index] in the list. + * Inserts all objects of [iterable] at position [index] in this list. * * This increases the length of the list by the length of [iterable] and - * shifts all later elements towards the end of the list. + * shifts all later objects towards the end of the list. * - * It is an error if the [index] does not point inside the list or at the - * position after the last element. + * An error occurs if the [index] is less than 0 or greater than length. + * An [UnsupportedError] occurs if the list is fixed-length. */ void insertAll(int index, Iterable iterable); /** - * Overwrites elements of `this` with the elemenst of [iterable] starting - * at position [index] in the list. + * Overwrites objects of `this` with the objects of [iterable], starting + * at position [index] in this list. * * This operation does not increase the length of `this`. * - * It is an error if the [index] does not point inside the list or at the - * position after the last element. - * - * It is an error if the [iterable] is longer than [length] - [index]. + * An error occurs if the [index] is less than 0 or greater than length. + * An error occurs if the [iterable] is longer than [length] - [index]. */ void setAll(int index, Iterable iterable); /** - * Removes [value] from the list. Returns true if [value] was - * in the list. Returns false otherwise. The method has no effect - * if [value] value was not in the list. + * Removes [value] from this list. + * + * Returns true if [value] was in the list. + * Returns false otherwise. + * The method has no effect if [value] was not in the list. + * + * An [UnsupportedError] occurs if the list is fixed-length. */ bool remove(Object value); /** - * Removes the element at position [index] from the list. + * Removes the object at position [index] from this list. * - * This reduces the length of `this` by one and moves all later elements + * This method reduces the length of `this` by one and moves all later objects * down by one position. * - * Returns the removed element. + * Returns the removed object. * - * Throws an [ArgumentError] if [index] is not an [int]. - * - * Throws an [RangeError] if the [index] does not point inside - * the list. - * - * Throws an [UnsupportedError], and doesn't remove the element, - * if the length of `this` cannot be changed. + * * Throws an [ArgumentError] if [index] is not an [int]. + * * Throws a [RangeError] if the [index] is out of range for this list. + * * Throws an [UnsupportedError], and doesn't remove the object, + * if this is a fixed-length list. */ E removeAt(int index); /** - * Pops and returns the last element of the list. - * Throws a [UnsupportedError] if the length of the - * list cannot be changed. + * Pops and returns the last object in this list. + * + * Throws an [UnsupportedError] if this is a fixed-length list. */ E removeLast(); /** - * Removes all elements of this list that satisfy [test]. + * Removes all objects from this list that satisfy [test]. * - * An elements [:e:] satisfies [test] if [:test(e):] is true. + * An object [:o:] satisfies [test] if [:test(o):] is true. + * + * Throws an [UnsupportedError] if this is a fixed-length list. */ void removeWhere(bool test(E element)); /** - * Removes all elements of this list that fail to satisfy [test]. + * Removes all objects from this list that fail to satisfy [test]. * - * An elements [:e:] satisfies [test] if [:test(e):] is true. + * An object [:o:] satisfies [test] if [:test(o):] is true. + * + * Throws an [UnsupportedError] if this is a fixed-length list. */ void retainWhere(bool test(E element)); /** - * Returns a new list containing the elements from [start] to [end]. - * - * The result contains elements of this list with indices greater than or - * equal to [start] and less than [end]. + * Returns a new list containing the objects + * from [start] inclusive to [end] exclusive. * * If [end] is omitted, the [length] of `this` is used. * - * It is an error if [start] is outside the range `0` .. `[length]` or if - * [end] is outside the range `[start]` .. `[length]`. + * An error occurs if [start] is outside the range `0` .. `length` or if + * [end] is outside the range `start` .. `length`. */ List sublist(int start, [int end]); /** - * Returns an [Iterable] that iterates over the elements in the range - * [start] to [end] exclusive. The result of this function - * is backed by `this`. + * Returns an [Iterable] that iterates over the objects in the range + * [start] inclusive to [end] exclusive. * - * It is an error if [end] is before [start]. + * An error occurs if [end] is before [start]. * - * It is an error if the [start] and [end] are not valid ranges at the time - * of the call to this method. The returned [Iterable] behaves similar to - * `skip(start).take(end - start)`. That is, it will not throw exceptions + * An error occurs if the [start] and [end] are not valid ranges at the time + * of the call to this method. The returned [Iterable] behaves like + * `skip(start).take(end - start)`. That is, it does not throw exceptions * if `this` changes size. * * Example: @@ -320,17 +314,15 @@ abstract class List implements Iterable { Iterable getRange(int start, int end); /** - * Copies the elements of [iterable], skipping the [skipCount] first elements, - * into the range [start] to [end] exclusive of `this`. + * Copies the objects of [iterable], skipping [skipCount] objects first, + * into the range [start] inclusive to [end] exclusive of `this`. * * If [start] equals [end] and [start]..[end] represents a legal range, this * method has no effect. * - * It is an error if [start]..[end] is not a valid range pointing into the - * `this`. - * - * It is an error if the [iterable] does not have enough elements after - * skipping [skipCount] elements. + * An error occurs if [start]..[end] is not a valid range for `this`. + * An error occurs if the [iterable] does not have enough objects after + * skipping [skipCount] objects. * * Example: * @@ -342,28 +334,26 @@ abstract class List implements Iterable { void setRange(int start, int end, Iterable iterable, [int skipCount = 0]); /** - * Removes the elements in the range [start] to [end] exclusive. + * Removes the objects in the range [start] inclusive to [end] exclusive. * - * It is an error if [start]..[end] is not a valid range pointing into the - * `this`. + * An error occurs if [start]..[end] is not a valid range for `this`. + * Throws an [UnsupportedError] if this is a fixed-length list. */ void removeRange(int start, int end); /** - * Sets the elements in the range [start] to [end] exclusive to the given - * [fillValue]. + * Sets the objects in the range [start] inclusive to [end] exclusive + * to the given [fillValue]. * - * It is an error if [start]..[end] is not a valid range pointing into the - * `this`. + * An error occurs if [start]..[end] is not a valid range for `this`. */ void fillRange(int start, int end, [E fillValue]); /** - * Removes the elements in the range [start] to [end] exclusive and replaces - * them with the contents of the [iterable]. + * Removes the objects in the range [start] inclusive to [end] exclusive + * and replaces them with the contents of the [iterable]. * - * It is an error if [start]..[end] is not a valid range pointing into the - * `this`. + * An error occurs if [start]..[end] is not a valid range for `this`. * * Example: * @@ -376,8 +366,8 @@ abstract class List implements Iterable { /** * Returns an unmodifiable [Map] view of `this`. * - * It has the indices of this list as keys, and the corresponding elements - * as values. The [Map.keys] [Iterable] will iterate the indices 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. */ Map asMap();