Mercurial > projects > ldc

comparison tango/tango/util/collection/model/Dispenser.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: 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