1 /*
2 * Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * The Universal Permissive License (UPL), Version 1.0
6 *
7 * Subject to the condition set forth below, permission is hereby granted to any
8 * person obtaining a copy of this software, associated documentation and/or
9 * data (collectively the "Software"), free of charge and under any and all
10 * copyright rights in the Software, and any and all patent rights owned or
11 * freely licensable by each licensor hereunder covering either (i) the
12 * unmodified Software as contributed to or provided by such licensor, or (ii)
13 * the Larger Works (as defined below), to deal in both
14 *
15 * (a) the Software, and
16 *
17 * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
18 * one is included with the Software each a "Larger Work" to which the Software
19 * is contributed by such licensors),
20 *
21 * without restriction, including without limitation the rights to copy, create
22 * derivative works of, display, perform, and distribute the Software and make,
23 * use, sell, offer for sale, import, export, have made, and have sold the
24 * Software and the Larger Work(s), and to sublicense the foregoing rights on
25 * either these or other terms.
26 *
27 * This license is subject to the following condition:
28 *
29 * The above copyright notice and either this complete permission notice or at a
30 * minimum a reference to the UPL must be included in all copies or substantial
31 * portions of the Software.
32 *
33 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
34 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
35 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
36 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
37 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
38 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
39 * SOFTWARE.
40 */
41 package jdk.internal.vm.compiler.collections;
42
43 import java.util.Iterator;
44
45 /**
46 * Memory efficient set data structure.
47 *
48 * @since 1.0
49 */
50 public interface EconomicSet<E> extends UnmodifiableEconomicSet<E> {
51
52 /**
53 * Adds {@code element} to this set if it is not already present.
54 *
55 * @return {@code true} if this set did not already contain {@code element}.
56 * @since 1.0
57 */
58 boolean add(E element);
59
60 /**
61 * Removes {@code element} from this set if it is present. This set will not contain
62 * {@code element} once the call returns.
63 *
64 * @since 1.0
65 */
66 void remove(E element);
67
68 /**
69 * Removes all of the elements from this set. The set will be empty after this call returns.
70 *
71 * @since 1.0
72 */
73 void clear();
74
75 /**
76 * Adds all of the elements in {@code other} to this set if they're not already present.
77 *
78 * @since 1.0
79 */
80 default void addAll(EconomicSet<E> other) {
81 addAll(other.iterator());
82 }
83
84 /**
85 * Adds all of the elements in {@code values} to this set if they're not already present.
86 *
87 * @since 1.0
88 */
89 default void addAll(Iterable<E> values) {
90 addAll(values.iterator());
91 }
92
93 /**
94 * Adds all of the elements enumerated by {@code iterator} to this set if they're not already
95 * present.
96 *
97 * @since 1.0
98 */
99 default void addAll(Iterator<E> iterator) {
100 while (iterator.hasNext()) {
101 add(iterator.next());
102 }
103 }
104
105 /**
106 * Removes from this set all of its elements that are contained in {@code other}.
107 *
108 * @since 1.0
109 */
110 default void removeAll(EconomicSet<E> other) {
111 removeAll(other.iterator());
112 }
113
114 /**
115 * Removes from this set all of its elements that are contained in {@code values}.
116 *
117 * @since 1.0
118 */
119 default void removeAll(Iterable<E> values) {
120 removeAll(values.iterator());
121 }
122
123 /**
124 * Removes from this set all of its elements that are enumerated by {@code iterator}.
125 *
126 * @since 1.0
127 */
128 default void removeAll(Iterator<E> iterator) {
129 while (iterator.hasNext()) {
130 remove(iterator.next());
131 }
132 }
133
134 /**
135 * Removes from this set all of its elements that are not contained in {@code other}.
136 *
137 * @since 1.0
138 */
139 default void retainAll(EconomicSet<E> other) {
140 Iterator<E> iterator = iterator();
141 while (iterator.hasNext()) {
142 E key = iterator.next();
143 if (!other.contains(key)) {
144 iterator.remove();
145 }
146 }
147 }
148
149 /**
150 * Creates a new set guaranteeing insertion order when iterating over its elements with the
151 * default {@link Equivalence#DEFAULT} comparison strategy.
152 *
153 * @since 1.0
154 */
155 static <E> EconomicSet<E> create() {
156 return EconomicSet.create(Equivalence.DEFAULT);
157 }
158
159 /**
160 * Creates a new set guaranteeing insertion order when iterating over its elements.
161 *
162 * @since 1.0
163 */
164 static <E> EconomicSet<E> create(Equivalence strategy) {
165 return EconomicMapImpl.create(strategy, true);
166 }
167
168 /**
169 * Creates a new set guaranteeing insertion order when iterating over its elements with the
170 * default {@link Equivalence#DEFAULT} comparison strategy and inserts all elements of the
171 * specified collection.
172 *
173 * @since 1.0
174 */
175 static <E> EconomicSet<E> create(int initialCapacity) {
176 return EconomicSet.create(Equivalence.DEFAULT, initialCapacity);
177 }
178
179 /**
180 * Creates a new set guaranteeing insertion order when iterating over its elements with the
181 * default {@link Equivalence#DEFAULT} comparison strategy and inserts all elements of the
182 * specified collection.
183 *
184 * @since 1.0
185 */
186 static <E> EconomicSet<E> create(UnmodifiableEconomicSet<E> c) {
187 return EconomicSet.create(Equivalence.DEFAULT, c);
188 }
189
190 /**
191 * Creates a new set guaranteeing insertion order when iterating over its elements and
192 * initializes with the given capacity.
193 *
194 * @since 1.0
195 */
196 static <E> EconomicSet<E> create(Equivalence strategy, int initialCapacity) {
197 return EconomicMapImpl.create(strategy, initialCapacity, true);
198 }
199
200 /**
201 * Creates a new set guaranteeing insertion order when iterating over its elements and inserts
202 * all elements of the specified collection.
203 *
204 * @since 1.0
205 */
206 static <E> EconomicSet<E> create(Equivalence strategy, UnmodifiableEconomicSet<E> c) {
207 return EconomicMapImpl.create(strategy, c, true);
208 }
209 }