1 package org.djutils.immutablecollections;
2
3 import java.util.Comparator;
4 import java.util.NoSuchElementException;
5 import java.util.SortedSet;
6 import java.util.TreeSet;
7
8 /**
9 * A SortedSet interface without the methods that can change it. The return values of subSet, tailSet and headSet are all
10 * ImmutableSortedSets.
11 * <p>
12 * Copyright (c) 2016-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
13 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
14 * distributed under a three-clause BSD-style license, which can be found at
15 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>.
16 * </p>
17 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
18 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
19 * @param <E> the type of content of this Set
20 */
21 public interface ImmutableSortedSet<E> extends ImmutableSet<E>
22 {
23 /**
24 * Returns a modifiable copy of this immutable set.
25 * @return a modifiable copy of this immutable set.
26 */
27 @Override
28 SortedSet<E> toSet();
29
30 /**
31 * Returns the comparator used to order the elements in this immutable set, or <code>null</code> if this immutable set uses
32 * the {@linkplain Comparable natural ordering} of its elements.
33 * @return the comparator used to order the elements in this immutable set, or <code>null</code> if this immutable set uses
34 * the natural ordering of its elements
35 */
36 Comparator<? super E> comparator();
37
38 /**
39 * Returns a view of the portion of this immutable set whose elements range from <code>fromElement</code>, inclusive, to
40 * <code>toElement</code>, exclusive. (If <code>fromElement</code> and <code>toElement</code> are equal, the returned
41 * immutable set is empty.)
42 * <p>
43 * The result of this method is a new, immutable sorted set.
44 * @param fromElement E; low endpoint (inclusive) of the returned immutable set
45 * @param toElement E; high endpoint (exclusive) of the returned immutable set
46 * @return a new, immutable sorted set of the portion of this immutable set whose elements range from
47 * <code>fromElement</code>, inclusive, to <code>toElement</code>, exclusive
48 * @throws ClassCastException if <code>fromElement</code> and <code>toElement</code> cannot be compared to one another using
49 * this immutable set's comparator (or, if the immutable set has no comparator, using natural ordering).
50 * Implementations may, but are not required to, throw this exception if <code>fromElement</code> or
51 * <code>toElement</code> cannot be compared to elements currently in the immutable set.
52 * @throws NullPointerException if <code>fromElement</code> or <code>toElement</code> is null and this immutable set does
53 * not permit null elements
54 * @throws IllegalArgumentException if <code>fromElement</code> is greater than <code>toElement</code>; or if this immutable
55 * set itself has a restricted range, and <code>fromElement</code> or <code>toElement</code> lies outside the
56 * bounds of the range
57 */
58 ImmutableSortedSet<E> subSet(E fromElement, E toElement);
59
60 /**
61 * Returns a view of the portion of this immutable set whose elements are strictly less than <code>toElement</code>. The
62 * returned immutable set is backed by this immutable set, so changes in the returned immutable set are reflected in this
63 * immutable set, and vice-versa. The returned immutable set supports all optional immutable set operations that this
64 * immutable set supports.
65 * <p>
66 * The result of this method is a new, immutable sorted set.
67 * @param toElement E; high endpoint (exclusive) of the returned immutable set
68 * @return a view of the portion of this immutable set whose elements are strictly less than <code>toElement</code>
69 * @throws ClassCastException if <code>toElement</code> is not compatible with this immutable set's comparator (or, if the
70 * immutable set has no comparator, if <code>toElement</code> does not implement {@link Comparable}).
71 * Implementations may, but are not required to, throw this exception if <code>toElement</code> cannot be
72 * compared to elements currently in the immutable set.
73 * @throws NullPointerException if <code>toElement</code> is null and this immutable set does not permit null elements
74 * @throws IllegalArgumentException if this immutable set itself has a restricted range, and <code>toElement</code> lies
75 * outside the bounds of the range
76 */
77 ImmutableSortedSet<E> headSet(E toElement);
78
79 /**
80 * Returns a view of the portion of this immutable set whose elements are greater than or equal to <code>fromElement</code>.
81 * The returned immutable set is backed by this immutable set, so changes in the returned immutable set are reflected in
82 * this immutable set, and vice-versa. The returned immutable set supports all optional immutable set operations that this
83 * immutable set supports.
84 * <p>
85 * The result of this method is a new, immutable sorted set.
86 * @param fromElement E; low endpoint (inclusive) of the returned immutable set
87 * @return a view of the portion of this immutable set whose elements are greater than or equal to <code>fromElement</code>
88 * @throws ClassCastException if <code>fromElement</code> is not compatible with this immutable set's comparator (or, if the
89 * immutable set has no comparator, if <code>fromElement</code> does not implement {@link Comparable}).
90 * Implementations may, but are not required to, throw this exception if <code>fromElement</code> cannot be
91 * compared to elements currently in the immutable set.
92 * @throws NullPointerException if <code>fromElement</code> is null and this immutable set does not permit null elements
93 * @throws IllegalArgumentException if this immutable set itself has a restricted range, and <code>fromElement</code> lies
94 * outside the bounds of the range
95 */
96 ImmutableSortedSet<E> tailSet(E fromElement);
97
98 /**
99 * Returns the first (lowest) element currently in this immutable set.
100 * @return the first (lowest) element currently in this immutable set
101 * @throws NoSuchElementException if this immutable set is empty
102 */
103 E first();
104
105 /**
106 * Returns the last (highest) element currently in this immutable set.
107 * @return the last (highest) element currently in this immutable set
108 * @throws NoSuchElementException if this immutable set is empty
109 */
110 E last();
111
112 /**
113 * Force to redefine equals for the implementations of immutable collection classes.
114 * @param obj Object; the object to compare this collection with
115 * @return whether the objects are equal
116 */
117 @Override
118 boolean equals(Object obj);
119
120 /**
121 * Force to redefine hashCode for the implementations of immutable collection classes.
122 * @return the calculated hashCode
123 */
124 @Override
125 int hashCode();
126
127 /**
128 * Return an empty ImmutableSortedSet, backed by a TreeSet.
129 * @param <E> the value type
130 * @return ImmutableSortedSet<K, V>; an empty ImmutableSortedSet
131 */
132 static <E> ImmutableSortedSet<E> of()
133 {
134 return new ImmutableTreeSet<>(new TreeSet<E>(), Immutable.WRAP);
135 }
136
137 /**
138 * Return an ImmutableSortedSet with 1 entry, backed by a TreeSet.
139 * @param <E> the value type
140 * @param v1 E; value 1
141 * @return ImmutableSortedSet<K, V>; an ImmutableSortedSet with 1 entry, backed by a TreeSet
142 */
143 static <E> ImmutableSortedSet<E> of(final E v1)
144 {
145 TreeSet<E> set = new TreeSet<>();
146 set.add(v1);
147 return new ImmutableTreeSet<>(set, Immutable.WRAP);
148 }
149
150 /**
151 * Return an ImmutableSortedSet with 2 entries, backed by a TreeSet.
152 * @param <E> the value type
153 * @param v1 E; value 1
154 * @param v2 E; value 2
155 * @return ImmutableSortedSet<K, V>; an ImmutableSortedSet with 2 entries, backed by a TreeSet
156 */
157 static <E> ImmutableSortedSet<E> of(final E v1, final E v2)
158 {
159 TreeSet<E> set = new TreeSet<>();
160 set.add(v1);
161 set.add(v2);
162 return new ImmutableTreeSet<>(set, Immutable.WRAP);
163 }
164
165 /**
166 * Return an ImmutableSortedSet with 3 entries, backed by a TreeSet.
167 * @param <E> the value type
168 * @param v1 E; value 1
169 * @param v2 E; value 2
170 * @param v3 E; value 3
171 * @return ImmutableSortedSet<K, V>; an ImmutableSortedSet with 3 entries, backed by a TreeSet
172 */
173 static <E> ImmutableSortedSet<E> of(final E v1, final E v2, final E v3)
174 {
175 TreeSet<E> set = new TreeSet<>();
176 set.add(v1);
177 set.add(v2);
178 set.add(v3);
179 return new ImmutableTreeSet<>(set, Immutable.WRAP);
180 }
181
182 /**
183 * Return an ImmutableSortedSet with 4 entries, backed by a TreeSet.
184 * @param <E> the value type
185 * @param v1 E; value 1
186 * @param v2 E; value 2
187 * @param v3 E; value 3
188 * @param v4 E; value 4
189 * @return ImmutableSortedSet<K, V>; an ImmutableSortedSet with 4 entries, backed by a TreeSet
190 */
191 static <E> ImmutableSortedSet<E> of(final E v1, final E v2, final E v3, final E v4)
192 {
193 TreeSet<E> set = new TreeSet<>();
194 set.add(v1);
195 set.add(v2);
196 set.add(v3);
197 set.add(v4);
198 return new ImmutableTreeSet<>(set, Immutable.WRAP);
199 }
200
201 /**
202 * Return an ImmutableSortedSet with 5 or more entries, backed by a TreeSet.
203 * @param <E> the value type
204 * @param v1 E; value 1
205 * @param v2 E; value 2
206 * @param v3 E; value 3
207 * @param v4 E; value 4
208 * @param v5 E; value 5
209 * @param vn E...; values 6 and beyond
210 * @return ImmutableSortedSet<K, V>; an ImmutableSortedSet with 5 or more entries, backed by a TreeSet
211 */
212 @SuppressWarnings("unchecked")
213 static <E> ImmutableSortedSet<E> of(final E v1, final E v2, final E v3, final E v4, final E v5, final E... vn)
214 {
215 TreeSet<E> set = new TreeSet<>();
216 set.add(v1);
217 set.add(v2);
218 set.add(v3);
219 set.add(v4);
220 set.add(v5);
221 for (E v : vn)
222 {
223 set.add(v);
224 }
225 return new ImmutableTreeSet<>(set, Immutable.WRAP);
226 }
227
228 }