tango.util.collection.model.Dispenser

interface Dispenser(T) : View!(T) ¶#

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

For an introduction to this package see Overview .

void clear() [public] ¶#

Cause the collection to become empty.

Returns:

condition:

 isEmpty() &&
 Version change iff !PREV(this).isEmpty();
 

void replace(T oldElement, T newElement) [public] ¶#

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:

 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
 

Throws:

IllegalElementException if has(oldElement) and !allows(newElement)

void replaceAll(T oldElement, T newElement) [public] ¶#

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:

 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
 

Throws:

IllegalElementException if has(oldElement) and !allows(newElement)

T take() [public] ¶#

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.

Example usage. One way to transfer all elements from Dispenser a to MutableBag b is:

 while (!a.empty()) b.add(a.take());
 

Returns:

an element v such that PREV(this).has(v) and the postconditions of removeOneOf(v) hold.

Throws:

NoSuchElementException iff isEmpty.

void removeAll(Iterator!(T) e) [public] ¶#

Exclude all occurrences of each element of the Iterator. Behaviorally equivalent to

 while (e.more()) removeAll(e.value());
 @param e the enumeration of elements to exclude.

Throws:

CorruptedIteratorException is propagated if thrown

void remove(Iterator!(T) e) [public] ¶#

Remove an occurrence of each element of the Iterator. Behaviorally equivalent to

 while (e.more()) remove (e.value());
 @param e the enumeration of elements to remove.

Throws:

CorruptedIteratorException is propagated if thrown

void removeAll(T element) [public] ¶#

Exclude all occurrences of the indicated element from the collection. No effect if element not present. @param element the element to exclude.

Returns:

condition:

 !has(element) &&
 size() == PREV(this).size() - PREV(this).instances(element) &&
 no other element changes &&
 Version change iff PREV(this).has(element)
 

void remove(T element) [public] ¶#

Remove an instance of the indicated element from the collection. No effect if !has(element) @param element the element to remove

Returns:

condition:

 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