Index: sdk/lib/core/collection.dart |
diff --git a/sdk/lib/core/collection.dart b/sdk/lib/core/collection.dart |
index 23b08e6b4b008e89eb954a2ff696923b0fdb1f34..b24940dfd1b317ae3faf6332a29121644f3ab7af 100644 |
--- a/sdk/lib/core/collection.dart |
+++ b/sdk/lib/core/collection.dart |
@@ -5,11 +5,83 @@ |
part of dart.core; |
/** |
- * The common interface of all collections. |
+ * A collection of individual elements. |
* |
- * The [Collection] class contains a skeleton implementation of |
- * an iterator based collection. |
+ * A [Collection] contains some elements in a structure optimized |
+ * for certain operations. Different collections are optimized for different |
+ * uses. |
+ * |
+ * A collection can be updated by adding or removing elements. |
+ * |
+ * Collections are [Iterable]. The order of iteration is defined by |
+ * each type of collection. |
*/ |
abstract class Collection<E> extends Iterable<E> { |
const Collection(); |
+ |
+ /** |
+ * Provides the number of elements in this collection. |
+ * |
+ * On a collection, this operation should be efficient, which\ |
+ * cannot be guaranteed for [Iterable]s in general. |
+ */ |
+ int get length; |
floitsch
2013/01/17 13:36:58
I would remove this line.
For example: should a S
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Reasonable. We can write on List and Set that they
|
+ |
+ /** |
+ * Adds an element to this collection. |
+ * |
+ * After this, the [contains] method should return true for that |
floitsch
2013/01/17 13:36:58
I would remove this line. Seems obvious.
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
|
+ * element. |
+ */ |
+ void add(E element); |
+ |
+ /** |
+ * Adds all of [elements] to this collection. |
+ * |
+ * Equivalent to adding each element in [elements] using [add], |
+ * but some collections may be able to optimize it. |
+ */ |
+ void addAll(Iterable<E> elements); |
floitsch
2013/01/17 13:36:58
Provide default implementation.
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
|
+ |
+ /** |
+ * Removes an instance of [element] from this collection. |
+ * |
+ * This removes only one instance of the element for collections that can |
floitsch
2013/01/17 13:36:58
If the collection contains the element more than o
|
+ * contain the same element more than once (e.g., [List]). Which instance |
+ * is removed is decided by the collection. |
+ * |
+ * Has no effect if the elements is not in this collection. |
+ */ |
+ void remove(Object element); |
+ |
+ /** |
+ * Removes all of [elements] from this collection. |
+ * |
+ * Equivalent to calling [remove] once for each element in |
+ * [elements], but may be faster for some collections. |
+ */ |
+ void removeAll(Iterable elements); |
floitsch
2013/01/17 13:36:58
Provide default implementation.
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
|
+ |
+ /** |
+ * Removes all elements of this collection that are not |
+ * in [elements]. |
+ * |
+ * Afterwards this collection should contain only elements that |
floitsch
2013/01/17 13:36:58
Seems obvious.
Maybe mention "intersection" ?
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
|
+ * are in both this collection and in [elements]. |
+ */ |
+ void retainAll(Iterable elements); |
floitsch
2013/01/17 13:36:58
Provide default implementation.
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
|
+ |
+ /** |
+ * Removes all elements of this collection that satisfy [test]. |
+ * |
+ * An elements [:e:] satisfies [test] if [:test(e):] is true. |
+ */ |
+ void removeMatching(bool test(E element)); |
floitsch
2013/01/17 13:36:58
Provide default implementation.
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
|
+ |
+ /** |
+ * Removes all elements of this collection that fail to satisfy [test]. |
+ * |
+ * An elements [:e:] satisfies [test] if [:test(e):] is true. |
floitsch
2013/01/17 13:36:58
... [:e:] fails to satisfy [test] if [:test(e):] i
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Double negative is not an improvement, and it says
|
+ */ |
+ void retainMatching(bool test(E element)); |
floitsch
2013/01/17 13:36:58
Provide default implementation.
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
|
} |