Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(127)

Unified Diff: sdk/lib/core/collection.dart

Issue 11931034: Add methods to Collection. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Also on DoubleLinkedQueue. Created 7 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
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.
}

Powered by Google App Engine
This is Rietveld 408576698