OLD | NEW |
| (Empty) |
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 | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 part of dart.core; | |
6 | |
7 /** | |
8 * A collection of objects in which each object can occur only once. | |
9 * | |
10 * That is, for each object of the element type, the object is either considered | |
11 * to be in the set, or to _not_ be in the set. | |
12 * | |
13 * Set implementations may consider some elements indistinguishable. These | |
14 * elements are treated as being the same for any operation on the set. | |
15 * | |
16 * The default [Set] implementation, [LinkedHashSet], considers objects | |
17 * indistinguishable if they are equal with regard to | |
18 * operator [Object.==]. | |
19 * | |
20 * Iterating over elements of a set may be either unordered | |
21 * or ordered in some way. Examples: | |
22 * | |
23 * * A [HashSet] is unordered, which means that its iteration order is | |
24 * uspecified, | |
25 * * [LinkedHashSet] iterates in the insertion order of its elements, and | |
26 * * a sorted set like [SplayTreeSet] iterates the elements in sorted order. | |
27 * | |
28 * It is generally not allowed to modify the set (add or remove elements) while | |
29 * an operation on the set is being performed, for example during a call to | |
30 * [forEach] or [containsAll]. Nor is it allowed to modify the set while | |
31 * iterating either the set itself or any [Iterable] that is backed by the set, | |
32 * such as the ones returned by methods like [where] and [map]. | |
33 */ | |
34 abstract class Set<E> extends Iterable<E> implements EfficientLength { | |
35 /** | |
36 * Creates an empty [Set]. | |
37 * | |
38 * The created [Set] is a plain [LinkedHashSet]. | |
39 * As such, it considers elements that are equal (using [==]) to be | |
40 * indistinguishable, and requires them to have a compatible | |
41 * [Object.hashCode] implementation. | |
42 * | |
43 * The set is equivalent to one created by `new LinkedHashSet<E>()`. | |
44 */ | |
45 factory Set() = LinkedHashSet<E>; | |
46 | |
47 /** | |
48 * Creates an empty identity [Set]. | |
49 * | |
50 * The created [Set] is a [LinkedHashSet] that uses identity as equality | |
51 * relation. | |
52 * | |
53 * The set is equivalent to one created by `new LinkedHashSet<E>.identity()`. | |
54 */ | |
55 factory Set.identity() = LinkedHashSet<E>.identity; | |
56 | |
57 /** | |
58 * Creates a [Set] that contains all [elements]. | |
59 * | |
60 * All the [elements] should be assignable to [E]. | |
61 * The `elements` iterable itself can have any type, | |
62 * so this constructor can be used to down-cast a `Set`, for example as: | |
63 * | |
64 * Set<SuperType> superSet = ...; | |
65 * Set<SubType> subSet = | |
66 * new Set<SubType>.from(superSet.where((e) => e is SubType)); | |
67 * | |
68 * The created [Set] is a [LinkedHashSet]. As such, it considers elements that | |
69 * are equal (using [==]) to be indistinguishable, and requires them to | |
70 * have a compatible [Object.hashCode] implementation. | |
71 * | |
72 * The set is equivalent to one created by | |
73 * `new LinkedHashSet<E>.from(elements)`. | |
74 */ | |
75 factory Set.from(Iterable<E> elements) = LinkedHashSet<E>.from; | |
76 | |
77 /** | |
78 * Provides an iterator that iterates over the elements of this set. | |
79 * | |
80 * The order of iteration is defined by the individual `Set` implementation, | |
81 * but must be consistent between changes to the set. | |
82 */ | |
83 Iterator<E> get iterator; | |
84 | |
85 /** | |
86 * Returns true if [value] is in the set. | |
87 */ | |
88 bool contains(Object value); | |
89 | |
90 /** | |
91 * Adds [value] to the set. | |
92 * | |
93 * Returns `true` if [value] (or an equal value) was not yet in the set. | |
94 * Otherwise returns `false` and the set is not changed. | |
95 * | |
96 * Example: | |
97 * | |
98 * var set = new Set(); | |
99 * var time1 = new DateTime.fromMillisecondsSinceEpoch(0); | |
100 * var time2 = new DateTime.fromMillisecondsSinceEpoch(0); | |
101 * // time1 and time2 are equal, but not identical. | |
102 * Expect.isTrue(time1 == time2); | |
103 * Expect.isFalse(identical(time1, time2)); | |
104 * set.add(time1); // => true. | |
105 * // A value equal to time2 exists already in the set, and the call to | |
106 * // add doesn't change the set. | |
107 * set.add(time2); // => false. | |
108 * Expect.isTrue(set.length == 1); | |
109 * Expect.isTrue(identical(time1, set.first)); | |
110 */ | |
111 bool add(E value); | |
112 | |
113 /** | |
114 * Adds all [elements] to this Set. | |
115 * | |
116 * Equivalent to adding each element in [elements] using [add], | |
117 * but some collections may be able to optimize it. | |
118 */ | |
119 void addAll(Iterable<E> elements); | |
120 | |
121 /** | |
122 * Removes [value] from the set. Returns true if [value] was | |
123 * in the set. Returns false otherwise. The method has no effect | |
124 * if [value] value was not in the set. | |
125 */ | |
126 bool remove(Object value); | |
127 | |
128 /** | |
129 * If an object equal to [object] is in the set, return it. | |
130 * | |
131 * Checks if there is an object in the set that is equal to [object]. | |
132 * If so, that object is returned, otherwise returns null. | |
133 */ | |
134 E lookup(Object object); | |
135 | |
136 /** | |
137 * Removes each element of [elements] from this set. | |
138 */ | |
139 void removeAll(Iterable<Object> elements); | |
140 | |
141 /** | |
142 * Removes all elements of this set that are not elements in [elements]. | |
143 * | |
144 * Checks for each element of [elements] whether there is an element in this | |
145 * set that is equal to it (according to `this.contains`), and if so, the | |
146 * equal element in this set is retained, and elements that are not equal | |
147 * to any element in `elements` are removed. | |
148 */ | |
149 void retainAll(Iterable<Object> elements); | |
150 | |
151 /** | |
152 * Removes all elements of this set that satisfy [test]. | |
153 */ | |
154 void removeWhere(bool test(E element)); | |
155 | |
156 /** | |
157 * Removes all elements of this set that fail to satisfy [test]. | |
158 */ | |
159 void retainWhere(bool test(E element)); | |
160 | |
161 /** | |
162 * Returns whether this Set contains all the elements of [other]. | |
163 */ | |
164 bool containsAll(Iterable<Object> other); | |
165 | |
166 /** | |
167 * Returns a new set which is the intersection between this set and [other]. | |
168 * | |
169 * That is, the returned set contains all the elements of this [Set] that | |
170 * are also elements of [other] according to `other.contains`. | |
171 */ | |
172 Set<E> intersection(Set<Object> other); | |
173 | |
174 /** | |
175 * Returns a new set which contains all the elements of this set and [other]. | |
176 * | |
177 * That is, the returned set contains all the elements of this [Set] and | |
178 * all the elements of [other]. | |
179 */ | |
180 Set<E> union(Set<E> other); | |
181 | |
182 /** | |
183 * Returns a new set with the elements of this that are not in [other]. | |
184 * | |
185 * That is, the returned set contains all the elements of this [Set] that | |
186 * are not elements of [other] according to `other.contains`. | |
187 */ | |
188 Set<E> difference(Set<Object> other); | |
189 | |
190 /** | |
191 * Removes all elements in the set. | |
192 */ | |
193 void clear(); | |
194 | |
195 /* Creates a [Set] with the same elements and behavior as this `Set`. | |
196 * | |
197 * The returned set behaves the same as this set | |
198 * with regard to adding and removing elements. | |
199 * It initially contains the same elements. | |
200 * If this set specifies an ordering of the elements, | |
201 * the returned set will have the same order. | |
202 */ | |
203 Set<E> toSet(); | |
204 } | |
OLD | NEW |