1 package org.djutils.immutablecollections;
2
3 import java.util.Collections;
4 import java.util.Comparator;
5 import java.util.NavigableSet;
6
7 /**
8 * A {@link ImmutableSortedSet} extended with navigation methods reporting closest matches for given search targets. Methods
9 * {@code lower}, {@code floor}, {@code ceiling}, and {@code higher} return elements respectively less than, less than or equal,
10 * greater than or equal, and greater than a given element, returning {@code null} if there is no such element. All methods from
11 * java.util.NavigableSet that can change the set have been left out.
12 * <p>
13 * Copyright (c) 2016-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
14 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
15 * distributed under a three-clause BSD-style license, which can be found at
16 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>.
17 * </p>
18 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
19 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
20 * @param <E> the type of content of this Set
21 */
22 public interface ImmutableNavigableSet<E> extends ImmutableSortedSet<E>
23 {
24 /**
25 * Returns a modifiable copy of this immutable set.
26 * @return a modifiable copy of this immutable set.
27 */
28 @Override
29 NavigableSet<E> toSet();
30
31 /**
32 * Returns the greatest element in this immutable set strictly less than the given element, or {@code null} if there is no
33 * such element.
34 * @param e E; the value to match
35 * @return the greatest element less than {@code e}, or {@code null} if there is no such element
36 * @throws ClassCastException if the specified element cannot be compared with the elements currently in the immutable set
37 * @throws NullPointerException if the specified element is null and this immutable set does not permit null elements
38 */
39 E lower(E e);
40
41 /**
42 * Returns the greatest element in this immutable set less than or equal to the given element, or {@code null} if there is
43 * no such element.
44 * @param e E; the value to match
45 * @return the greatest element less than or equal to {@code e}, or {@code null} if there is no such element
46 * @throws ClassCastException if the specified element cannot be compared with the elements currently in the immutable set
47 * @throws NullPointerException if the specified element is null and this immutable set does not permit null elements
48 */
49 E floor(E e);
50
51 /**
52 * Returns the least element in this immutable set greater than or equal to the given element, or {@code null} if there is
53 * no such element.
54 * @param e E; the value to match
55 * @return the least element greater than or equal to {@code e}, or {@code null} if there is no such element
56 * @throws ClassCastException if the specified element cannot be compared with the elements currently in the immutable set
57 * @throws NullPointerException if the specified element is null and this immutable set does not permit null elements
58 */
59 E ceiling(E e);
60
61 /**
62 * Returns the least element in this immutable set strictly greater than the given element, or {@code null} if there is no
63 * such element.
64 * @param e E; the value to match
65 * @return the least element greater than {@code e}, or {@code null} if there is no such element
66 * @throws ClassCastException if the specified element cannot be compared with the elements currently in the immutable set
67 * @throws NullPointerException if the specified element is null and this immutable set does not permit null elements
68 */
69 E higher(E e);
70
71 /**
72 * Returns a reverse order view of the elements contained in this immutable set.
73 * <p>
74 * The returned immutable set has an ordering equivalent to
75 * <code>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</code>. The expression
76 * {@code s.descendingSet().descendingSet()} returns a view of {@code s} essentially equivalent to {@code s}.
77 * @return a reverse order view of this immutable set
78 */
79 ImmutableNavigableSet<E> descendingSet();
80
81 /**
82 * Returns an immutable iterator over the elements in this immutable set, in descending order. Equivalent in effect to
83 * {@code descendingSet().iterator()}.
84 * @return an immutable iterator over the elements in this immutable set, in descending order
85 */
86 ImmutableIterator<E> descendingIterator();
87
88 /**
89 * Returns a view of the portion of this immutable set whose elements range from {@code fromElement} to {@code toElement}.
90 * If {@code fromElement} and {@code toElement} are equal, the returned immutable set is empty unless {@code fromInclusive}
91 * and {@code toInclusive} are both true.
92 * @param fromElement E; low endpoint of the returned immutable set
93 * @param fromInclusive boolean; {@code true} if the low endpoint is to be included in the returned view
94 * @param toElement E; high endpoint of the returned immutable set
95 * @param toInclusive boolean; {@code true} if the high endpoint is to be included in the returned view
96 * @return a view of the portion of this immutable set whose elements range from {@code fromElement}, inclusive, to
97 * {@code toElement}, exclusive
98 * @throws ClassCastException if {@code fromElement} and {@code toElement} cannot be compared to one another using this
99 * immutable set's comparator (or, if the immutable set has no comparator, using natural ordering).
100 * Implementations may, but are not required to, throw this exception if {@code fromElement} or
101 * {@code toElement} cannot be compared to elements currently in the immutable set.
102 * @throws NullPointerException if {@code fromElement} or {@code toElement} is null and this immutable set does not permit
103 * null elements
104 * @throws IllegalArgumentException if {@code fromElement} is greater than {@code toElement}; or if this immutable set
105 * itself has a restricted range, and {@code fromElement} or {@code toElement} lies outside the bounds of the
106 * range.
107 */
108 ImmutableNavigableSet<E> subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive);
109
110 /**
111 * Returns a view of the portion of this immutable set whose elements are less than (or equal to, if {@code inclusive} is
112 * true) {@code toElement}.
113 * @param toElement E; high endpoint of the returned immutable set
114 * @param inclusive boolean; {@code true} if the high endpoint is to be included in the returned view
115 * @return a view of the portion of this immutable set whose elements are less than (or equal to, if {@code inclusive} is
116 * true) {@code toElement}
117 * @throws ClassCastException if {@code toElement} is not compatible with this immutable set's comparator (or, if the
118 * immutable set has no comparator, if {@code toElement} does not implement {@link Comparable}). Implementations
119 * may, but are not required to, throw this exception if {@code toElement} cannot be compared to elements
120 * currently in the immutable set.
121 * @throws NullPointerException if {@code toElement} is null and this immutable set does not permit null elements
122 * @throws IllegalArgumentException if this immutable set itself has a restricted range, and {@code toElement} lies outside
123 * the bounds of the range
124 */
125 ImmutableNavigableSet<E> headSet(E toElement, boolean inclusive);
126
127 /**
128 * Returns a view of the portion of this immutable set whose elements are greater than (or equal to, if {@code inclusive} is
129 * true) {@code fromElement}.
130 * @param fromElement E; low endpoint of the returned immutable set
131 * @param inclusive boolean; {@code true} if the low endpoint is to be included in the returned view
132 * @return a view of the portion of this immutable set whose elements are greater than or equal to {@code fromElement}
133 * @throws ClassCastException if {@code fromElement} is not compatible with this immutable set's comparator (or, if the
134 * immutable set has no comparator, if {@code fromElement} does not implement {@link Comparable}).
135 * Implementations may, but are not required to, throw this exception if {@code fromElement} cannot be compared
136 * to elements currently in the immutable set.
137 * @throws NullPointerException if {@code fromElement} is null and this immutable set does not permit null elements
138 * @throws IllegalArgumentException if this immutable set itself has a restricted range, and {@code fromElement} lies
139 * outside the bounds of the range
140 */
141 ImmutableNavigableSet<E> tailSet(E fromElement, boolean inclusive);
142
143 /**
144 * Force to redefine equals for the implementations of immutable collection classes.
145 * @param obj Object; the object to compare this collection with
146 * @return whether the objects are equal
147 */
148 @Override
149 boolean equals(Object obj);
150
151 /**
152 * Force to redefine hashCode for the implementations of immutable collection classes.
153 * @return the calculated hashCode
154 */
155 @Override
156 int hashCode();
157
158 }