OLD | NEW |
---|---|
1 // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.core; | 5 part of dart.core; |
6 | 6 |
7 /** | 7 /** |
8 * The common interface of all collections. | 8 * A collection of individual elements. |
9 * | 9 * |
10 * The [Collection] class contains a skeleton implementation of | 10 * A [Collection] contains some elements in a structure optimized |
11 * an iterator based collection. | 11 * for certain operations. Different collections are optimized for different |
12 * uses. | |
13 * | |
14 * A collection can be updated by adding or removing elements. | |
15 * | |
16 * Collections are [Iterable]. The order of iteration is defined by | |
17 * each type of collection. | |
12 */ | 18 */ |
13 abstract class Collection<E> extends Iterable<E> { | 19 abstract class Collection<E> extends Iterable<E> { |
14 const Collection(); | 20 const Collection(); |
21 | |
22 /** | |
23 * Provides the number of elements in this collection. | |
24 * | |
25 * On a collection, this operation should be efficient, which\ | |
26 * cannot be guaranteed for [Iterable]s in general. | |
27 */ | |
28 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
| |
29 | |
30 /** | |
31 * Adds an element to this collection. | |
32 * | |
33 * 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.
| |
34 * element. | |
35 */ | |
36 void add(E element); | |
37 | |
38 /** | |
39 * Adds all of [elements] to this collection. | |
40 * | |
41 * Equivalent to adding each element in [elements] using [add], | |
42 * but some collections may be able to optimize it. | |
43 */ | |
44 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.
| |
45 | |
46 /** | |
47 * Removes an instance of [element] from this collection. | |
48 * | |
49 * 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
| |
50 * contain the same element more than once (e.g., [List]). Which instance | |
51 * is removed is decided by the collection. | |
52 * | |
53 * Has no effect if the elements is not in this collection. | |
54 */ | |
55 void remove(Object element); | |
56 | |
57 /** | |
58 * Removes all of [elements] from this collection. | |
59 * | |
60 * Equivalent to calling [remove] once for each element in | |
61 * [elements], but may be faster for some collections. | |
62 */ | |
63 void removeAll(Iterable elements); | |
floitsch
2013/01/17 13:36:58
Provide default implementation.
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
| |
64 | |
65 /** | |
66 * Removes all elements of this collection that are not | |
67 * in [elements]. | |
68 * | |
69 * 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.
| |
70 * are in both this collection and in [elements]. | |
71 */ | |
72 void retainAll(Iterable elements); | |
floitsch
2013/01/17 13:36:58
Provide default implementation.
Lasse Reichstein Nielsen
2013/01/18 11:41:48
Done.
| |
73 | |
74 /** | |
75 * Removes all elements of this collection that satisfy [test]. | |
76 * | |
77 * An elements [:e:] satisfies [test] if [:test(e):] is true. | |
78 */ | |
79 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.
| |
80 | |
81 /** | |
82 * Removes all elements of this collection that fail to satisfy [test]. | |
83 * | |
84 * 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
| |
85 */ | |
86 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.
| |
15 } | 87 } |
OLD | NEW |