1 package org.djutils.immutablecollections;
2
3 import java.util.Comparator;
4 import java.util.NoSuchElementException;
5 import java.util.SortedSet;
6
7 /**
8 * A SortedSet interface without the methods that can change it. The return values of subSet, tailSet and headSet are all
9 * ImmutableSortedSets.
10 * <p>
11 * Copyright (c) 2016-2019 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
12 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
13 * distributed under a three-clause BSD-style license, which can be found at
14 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>.
15 * </p>
16 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
17 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
18 * @author <a href="https://www.transport.citg.tudelft.nl">Wouter Schakel</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 the
32 * {@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 the
34 * 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 immutable set is
41 * 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 <code>fromElement</code>,
47 * inclusive, to <code>toElement</code>, exclusive
48 * @throws ClassCastException if <code>fromElement</code> and <code>toElement</code> cannot be compared to one another using this
49 * 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 not permit
53 * null elements
54 * @throws IllegalArgumentException if <code>fromElement</code> is greater than <code>toElement</code>; or if this immutable set
55 * itself has a restricted range, and <code>fromElement</code> or <code>toElement</code> lies outside the bounds of the
56 * 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 compared
72 * 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 outside
75 * 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>. The
81 * returned immutable set is backed by this immutable set, so changes in the returned immutable set are reflected in this
82 * 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 compared
91 * 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 }