|
132
|
1 /*
|
|
|
2 File: Dispenser.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
|
|
|
12 */
|
|
|
13
|
|
|
14
|
|
|
15 module tango.util.collection.model.Dispenser;
|
|
|
16
|
|
|
17 private import tango.util.collection.model.View,
|
|
|
18 tango.util.collection.model.Iterator;
|
|
|
19
|
|
|
20 /**
|
|
|
21 *
|
|
|
22 * Dispenser is the root interface of all mutable collections; i.e.,
|
|
|
23 * collections that may have elements dynamically added, removed,
|
|
|
24 * and/or replaced in accord with their collection semantics.
|
|
|
25 *
|
|
|
26 * author: Doug Lea
|
|
|
27 *
|
|
|
28 * <P> For an introduction to this package see <A HREF="index.html"> Overview </A>.
|
|
|
29 **/
|
|
|
30
|
|
|
31 public interface Dispenser(T) : View!(T)
|
|
|
32 {
|
|
|
33 /**
|
|
|
34 * Cause the collection to become empty.
|
|
|
35 * Returns: condition:
|
|
|
36 * <PRE>
|
|
|
37 * isEmpty() &&
|
|
|
38 * Version change iff !PREV(this).isEmpty();
|
|
|
39 * </PRE>
|
|
|
40 **/
|
|
|
41
|
|
|
42 public void clear ();
|
|
|
43
|
|
|
44 /**
|
|
|
45 * Replace an occurrence of oldElement with newElement.
|
|
|
46 * No effect if does not hold oldElement or if oldElement.equals(newElement).
|
|
|
47 * The operation has a consistent, but slightly special interpretation
|
|
|
48 * when applied to Sets. For Sets, because elements occur at
|
|
|
49 * most once, if newElement is already included, replacing oldElement with
|
|
|
50 * with newElement has the same effect as just removing oldElement.
|
|
|
51 * Returns: condition:
|
|
|
52 * <PRE>
|
|
|
53 * let int delta = oldElement.equals(newElement)? 0 :
|
|
|
54 * max(1, PREV(this).instances(oldElement) in
|
|
|
55 * instances(oldElement) == PREV(this).instances(oldElement) - delta &&
|
|
|
56 * instances(newElement) == (this instanceof Set) ?
|
|
|
57 * max(1, PREV(this).instances(oldElement) + delta):
|
|
|
58 * PREV(this).instances(oldElement) + delta) &&
|
|
|
59 * no other element changes &&
|
|
|
60 * Version change iff delta != 0
|
|
|
61 * </PRE>
|
|
|
62 * Throws: IllegalElementException if has(oldElement) and !allows(newElement)
|
|
|
63 **/
|
|
|
64
|
|
|
65 public void replace (T oldElement, T newElement);
|
|
|
66
|
|
|
67 /**
|
|
|
68 * Replace all occurrences of oldElement with newElement.
|
|
|
69 * No effect if does not hold oldElement or if oldElement.equals(newElement).
|
|
|
70 * The operation has a consistent, but slightly special interpretation
|
|
|
71 * when applied to Sets. For Sets, because elements occur at
|
|
|
72 * most once, if newElement is already included, replacing oldElement with
|
|
|
73 * with newElement has the same effect as just removing oldElement.
|
|
|
74 * Returns: condition:
|
|
|
75 * <PRE>
|
|
|
76 * let int delta = oldElement.equals(newElement)? 0 :
|
|
|
77 PREV(this).instances(oldElement) in
|
|
|
78 * instances(oldElement) == PREV(this).instances(oldElement) - delta &&
|
|
|
79 * instances(newElement) == (this instanceof Set) ?
|
|
|
80 * max(1, PREV(this).instances(oldElement) + delta):
|
|
|
81 * PREV(this).instances(oldElement) + delta) &&
|
|
|
82 * no other element changes &&
|
|
|
83 * Version change iff delta != 0
|
|
|
84 * </PRE>
|
|
|
85 * Throws: IllegalElementException if has(oldElement) and !allows(newElement)
|
|
|
86 **/
|
|
|
87
|
|
|
88 public void replaceAll(T oldElement, T newElement);
|
|
|
89
|
|
|
90 /**
|
|
|
91 * Remove and return an element. Implementations
|
|
|
92 * may strengthen the guarantee about the nature of this element.
|
|
|
93 * but in general it is the most convenient or efficient element to remove.
|
|
|
94 * <P>
|
|
|
95 * Example usage. One way to transfer all elements from
|
|
|
96 * Dispenser a to MutableBag b is:
|
|
|
97 * <PRE>
|
|
|
98 * while (!a.empty()) b.add(a.take());
|
|
|
99 * </PRE>
|
|
|
100 * Returns: an element v such that PREV(this).has(v)
|
|
|
101 * and the postconditions of removeOneOf(v) hold.
|
|
|
102 * Throws: NoSuchElementException iff isEmpty.
|
|
|
103 **/
|
|
|
104
|
|
|
105 public T take ();
|
|
|
106
|
|
|
107
|
|
|
108 /**
|
|
|
109 * Exclude all occurrences of each element of the Iterator.
|
|
|
110 * Behaviorally equivalent to
|
|
|
111 * <PRE>
|
|
|
112 * while (e.more()) removeAll(e.value());
|
|
|
113 * @param e the enumeration of elements to exclude.
|
|
|
114 * Throws: CorruptedIteratorException is propagated if thrown
|
|
|
115 **/
|
|
|
116
|
|
|
117 public void removeAll (Iterator!(T) e);
|
|
|
118
|
|
|
119 /**
|
|
|
120 * Remove an occurrence of each element of the Iterator.
|
|
|
121 * Behaviorally equivalent to
|
|
|
122 * <PRE>
|
|
|
123 * while (e.more()) remove (e.value());
|
|
|
124 * @param e the enumeration of elements to remove.
|
|
|
125 * Throws: CorruptedIteratorException is propagated if thrown
|
|
|
126 **/
|
|
|
127
|
|
|
128 public void remove (Iterator!(T) e);
|
|
|
129
|
|
|
130 /**
|
|
|
131 * Exclude all occurrences of the indicated element from the collection.
|
|
|
132 * No effect if element not present.
|
|
|
133 * @param element the element to exclude.
|
|
|
134 * Returns: condition:
|
|
|
135 * <PRE>
|
|
|
136 * !has(element) &&
|
|
|
137 * size() == PREV(this).size() - PREV(this).instances(element) &&
|
|
|
138 * no other element changes &&
|
|
|
139 * Version change iff PREV(this).has(element)
|
|
|
140 * </PRE>
|
|
|
141 **/
|
|
|
142
|
|
|
143 public void removeAll (T element);
|
|
|
144
|
|
|
145
|
|
|
146 /**
|
|
|
147 * Remove an instance of the indicated element from the collection.
|
|
|
148 * No effect if !has(element)
|
|
|
149 * @param element the element to remove
|
|
|
150 * Returns: condition:
|
|
|
151 * <PRE>
|
|
|
152 * let occ = max(1, instances(element)) in
|
|
|
153 * size() == PREV(this).size() - occ &&
|
|
|
154 * instances(element) == PREV(this).instances(element) - occ &&
|
|
|
155 * no other element changes &&
|
|
|
156 * version change iff occ == 1
|
|
|
157 * </PRE>
|
|
|
158 **/
|
|
|
159
|
|
|
160 public void remove (T element);
|
|
|
161 }
|
|
|
162
|
|
|
163
|
