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 * A collection of objects in which each object can occur only once. | 8 * A collection of objects in which each object can occur only once. |
9 * | 9 * |
10 * That is, for each object of the element type, the object is either considered | 10 * That is, for each object of the element type, the object is either considered |
(...skipping 13 matching lines...) Expand all Loading... |
24 * uspecified, | 24 * uspecified, |
25 * * [LinkedHashSet] iterates in the insertion order of its elements, and | 25 * * [LinkedHashSet] iterates in the insertion order of its elements, and |
26 * * a sorted set like [SplayTreeSet] iterates the elements in sorted order. | 26 * * a sorted set like [SplayTreeSet] iterates the elements in sorted order. |
27 * | 27 * |
28 * It is generally not allowed to modify the set (add or remove elements) while | 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 | 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 | 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, | 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]. | 32 * such as the ones returned by methods like [where] and [map]. |
33 */ | 33 */ |
34 abstract class Set<E> extends IterableBase<E> implements EfficientLength { | 34 abstract class Set<E> extends Iterable<E> implements EfficientLength { |
35 /** | 35 /** |
36 * Creates an empty [Set]. | 36 * Creates an empty [Set]. |
37 * | 37 * |
38 * The created [Set] is a plain [LinkedHashSet]. | 38 * The created [Set] is a plain [LinkedHashSet]. |
39 * As such, it considers elements that are equal (using [==]) to be | 39 * As such, it considers elements that are equal (using [==]) to be |
40 * indistinguishable, and requires them to have a compatible | 40 * indistinguishable, and requires them to have a compatible |
41 * [Object.hashCode] implementation. | 41 * [Object.hashCode] implementation. |
42 * | 42 * |
43 * The set is equivalent to one created by `new LinkedHashSet<E>()`. | 43 * The set is equivalent to one created by `new LinkedHashSet<E>()`. |
44 */ | 44 */ |
(...skipping 36 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
81 * but must be consistent between changes to the set. | 81 * but must be consistent between changes to the set. |
82 */ | 82 */ |
83 Iterator<E> get iterator; | 83 Iterator<E> get iterator; |
84 | 84 |
85 /** | 85 /** |
86 * Returns true if [value] is in the set. | 86 * Returns true if [value] is in the set. |
87 */ | 87 */ |
88 bool contains(Object value); | 88 bool contains(Object value); |
89 | 89 |
90 /** | 90 /** |
91 * Adds [value] into the set. Returns `true` if [value] was added to the set. | 91 * Adds [value] to the set. |
92 * | 92 * |
93 * If [value] already exists, the set is not changed and `false` is returned. | 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)); |
94 */ | 110 */ |
95 bool add(E value); | 111 bool add(E value); |
96 | 112 |
97 /** | 113 /** |
98 * Adds all [elements] to this Set. | 114 * Adds all [elements] to this Set. |
99 * | 115 * |
100 * Equivalent to adding each element in [elements] using [add], | 116 * Equivalent to adding each element in [elements] using [add], |
101 * but some collections may be able to optimize it. | 117 * but some collections may be able to optimize it. |
102 */ | 118 */ |
103 void addAll(Iterable<E> elements); | 119 void addAll(Iterable<E> elements); |
(...skipping 75 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
179 /* Creates a [Set] with the same elements and behavior as this `Set`. | 195 /* Creates a [Set] with the same elements and behavior as this `Set`. |
180 * | 196 * |
181 * The returned set behaves the same as this set | 197 * The returned set behaves the same as this set |
182 * with regard to adding and removing elements. | 198 * with regard to adding and removing elements. |
183 * It initially contains the same elements. | 199 * It initially contains the same elements. |
184 * If this set specifies an ordering of the elements, | 200 * If this set specifies an ordering of the elements, |
185 * the returned set will have the same order. | 201 * the returned set will have the same order. |
186 */ | 202 */ |
187 Set<E> toSet(); | 203 Set<E> toSet(); |
188 } | 204 } |
OLD | NEW |