|
132
|
1 /*
|
|
|
2 File: View.d
|
|
|
3
|
|
|
4 Originally written by Doug Lea and released into the public domain.
|
|
|
5 Thanks for the assistance and support of Sun Microsystems Labs, Agorics
|
|
|
6 Inc, Loral, and everyone contributing, testing, and using this code.
|
|
|
7
|
|
|
8 History:
|
|
|
9 Date Who What
|
|
|
10 24Sep95 dl@cs.oswego.edu Create from collections.d working file
|
|
|
11 14dec95 dl Declare as a subinterface of Cloneable
|
|
|
12 9Apr97 dl made Serializable
|
|
|
13
|
|
|
14 */
|
|
|
15
|
|
|
16
|
|
|
17 module tango.util.collection.model.View;
|
|
|
18
|
|
|
19 private import tango.util.collection.model.Dispenser;
|
|
|
20 private import tango.util.collection.model.GuardIterator;
|
|
|
21
|
|
|
22
|
|
|
23 /**
|
|
|
24 * this is the base interface for most classes in this package.
|
|
|
25 *
|
|
|
26 *
|
|
|
27 author: Doug Lea
|
|
|
28 * @version 0.93
|
|
|
29 *
|
|
|
30 * <P> For an introduction to this package see <A HREF="index.html"> Overview </A>.
|
|
|
31 *
|
|
|
32 **/
|
|
|
33 public interface View(T)
|
|
|
34 {
|
|
|
35 /**
|
|
|
36 * All Views implement duplicate
|
|
|
37 **/
|
|
|
38
|
|
|
39 public Dispenser!(T) duplicate ();
|
|
|
40 public alias duplicate dup;
|
|
|
41
|
|
|
42 /**
|
|
|
43 * Report whether the View contains element.
|
|
|
44 * Behaviorally equivalent to <CODE>instances(element) >= 0</CODE>.
|
|
|
45 * @param element the element to look for
|
|
|
46 * Returns: true iff contains at least one member that is equal to element.
|
|
|
47 **/
|
|
|
48 public bool contains (T element);
|
|
|
49 public alias contains opIn;
|
|
|
50
|
|
|
51 /**
|
|
|
52 * Report the number of elements in the View.
|
|
|
53 * No other spurious effects.
|
|
|
54 * Returns: number of elements
|
|
|
55 **/
|
|
|
56 public uint size ();
|
|
|
57 public alias size length;
|
|
|
58
|
|
|
59 /**
|
|
|
60 * Report whether this View has no elements.
|
|
|
61 * Behaviorally equivalent to <CODE>size() == 0</CODE>.
|
|
|
62 * Returns: true if size() == 0
|
|
|
63 **/
|
|
|
64
|
|
|
65 public bool drained ();
|
|
|
66
|
|
|
67
|
|
|
68 /**
|
|
|
69 * All collections maintain a `version number'. The numbering
|
|
|
70 * scheme is arbitrary, but is guaranteed to change upon every
|
|
|
71 * modification that could possibly affect an elements() enumeration traversal.
|
|
|
72 * (This is true at least within the precision of the `int' representation;
|
|
|
73 * performing more than 2^32 operations will lead to reuse of version numbers).
|
|
|
74 * Versioning
|
|
|
75 * <EM>may</EM> be conservative with respect to `replacement' operations.
|
|
|
76 * For the sake of versioning replacements may be considered as
|
|
|
77 * removals followed by additions. Thus version numbers may change
|
|
|
78 * even if the old and new elements are identical.
|
|
|
79 * <P>
|
|
|
80 * All element() enumerations for Mutable Collections track version
|
|
|
81 * numbers, and raise inconsistency exceptions if the enumeration is
|
|
|
82 * used (via get()) on a version other than the one generated
|
|
|
83 * by the elements() method.
|
|
|
84 * <P>
|
|
|
85 * You can use versions to check if update operations actually have any effect
|
|
|
86 * on observable state.
|
|
|
87 * For example, clear() will cause cause a version change only
|
|
|
88 * if the collection was previously non-empty.
|
|
|
89 * Returns: the version number
|
|
|
90 **/
|
|
|
91
|
|
|
92 public uint mutation ();
|
|
|
93
|
|
|
94 /**
|
|
|
95 * Report whether the View COULD contain element,
|
|
|
96 * i.e., that it is valid with respect to the View's
|
|
|
97 * element screener if it has one.
|
|
|
98 * Always returns false if element == null.
|
|
|
99 * A constant function: if allows(v) is ever true it is always true.
|
|
|
100 * (This property is not in any way enforced however.)
|
|
|
101 * No other spurious effects.
|
|
|
102 * Returns: true if non-null and passes element screener check
|
|
|
103 **/
|
|
|
104 public bool allows (T element);
|
|
|
105
|
|
|
106
|
|
|
107 /**
|
|
|
108 * Report the number of occurrences of element in View.
|
|
|
109 * Always returns 0 if element == null.
|
|
|
110 * Otherwise T.equals is used to test for equality.
|
|
|
111 * @param element the element to look for
|
|
|
112 * Returns: the number of occurrences (always nonnegative)
|
|
|
113 **/
|
|
|
114 public uint instances (T element);
|
|
|
115
|
|
|
116 /**
|
|
|
117 * Return an enumeration that may be used to traverse through
|
|
|
118 * the elements in the View. Standard usage, for some
|
|
|
119 * ViewT c, and some operation `use(T obj)':
|
|
|
120 * <PRE>
|
|
|
121 * for (Iterator e = c.elements(); e.more(); )
|
|
|
122 * use(e.value());
|
|
|
123 * </PRE>
|
|
|
124 * (The values of get very often need to
|
|
|
125 * be coerced to types that you know they are.)
|
|
|
126 * <P>
|
|
|
127 * All Views return instances
|
|
|
128 * of ViewIterator, that can report the number of remaining
|
|
|
129 * elements, and also perform consistency checks so that
|
|
|
130 * for MutableViews, element enumerations may become
|
|
|
131 * invalidated if the View is modified during such a traversal
|
|
|
132 * (which could in turn cause random effects on the ViewT.
|
|
|
133 * TO prevent this, ViewIterators
|
|
|
134 * raise CorruptedIteratorException on attempts to access
|
|
|
135 * gets of altered Views.)
|
|
|
136 * Note: Since all View implementations are synchronizable,
|
|
|
137 * you may be able to guarantee that element traversals will not be
|
|
|
138 * corrupted by using the java <CODE>synchronized</CODE> construct
|
|
|
139 * around code blocks that do traversals. (Use with care though,
|
|
|
140 * since such constructs can cause deadlock.)
|
|
|
141 * <P>
|
|
|
142 * Guarantees about the nature of the elements returned by get of the
|
|
|
143 * returned Iterator may vary accross sub-interfaces.
|
|
|
144 * In all cases, the enumerations provided by elements() are guaranteed to
|
|
|
145 * step through (via get) ALL elements in the View.
|
|
|
146 * Unless guaranteed otherwise (for example in Seq), elements() enumerations
|
|
|
147 * need not have any particular get() ordering so long as they
|
|
|
148 * allow traversal of all of the elements. So, for example, two successive
|
|
|
149 * calls to element() may produce enumerations with the same
|
|
|
150 * elements but different get() orderings.
|
|
|
151 * Again, sub-interfaces may provide stronger guarantees. In
|
|
|
152 * particular, Seqs produce enumerations with gets in
|
|
|
153 * index order, ElementSortedViews enumerations are in ascending
|
|
|
154 * sorted order, and KeySortedViews are in ascending order of keys.
|
|
|
155 * Returns: an enumeration e such that
|
|
|
156 * <PRE>
|
|
|
157 * e.remaining() == size() &&
|
|
|
158 * foreach (v in e) has(e)
|
|
|
159 * </PRE>
|
|
|
160 **/
|
|
|
161
|
|
|
162 public GuardIterator!(T) elements ();
|
|
|
163
|
|
|
164 /**
|
|
|
165 traverse the collection content. This is cheaper than using an
|
|
|
166 iterator since there is no creation cost involved.
|
|
|
167 **/
|
|
|
168
|
|
|
169 public int opApply (int delegate (inout T value) dg);
|
|
|
170
|
|
|
171 /**
|
|
|
172 expose collection content as an array
|
|
|
173 **/
|
|
|
174
|
|
|
175 public T[] toArray ();
|
|
|
176
|
|
|
177 /**
|
|
|
178 * Report whether other has the same element structure as this.
|
|
|
179 * That is, whether other is of the same size, and has the same
|
|
|
180 * elements() properties.
|
|
|
181 * This is a useful version of equality testing. But is not named
|
|
|
182 * `equals' in part because it may not be the version you need.
|
|
|
183 * <P>
|
|
|
184 * The easiest way to decribe this operation is just to
|
|
|
185 * explain how it is interpreted in standard sub-interfaces:
|
|
|
186 * <UL>
|
|
|
187 * <LI> Seq and ElementSortedView: other.elements() has the
|
|
|
188 * same order as this.elements().
|
|
|
189 * <LI> Bag: other.elements has the same instances each element as this.
|
|
|
190 * <LI> Set: other.elements has all elements of this
|
|
|
191 * <LI> Map: other has all (key, element) pairs of this.
|
|
|
192 * <LI> KeySortedView: other has all (key, element)
|
|
|
193 * pairs as this, and with keys enumerated in the same order as
|
|
|
194 * this.keys().
|
|
|
195 *</UL>
|
|
|
196 * @param other, a View
|
|
|
197 * Returns: true if considered to have the same size and elements.
|
|
|
198 **/
|
|
|
199
|
|
|
200 public bool matches (View other);
|
|
|
201 public alias matches opEquals;
|
|
|
202
|
|
|
203
|
|
|
204 /**
|
|
|
205 * Check the consistency of internal state, and raise exception if
|
|
|
206 * not OK.
|
|
|
207 * These should be `best-effort' checks. You cannot always locally
|
|
|
208 * determine full consistency, but can usually approximate it,
|
|
|
209 * and validate the most important representation invariants.
|
|
|
210 * The most common kinds of checks are cache checks. For example,
|
|
|
211 * A linked list that also maintains a separate record of the
|
|
|
212 * number of items on the list should verify that the recorded
|
|
|
213 * count matches the number of elements in the list.
|
|
|
214 * <P>
|
|
|
215 * This method should either return normally or throw:
|
|
|
216 * Throws: ImplementationError if check fails
|
|
|
217 **/
|
|
|
218
|
|
|
219 public void checkImplementation();
|
|
|
220 }
|
|
|
221
|
