1 package org.opentrafficsim.base.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) 2013-2016 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
12 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
13 * </p>
14 * $LastChangedDate: 2015-07-24 02:58:59 +0200 (Fri, 24 Jul 2015) $, @version $Revision: 1147 $, by $Author: averbraeck $,
15 * initial version May 7, 2016 <br>
16 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
17 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
18 * @author <a href="http://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 SortedSet<E> toSet();
28
29 /**
30 * Returns the comparator used to order the elements in this immutable set, or <tt>null</tt> if this immutable set uses the
31 * {@linkplain Comparable natural ordering} of its elements.
32 * @return the comparator used to order the elements in this immutable set, or <tt>null</tt> if this immutable set uses the
33 * natural ordering of its elements
34 */
35 Comparator<? super E> comparator();
36
37 /**
38 * Returns a view of the portion of this immutable set whose elements range from <tt>fromElement</tt>, inclusive, to
39 * <tt>toElement</tt>, exclusive. (If <tt>fromElement</tt> and <tt>toElement</tt> are equal, the returned immutable set is
40 * empty.)
41 * <p>
42 * The result of this method is a new, immutable sorted set.
43 * @param fromElement low endpoint (inclusive) of the returned immutable set
44 * @param toElement high endpoint (exclusive) of the returned immutable set
45 * @return a new, immutable sorted set of the portion of this immutable set whose elements range from <tt>fromElement</tt>,
46 * inclusive, to <tt>toElement</tt>, exclusive
47 * @throws ClassCastException if <tt>fromElement</tt> and <tt>toElement</tt> cannot be compared to one another using this
48 * immutable set's comparator (or, if the immutable set has no comparator, using natural ordering).
49 * Implementations may, but are not required to, throw this exception if <tt>fromElement</tt> or
50 * <tt>toElement</tt> cannot be compared to elements currently in the immutable set.
51 * @throws NullPointerException if <tt>fromElement</tt> or <tt>toElement</tt> is null and this immutable set does not permit
52 * null elements
53 * @throws IllegalArgumentException if <tt>fromElement</tt> is greater than <tt>toElement</tt>; or if this immutable set
54 * itself has a restricted range, and <tt>fromElement</tt> or <tt>toElement</tt> lies outside the bounds of the
55 * range
56 */
57 ImmutableSortedSet<E> subSet(E fromElement, E toElement);
58
59 /**
60 * Returns a view of the portion of this immutable set whose elements are strictly less than <tt>toElement</tt>. The
61 * returned immutable set is backed by this immutable set, so changes in the returned immutable set are reflected in this
62 * immutable set, and vice-versa. The returned immutable set supports all optional immutable set operations that this
63 * immutable set supports.
64 * <p>
65 * The result of this method is a new, immutable sorted set.
66 * @param toElement high endpoint (exclusive) of the returned immutable set
67 * @return a view of the portion of this immutable set whose elements are strictly less than <tt>toElement</tt>
68 * @throws ClassCastException if <tt>toElement</tt> is not compatible with this immutable set's comparator (or, if the
69 * immutable set has no comparator, if <tt>toElement</tt> does not implement {@link Comparable}).
70 * Implementations may, but are not required to, throw this exception if <tt>toElement</tt> cannot be compared
71 * to elements currently in the immutable set.
72 * @throws NullPointerException if <tt>toElement</tt> is null and this immutable set does not permit null elements
73 * @throws IllegalArgumentException if this immutable set itself has a restricted range, and <tt>toElement</tt> lies outside
74 * the bounds of the range
75 */
76 ImmutableSortedSet<E> headSet(E toElement);
77
78 /**
79 * Returns a view of the portion of this immutable set whose elements are greater than or equal to <tt>fromElement</tt>. The
80 * returned immutable set is backed by this immutable set, so changes in the returned immutable set are reflected in this
81 * immutable set, and vice-versa. The returned immutable set supports all optional immutable set operations that this
82 * immutable set supports.
83 * <p>
84 * The result of this method is a new, immutable sorted set.
85 * @param fromElement low endpoint (inclusive) of the returned immutable set
86 * @return a view of the portion of this immutable set whose elements are greater than or equal to <tt>fromElement</tt>
87 * @throws ClassCastException if <tt>fromElement</tt> is not compatible with this immutable set's comparator (or, if the
88 * immutable set has no comparator, if <tt>fromElement</tt> does not implement {@link Comparable}).
89 * Implementations may, but are not required to, throw this exception if <tt>fromElement</tt> cannot be compared
90 * to elements currently in the immutable set.
91 * @throws NullPointerException if <tt>fromElement</tt> is null and this immutable set does not permit null elements
92 * @throws IllegalArgumentException if this immutable set itself has a restricted range, and <tt>fromElement</tt> lies
93 * outside the bounds of the range
94 */
95 ImmutableSortedSet<E> tailSet(E fromElement);
96
97 /**
98 * Returns the first (lowest) element currently in this immutable set.
99 * @return the first (lowest) element currently in this immutable set
100 * @throws NoSuchElementException if this immutable set is empty
101 */
102 E first();
103
104 /**
105 * Returns the last (highest) element currently in this immutable set.
106 * @return the last (highest) element currently in this immutable set
107 * @throws NoSuchElementException if this immutable set is empty
108 */
109 E last();
110
111 /**
112 * Force to redefine equals for the implementations of immutable collection classes.
113 * @param obj the object to compare this collection with
114 * @return whether the objects are equal
115 */
116 boolean equals(final Object obj);
117
118 /**
119 * Force to redefine hashCode for the implementations of immutable collection classes.
120 * @return the calculated hashCode
121 */
122 int hashCode();
123
124 }