dart-lang/sdk
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

editing doc comments for List class

Browse Source 
BUG=
R=kathyw@google.com

Review URL: https://codereview.chromium.org//23190016

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@26434 260f80e4-7a28-3924-810f-c04153c831b5
This commit is contained in:
mcampione@google.com
2013-08-21 15:46:59 +00:00
parent c8b370ab50
commit e1f7ca4e40
1 changed files with 130 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files
sdk/lib/core/list.dart
+130 -140
View File
@@ -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<E> implements Iterable<E> {
/**
* 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<E> list = new List<E>();
@@ -87,14 +81,14 @@ abstract class List<E> implements Iterable<E> {
}
/**
* 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<E> implements Iterable<E> {
}
/**
* 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<E> 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<E> 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<E> 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<E> 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<E> 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<E> implements Iterable<E> {
Iterable<E> 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<E> implements Iterable<E> {
void setRange(int start, int end, Iterable<E> 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<E> implements Iterable<E> {
/**
* 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<int, E> asMap();