Add methods to Collection.

sdk/lib/core/collection.dart

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 Scheme-like linked list not be a Collection?

[Lasse Reichstein Nielsen, 2013/01/18 11:41:48]

Reasonable. We can write on List and Set that they are efficient.

+
+  /**
+   * 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 once, only one occurrence is
removed. The collection decides which one it removes.

+   * 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):] is not equal to true.

[Lasse Reichstein Nielsen, 2013/01/18 11:41:48]

Double negative is not an improvement, and it says the same thing.

+   */
+  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.

 }