1 package eu.simuline.util;
2
3 import java.util.SortedSet;
4 import java.util.NavigableMap;
5 import java.util.Comparator;
6 import java.util.NoSuchElementException; // for javadoc only
7
8 /**
9 * Represents a sorted set with multiplicities.
10 *
11 * If MultiSet extend Set, SortedMultiSet shall extend SortedSet
12 *
13 * @param <T>
14 * the class of the elements of this multi-set.
15 *
16 * Created: Sun Nov 23 22:36:30 2014
17 *
18 * @author <a href="mailto:ernst.reissner@simuline.eu">Ernst Reissner</a>
19 * @version 1.0
20 */
21 public interface SortedMultiSet<T> extends MultiSet<T> {
22
23 /**
24 * Returns a view of the underlying sorted set
25 * of this <code>SortedMultiSet</code>.
26 * For certain implementations, this set is immutable
27 * to prevent implicit modification of this <code>SortedMultiSet</code>.
28 *
29 * @return
30 * the <code>SortedSet</code> containing exactly the objects
31 * with strictly positive multiplicity
32 * in this <code>SortedMultiSet</code>.
33 */
34 SortedSet<T> getSet();
35
36 /**
37 * Returns a view of the underlying map of this <code>MultiSet</code>
38 * as a map mapping each entry to its multiplicity.
39 */
40 NavigableMap<T, Multiplicity> getMap();
41
42 /**
43 * Returns the comparator used to order the elements in this set,
44 * or <code>null</code>
45 * if this set uses the natural ordering of its elements.
46 *
47 * @return
48 * the comparator used to order the elements in this set,
49 * or <code>null</code>
50 * if this set uses the natural ordering of its elements.
51 */
52 Comparator<? super T> comparator();
53
54 /**
55 * Returns the first (lowest) element currently in this set.
56 *
57 * @return
58 * the first (lowest) element currently in this set
59 * @throws NoSuchElementException
60 * if this set is empty.
61 */
62 T first();
63
64 /**
65 * Returns the last (highest) element currently in this set.
66 *
67 * @return
68 * the last (highest) element currently in this set.
69 * @throws NoSuchElementException
70 * if this set is empty.
71 */
72 T last();
73
74 /**
75 * Returns a view of the portion of this multi-set
76 * whose elements are strictly less than <code>toElement</code>.
77 * The returned multi-set is backed by this multi-set,
78 * so changes in the returned set are reflected in this multi-set,
79 * and vice-versa.
80 * The returned multi-set supports all optional multi-set operations
81 * that this multi-set supports.
82 * <p>
83 * The returned multi-set
84 * will throw an <code>IllegalArgumentException</code>
85 * on an attempt to insert an element outside its range.
86 *
87 * @param toElement
88 * high endpoint (exclusive) of the returned multi-set.
89 * @return
90 * a view of the portion of this multi-set
91 * whose elements are strictly less than <code>toElement</code>.
92 * @throws ClassCastException
93 * if <code>toElement</code> is not compatible
94 * with this multi-set's comparator
95 * (or, if the set has no comparator,
96 * if <code>toElement</code> does not implement {@link Comparable}).
97 * Implementations may, but are not required to,
98 * throw this exception if <code>toElement</code> cannot be compared
99 * to elements currently in this multi-set.
100 * @throws NullPointerException
101 * if <code>toElement</code> is <code>null</code>
102 * and this multi-set does not permit <code>null</code> elements.
103 * @throws IllegalArgumentException
104 * if this multi-set itself has a restricted range,
105 * and <code>toElement</code> lies outside the bounds of the range.
106 */
107 SortedMultiSet<T> headSet(T toElement);
108
109 /**
110 * Returns a view of the portion of this multi-set
111 * whose elements are greater than or equal to <code>fromElement</code>.
112 * The returned multi-set is backed by this multi-set,
113 * so changes in the returned set are reflected in this multi-set,
114 * and vice-versa.
115 * The returned multi-set supports all optional multi-set operations
116 * that this multi-set supports.
117 * <p>
118 * The returned multi-set
119 * will throw an <code>IllegalArgumentException</code>
120 * on an attempt to insert an element outside its range.
121 *
122 * @param fromElement
123 * low endpoint (inclusive) of the returned multi-set.
124 * @return
125 * a view of the portion of this multi-set
126 * whose elements are greater than or equal to <code>fromElement</code>.
127 * @throws ClassCastException
128 * if <code>fromElement</code> is not compatible
129 * with this multi-set's comparator
130 * (or, if the set has no comparator,
131 * if <code>fromElement</code> does not implement {@link Comparable}).
132 * Implementations may, but are not required to,
133 * throw this exception if <code>fromElement</code> cannot be compared
134 * to elements currently in this multi-set.
135 * @throws NullPointerException
136 * if <code>fromElement</code> is <code>null</code>
137 * and this multi-set does not permit <code>null</code> elements.
138 * @throws IllegalArgumentException
139 * if this multi-set itself has a restricted range,
140 * and <code>fromElement</code> lies outside the bounds of the range.
141 */
142 SortedMultiSet<T> tailSet(T fromElement);
143
144 /**
145 * Returns a view of the portion of this multi-set
146 * whose elements range from <code>fromElement</code> inclusively
147 * to <code>toElement</code> exclusively.
148 * The returned multi-set is backed by this multi-set,
149 * so changes in the returned set are reflected in this multi-set,
150 * and vice-versa.
151 * The returned multi-set supports all optional multi-set operations
152 * that this multi-set supports.
153 * <p>
154 * The returned multi-set
155 * will throw an <code>IllegalArgumentException</code>
156 * on an attempt to insert an element outside its range.
157 *
158 * @param fromElement
159 * low endpoint (inclusive) of the returned multi-set.
160 * @param toElement
161 * high endpoint (exclusive) of the returned multi-set.
162 * @return
163 * a view of the portion of this multi-set
164 * from <code>fromElement</code> inclusively
165 * to <code>toElement</code> exclusively.
166 * @throws ClassCastException **** maybe original documentation wrong. ****
167 * if <code>fromElement</code> and <code>toElement</code>
168 * cannot be compared to one another using this set's comparator
169 * (or, if the set has no comparator, using natural ordering).
170 * or if <code>fromElement</code> is not compatible
171 * with this multi-set's comparator
172 * (or, if the set has no comparator,
173 * if <code>fromElement</code> does not implement {@link Comparable}).
174 * Implementations may, but are not required to,
175 * throw this exception
176 * if <code>fromElement</code> or <code>toElement</code>
177 * cannot be compared to elements currently in this multi-set.
178 * @throws NullPointerException
179 * if <code>fromElement</code> or <code>toElement</code>
180 * is <code>null</code>
181 * and this multi-set does not permit <code>null</code> elements.
182 * @throws IllegalArgumentException
183 * if <code>fromElement</code> is greater than <code>toElement</code>
184 * or if this multi-set itself has a restricted range,
185 * and <code>fromElement</code> or <code>toElement</code>
186 * lies outside the bounds of the range.
187 */
188 SortedMultiSet<T> subSet(T fromElement, T toElement);
189 }