1 package eu.simuline.util;
2
3 import java.util.Iterator;
4
5 /**
6 * Generalization of iterator suitable e.g. for sets to {@link MultiSet}s.
7 * Needed in addition: methods on multiplicity of element read last.
8 * <p>
9 * Not clear whether one should not allow addMult.
10 * why not unify addMult and removeMult?
11 * This would require a different implementation.
12 * Problem is also that {@link MultiSet} is not (yet) a collection.
13 *
14 *
15 * @param <E>
16 * the class of the elements of this multi-set.
17 *
18 * Created: Fri Oct 3 21:37:29 2014
19 *
20 * @author <a href="mailto:ernst.reissner@simuline.eu">Ernst Reissner</a>
21 * @version 1.0
22 */
23 public interface MultiSetIterator<E> extends Iterator<E> {
24
25 /**
26 * Removes from the underlying {@link MultiSet}
27 * the last element returned by {@link #next()},
28 * provided that element was not removed in the meantime
29 * and this method is supported by this iterator.
30 * <p>
31 * Invoking this method removes that element
32 * from the set associated with {@link MultiSet}.
33 * After this, neither {@link #setMult(int)} nor {@link #removeMult(int)}
34 * nor {@link #getMult()} may be invoked
35 * before next invocation of {@link #next()}.
36 * <p>
37 * The behavior of this iterator is unspecified
38 * if the underlying {@link MultiSet} is modified
39 * while the iteration is in progress
40 * in any way other than by calling methods of an iterator.
41 *
42 * @throws UnsupportedOperationException
43 * if removing is not supported by this iterator.
44 * This is in particular true
45 * if the underlying {@link MultiSet} is immutable.
46 * @throws IllegalStateException
47 * provided this method is supported by this iterator:
48 * if the method {@link #next()} has not yet been called
49 * or if, after last invocation of {@link #next()}
50 * the element returned by this invocation has been removed
51 * from the underlying {@link MultiSet}
52 * invoking {@link #remove()}, {@link #setMult(int)}
53 * or {@link #removeMult(int)} or a combination in an appropriate way.
54 */
55 void remove();
56
57 /**
58 * Returns the current multiplicity of the element
59 * last read by {@link #next()},
60 * provided that element was not removed in the meantime.
61 * This multiplicity could have been modified
62 * after last invocation of {@link #next()}
63 * by invoking {@link #remove()},
64 * {@link #setMult(int)} or {@link #removeMult(int)}.
65 * If the multiplicity became zero,
66 * this means that it has been completely removed
67 * and so its multiplicity cannot be queried any more.
68 *
69 * @return
70 * the multiplicity of the element this method refers to.
71 * This is a positive integer.
72 * @throws IllegalStateException
73 * if the method {@link #next()} has not yet been called
74 * or if, after last invocation of {@link #next()}
75 * the element returned by this invocation has been removed
76 * from the underlying {@link MultiSet}
77 * invoking {@link #remove()}, {@link #setMult(int)}
78 * or {@link #removeMult(int)} or a combination in an appropriate way.
79 */
80 int getMult();
81
82 // **** two places were Multiplicity is exposed.
83 MultiSet.Multiplicity getMultObj();
84
85 /**
86 * Endows the element of the underlying {@link MultiSet}
87 * returned by the last invocation of {@link #next()}
88 * with multiplicity given by <code>setMult</code>,
89 * provided that element was not removed in the meantime
90 * and this method is supported by this iterator.
91 * <p>
92 * For <code>setMult=0</code>, invoking this method removes that element
93 * from the set associated with {@link MultiSet}.
94 * After this, neither {@link #setMult(int)} nor {@link #removeMult(int)}
95 * nor {@link #remove()} nor {@link #getMult()} may be invoked
96 * before next invocation of {@link #next()}.
97 * <p>
98 * The behavior of this iterator is unspecified
99 * if the underlying {@link MultiSet} is modified
100 * while the iteration is in progress
101 * in any way other than by calling methods of an iterator.
102 *
103 * @param setMult
104 * a non-negative number signifying the new multiplicity
105 * of the element read last by {@link #next()}.
106 * @return
107 * the multiplicity of the element this method refers to
108 * before invoking this method.
109 * @throws UnsupportedOperationException
110 * if setting multiplicity is not supported by this iterator.
111 * This is in particular true
112 * if the underlying {@link MultiSet} is immutable.
113 * @throws IllegalStateException
114 * provided this method is supported by this iterator:
115 * if the method {@link #next()} has not yet been called
116 * or if, after last invocation of {@link #next()}
117 * the element returned by this invocation has been removed
118 * from the underlying {@link MultiSet}
119 * invoking {@link #remove()}, {@link #setMult(int)}
120 * or {@link #removeMult(int)} or a combination in an appropriate way.
121 * @throws IllegalArgumentException
122 * if <code>setMult</code> is negative
123 * and if the abovementioned exceptions are not thrown.
124 */
125 int setMult(int setMult);
126
127 //int addMult(int addMult);
128
129 /**
130 * Removes from the underlying {@link MultiSet}
131 * the last element returned by invocation of {@link #next()}
132 * with multiplicity given by <code>removeMult</code>,
133 * provided that element was not removed in the meantime
134 * and this method is supported by this iterator.
135 * <p>
136 * If <code>removeMult</code> is the multiplicity of that element,
137 * invoking this method removes that element
138 * from the set associated with {@link MultiSet}.
139 * After this, neither {@link #setMult(int)} nor {@link #remove()}
140 * nor {@link #remove()} nor {@link #getMult()} may be invoked
141 * before next invocation of {@link #next()}.
142 * <p>
143 * The behavior of this iterator is unspecified
144 * if the underlying {@link MultiSet} is modified
145 * while the iteration is in progress
146 * in any way other than by calling methods of an iterator.
147 *
148 * @param removeMult
149 * a number signifying the multiplicity which which
150 * the current element should be removed.
151 * Negative values signify adding that element.
152 * @return
153 * the multiplicity of the element this method refers to
154 * before invoking this method.
155 * @throws UnsupportedOperationException
156 * if removing multiplicity is not supported by this iterator.
157 * This is in particular true
158 * if the underlying {@link MultiSet} is immutable.
159 * @throws IllegalStateException
160 * if the method {@link #next()} has not yet been called
161 * or if, after last invocation of {@link #next()}
162 * the element returned by this invocation has been removed
163 * from the underlying {@link MultiSet}
164 * invoking {@link #remove()}, {@link #setMult(int)}
165 * or {@link #removeMult(int)} or a combination in an appropriate way.
166 * @throws IllegalArgumentException
167 * if <code>removeMult</code> or resulting multiplicity is negative
168 * and if the abovementioned exceptions are not thrown.
169 * @see #remove()
170 */
171 int removeMult(int removeMult);
172 }