1 /*
2 * Copyright (c) 2017, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 */
23
24
25 package jdk.internal.vm.compiler.collections;
26
27 import java.util.Iterator;
28
29 /**
30 * Memory efficient set data structure.
31 *
32 * @since 1.0
33 */
34 public interface EconomicSet<E> extends UnmodifiableEconomicSet<E> {
35
36 /**
37 * Adds {@code element} to this set if it is not already present.
38 *
39 * @return {@code true} if this set did not already contain {@code element}.
40 * @since 1.0
41 */
42 boolean add(E element);
43
44 /**
45 * Removes {@code element} from this set if it is present. This set will not contain
46 * {@code element} once the call returns.
47 *
48 * @since 1.0
49 */
50 void remove(E element);
51
52 /**
53 * Removes all of the elements from this set. The set will be empty after this call returns.
54 *
55 * @since 1.0
56 */
57 void clear();
58
59 /**
60 * Adds all of the elements in {@code other} to this set if they're not already present.
61 *
62 * @since 1.0
63 */
64 default void addAll(EconomicSet<E> other) {
65 addAll(other.iterator());
66 }
67
68 /**
69 * Adds all of the elements in {@code values} to this set if they're not already present.
70 *
71 * @since 1.0
72 */
73 default void addAll(Iterable<E> values) {
74 addAll(values.iterator());
75 }
76
77 /**
78 * Adds all of the elements enumerated by {@code iterator} to this set if they're not already
79 * present.
80 *
81 * @since 1.0
82 */
83 default void addAll(Iterator<E> iterator) {
84 while (iterator.hasNext()) {
85 add(iterator.next());
86 }
87 }
88
89 /**
90 * Removes from this set all of its elements that are contained in {@code other}.
91 *
92 * @since 1.0
93 */
94 default void removeAll(EconomicSet<E> other) {
95 removeAll(other.iterator());
96 }
97
98 /**
99 * Removes from this set all of its elements that are contained in {@code values}.
100 *
101 * @since 1.0
102 */
103 default void removeAll(Iterable<E> values) {
104 removeAll(values.iterator());
105 }
106
107 /**
108 * Removes from this set all of its elements that are enumerated by {@code iterator}.
109 *
110 * @since 1.0
111 */
112 default void removeAll(Iterator<E> iterator) {
113 while (iterator.hasNext()) {
114 remove(iterator.next());
115 }
116 }
117
118 /**
119 * Removes from this set all of its elements that are not contained in {@code other}.
120 *
121 * @since 1.0
122 */
123 default void retainAll(EconomicSet<E> other) {
124 Iterator<E> iterator = iterator();
125 while (iterator.hasNext()) {
126 E key = iterator.next();
127 if (!other.contains(key)) {
128 iterator.remove();
129 }
130 }
131 }
132
133 /**
134 * Creates a new set guaranteeing insertion order when iterating over its elements with the
135 * default {@link Equivalence#DEFAULT} comparison strategy.
136 *
137 * @since 1.0
138 */
139 static <E> EconomicSet<E> create() {
140 return EconomicSet.create(Equivalence.DEFAULT);
141 }
142
143 /**
144 * Creates a new set guaranteeing insertion order when iterating over its elements.
145 *
146 * @since 1.0
147 */
148 static <E> EconomicSet<E> create(Equivalence strategy) {
149 return EconomicMapImpl.create(strategy, true);
150 }
151
152 /**
153 * Creates a new set guaranteeing insertion order when iterating over its elements with the
154 * default {@link Equivalence#DEFAULT} comparison strategy and inserts all elements of the
155 * specified collection.
156 *
157 * @since 1.0
158 */
159 static <E> EconomicSet<E> create(int initialCapacity) {
160 return EconomicSet.create(Equivalence.DEFAULT, initialCapacity);
161 }
162
163 /**
164 * Creates a new set guaranteeing insertion order when iterating over its elements with the
165 * default {@link Equivalence#DEFAULT} comparison strategy and inserts all elements of the
166 * specified collection.
167 *
168 * @since 1.0
169 */
170 static <E> EconomicSet<E> create(UnmodifiableEconomicSet<E> c) {
171 return EconomicSet.create(Equivalence.DEFAULT, c);
172 }
173
174 /**
175 * Creates a new set guaranteeing insertion order when iterating over its elements and
176 * initializes with the given capacity.
177 *
178 * @since 1.0
179 */
180 static <E> EconomicSet<E> create(Equivalence strategy, int initialCapacity) {
181 return EconomicMapImpl.create(strategy, initialCapacity, true);
182 }
183
184 /**
185 * Creates a new set guaranteeing insertion order when iterating over its elements and inserts
186 * all elements of the specified collection.
187 *
188 * @since 1.0
189 */
190 static <E> EconomicSet<E> create(Equivalence strategy, UnmodifiableEconomicSet<E> c) {
191 return EconomicMapImpl.create(strategy, c, true);
192 }
193 }