Mercurial > projects > ldc
diff tango/tango/util/collection/model/Dispenser.d @ 132:1700239cab2e trunk
[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 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tango/tango/util/collection/model/Dispenser.d Fri Jan 11 17:57:40 2008 +0100 @@ -0,0 +1,163 @@ +/* + File: Dispenser.d + + Originally written by Doug Lea and released into the public domain. + Thanks for the assistance and support of Sun Microsystems Labs, Agorics + Inc, Loral, and everyone contributing, testing, and using this code. + + History: + Date Who What + 24Sep95 dl@cs.oswego.edu Create from collections.d working file + +*/ + + +module tango.util.collection.model.Dispenser; + +private import tango.util.collection.model.View, + tango.util.collection.model.Iterator; + +/** + * + * Dispenser is the root interface of all mutable collections; i.e., + * collections that may have elements dynamically added, removed, + * and/or replaced in accord with their collection semantics. + * + * author: Doug Lea + * + * <P> For an introduction to this package see <A HREF="index.html"> Overview </A>. +**/ + +public interface Dispenser(T) : View!(T) +{ + /** + * Cause the collection to become empty. + * Returns: condition: + * <PRE> + * isEmpty() && + * Version change iff !PREV(this).isEmpty(); + * </PRE> + **/ + + public void clear (); + + /** + * Replace an occurrence of oldElement with newElement. + * No effect if does not hold oldElement or if oldElement.equals(newElement). + * The operation has a consistent, but slightly special interpretation + * when applied to Sets. For Sets, because elements occur at + * most once, if newElement is already included, replacing oldElement with + * with newElement has the same effect as just removing oldElement. + * Returns: condition: + * <PRE> + * let int delta = oldElement.equals(newElement)? 0 : + * max(1, PREV(this).instances(oldElement) in + * instances(oldElement) == PREV(this).instances(oldElement) - delta && + * instances(newElement) == (this instanceof Set) ? + * max(1, PREV(this).instances(oldElement) + delta): + * PREV(this).instances(oldElement) + delta) && + * no other element changes && + * Version change iff delta != 0 + * </PRE> + * Throws: IllegalElementException if has(oldElement) and !allows(newElement) + **/ + + public void replace (T oldElement, T newElement); + + /** + * Replace all occurrences of oldElement with newElement. + * No effect if does not hold oldElement or if oldElement.equals(newElement). + * The operation has a consistent, but slightly special interpretation + * when applied to Sets. For Sets, because elements occur at + * most once, if newElement is already included, replacing oldElement with + * with newElement has the same effect as just removing oldElement. + * Returns: condition: + * <PRE> + * let int delta = oldElement.equals(newElement)? 0 : + PREV(this).instances(oldElement) in + * instances(oldElement) == PREV(this).instances(oldElement) - delta && + * instances(newElement) == (this instanceof Set) ? + * max(1, PREV(this).instances(oldElement) + delta): + * PREV(this).instances(oldElement) + delta) && + * no other element changes && + * Version change iff delta != 0 + * </PRE> + * Throws: IllegalElementException if has(oldElement) and !allows(newElement) + **/ + + public void replaceAll(T oldElement, T newElement); + + /** + * Remove and return an element. Implementations + * may strengthen the guarantee about the nature of this element. + * but in general it is the most convenient or efficient element to remove. + * <P> + * Example usage. One way to transfer all elements from + * Dispenser a to MutableBag b is: + * <PRE> + * while (!a.empty()) b.add(a.take()); + * </PRE> + * Returns: an element v such that PREV(this).has(v) + * and the postconditions of removeOneOf(v) hold. + * Throws: NoSuchElementException iff isEmpty. + **/ + + public T take (); + + + /** + * Exclude all occurrences of each element of the Iterator. + * Behaviorally equivalent to + * <PRE> + * while (e.more()) removeAll(e.value()); + * @param e the enumeration of elements to exclude. + * Throws: CorruptedIteratorException is propagated if thrown + **/ + + public void removeAll (Iterator!(T) e); + + /** + * Remove an occurrence of each element of the Iterator. + * Behaviorally equivalent to + * <PRE> + * while (e.more()) remove (e.value()); + * @param e the enumeration of elements to remove. + * Throws: CorruptedIteratorException is propagated if thrown + **/ + + public void remove (Iterator!(T) e); + + /** + * Exclude all occurrences of the indicated element from the collection. + * No effect if element not present. + * @param element the element to exclude. + * Returns: condition: + * <PRE> + * !has(element) && + * size() == PREV(this).size() - PREV(this).instances(element) && + * no other element changes && + * Version change iff PREV(this).has(element) + * </PRE> + **/ + + public void removeAll (T element); + + + /** + * Remove an instance of the indicated element from the collection. + * No effect if !has(element) + * @param element the element to remove + * Returns: condition: + * <PRE> + * let occ = max(1, instances(element)) in + * size() == PREV(this).size() - occ && + * instances(element) == PREV(this).instances(element) - occ && + * no other element changes && + * version change iff occ == 1 + * </PRE> + **/ + + public void remove (T element); +} + +