| 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 IterableBase<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 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] into the set. Returns `true` if [value] was added to the set. | |
| 92 * | |
| 93 * If [value] already exists, the set is not changed and `false` is returned. | |
| 94 */ | |
| 95 bool add(E value); | |
| 96 | |
| 97 /** | |
| 98 * Adds all [elements] to this Set. | |
| 99 * | |
| 100 * Equivalent to adding each element in [elements] using [add], | |
| 101 * but some collections may be able to optimize it. | |
| 102 */ | |
| 103 void addAll(Iterable<E> elements); | |
| 104 | |
| 105 /** | |
| 106 * Removes [value] from the set. Returns true if [value] was | |
| 107 * in the set. Returns false otherwise. The method has no effect | |
| 108 * if [value] value was not in the set. | |
| 109 */ | |
| 110 bool remove(Object value); | |
| 111 | |
| 112 /** | |
| 113 * If an object equal to [object] is in the set, return it. | |
| 114 * | |
| 115 * Checks if there is an object in the set that is equal to [object]. | |
| 116 * If so, that object is returned, otherwise returns null. | |
| 117 */ | |
| 118 E lookup(Object object); | |
| 119 | |
| 120 /** | |
| 121 * Removes each element of [elements] from this set. | |
| 122 */ | |
| 123 void removeAll(Iterable<Object> elements); | |
| 124 | |
| 125 /** | |
| 126 * Removes all elements of this set that are not elements in [elements]. | |
| 127 * | |
| 128 * Checks for each element of [elements] whether there is an element in this | |
| 129 * set that is equal to it (according to `this.contains`), and if so, the | |
| 130 * equal element in this set is retained, and elements that are not equal | |
| 131 * to any element in `elements` are removed. | |
| 132 */ | |
| 133 void retainAll(Iterable<Object> elements); | |
| 134 | |
| 135 /** | |
| 136 * Removes all elements of this set that satisfy [test]. | |
| 137 */ | |
| 138 void removeWhere(bool test(E element)); | |
| 139 | |
| 140 /** | |
| 141 * Removes all elements of this set that fail to satisfy [test]. | |
| 142 */ | |
| 143 void retainWhere(bool test(E element)); | |
| 144 | |
| 145 /** | |
| 146 * Returns whether this Set contains all the elements of [other]. | |
| 147 */ | |
| 148 bool containsAll(Iterable<Object> other); | |
| 149 | |
| 150 /** | |
| 151 * Returns a new set which is the intersection between this set and [other]. | |
| 152 * | |
| 153 * That is, the returned set contains all the elements of this [Set] that | |
| 154 * are also elements of [other] according to `other.contains`. | |
| 155 */ | |
| 156 Set<E> intersection(Set<Object> other); | |
| 157 | |
| 158 /** | |
| 159 * Returns a new set which contains all the elements of this set and [other]. | |
| 160 * | |
| 161 * That is, the returned set contains all the elements of this [Set] and | |
| 162 * all the elements of [other]. | |
| 163 */ | |
| 164 Set<E> union(Set<E> other); | |
| 165 | |
| 166 /** | |
| 167 * Returns a new set with the the elements of this that are not in [other]. | |
| 168 * | |
| 169 * That is, the returned set contains all the elements of this [Set] that | |
| 170 * are not elements of [other] according to `other.contains`. | |
| 171 */ | |
| 172 Set<E> difference(Set<Object> other); | |
| 173 | |
| 174 /** | |
| 175 * Removes all elements in the set. | |
| 176 */ | |
| 177 void clear(); | |
| 178 | |
| 179 /* Creates a [Set] with the same elements and behavior as this `Set`. | |
| 180 * | |
| 181 * The returned set behaves the same as this set | |
| 182 * with regard to adding and removing elements. | |
| 183 * It initially contains the same elements. | |
| 184 * If this set specifies an ordering of the elements, | |
| 185 * the returned set will have the same order. | |
| 186 */ | |
| 187 Set<E> toSet(); | |
| 188 } | |
| OLD | NEW |