Mercurial > projects > ldc

comparison tango/tango/util/collection/model/View.d @ 132:1700239cab2e trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[svn r136] MAJOR UNSTABLE UPDATE!!! Initial commit after moving to Tango instead of Phobos. Lots of bugfixes... This build is not suitable for most things.
author lindquist
date Fri, 11 Jan 2008 17:57:40 +0100
parents
children
comparison
equal deleted inserted replaced
131:5825d48b27d1 132:1700239cab2e
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) &gt;= 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