All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface collections.UpdatableCollection

public interface interface UpdatableCollection
extends Collection
UpdatableCollection 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.


Method Index

 o clear()
Cause the collection to become empty.
 o exclude(Object)
Exclude all occurrences of the indicated element from the collection.
 o excludeElements(Enumeration)
Exclude all occurrences of each element of the Enumeration.
 o removeElements(Enumeration)
Remove an occurrence of each element of the Enumeration.
 o removeOneOf(Object)
Remove an instance of the indicated element from the collection.
 o replaceAllOf(Object, Object)
Replace all occurrences of oldElement with newElement.
 o replaceOneOf(Object, Object)
Replace an occurrence of oldElement with newElement.
 o take()
Remove and return an element.
 o version()
All updatable collections maintain a `version number'.

Methods

 o version
 public abstract int version()
All updatable collections maintain a `version number'. The numbering scheme is arbitrary, but is guaranteed to change upon every modification that could possibly affect an elements() enumeration traversal. (This is true at least within the precision of the `int' representation; performing more than 2^32 operations will lead to reuse of version numbers). Versioning may be conservative with respect to `replacement' operations. For the sake of versioning replacements may be considered as removals followed by additions. Thus version numbers may change even if the old and new elements are identical.

All element() enumerations for Updatable Collections track version numbers, and raise inconsistency exceptions if the enumeration is used (via nextElement()) on a version other than the one generated by the elements() method.

You can use versions to check if update operations actually have any effect on observable state. For example, clear() will cause cause a version change only if the collection was previously non-empty.

Returns:
the version number
 o clear
 public abstract void clear()
Cause the collection to become empty.

Returns:
condition:
 isEmpty() &&
 Version change iff !PREV(this).isEmpty();
 
 o exclude
 public abstract void exclude(Object element)
Exclude all occurrences of the indicated element from the collection. No effect if element not present.

Parameters:
element - the element to exclude.
Returns:
condition:
 !includes(element) &&
 size() == PREV(this).size() - PREV(this).occurrencesOf(element) &&
 no other element changes &&
 Version change iff PREV(this).includes(element)
 
 o removeOneOf
 public abstract void removeOneOf(Object element)
Remove an instance of the indicated element from the collection. No effect if !includes(element)

Parameters:
element - the element to remove
Returns:
condition:
 let occ = max(1, occurrencesOf(element)) in
  size() == PREV(this).size() - occ &&
  occurrencesOf(element) == PREV(this).occurrencesOf(element) - occ &&
  no other element changes &&
  version change iff occ == 1
 
 o replaceOneOf
 public abstract void replaceOneOf(Object oldElement,
                                   Object newElement) throws IllegalElementException
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).occurrencesOf(oldElement) in
  occurrencesOf(oldElement) == PREV(this).occurrencesOf(oldElement) - delta &&
  occurrencesOf(newElement) ==  (this instanceof Set) ? 
         max(1, PREV(this).occurrencesOf(oldElement) + delta):
                PREV(this).occurrencesOf(oldElement) + delta) &&
  no other element changes &&
  Version change iff delta != 0
 
Throws: IllegalElementException
if includes(oldElement) and !canInclude(newElement)
 o replaceAllOf
 public abstract void replaceAllOf(Object oldElement,
                                   Object newElement) throws IllegalElementException
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).occurrencesOf(oldElement) in
  occurrencesOf(oldElement) == PREV(this).occurrencesOf(oldElement) - delta &&
  occurrencesOf(newElement) ==  (this instanceof Set) ? 
         max(1, PREV(this).occurrencesOf(oldElement) + delta):
                PREV(this).occurrencesOf(oldElement) + delta) &&
  no other element changes &&
  Version change iff delta != 0
 
Throws: IllegalElementException
if includes(oldElement) and !canInclude(newElement)
 o take
 public abstract Object take() throws NoSuchElementException
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 UpdatableCollection a to UpdatableBag b is:

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

Returns:
an element v such that PREV(this).includes(v) and the postconditions of removeOneOf(v) hold.
Throws: NoSuchElementException
iff isEmpty.
 o excludeElements
 public abstract void excludeElements(Enumeration e) throws CorruptedEnumerationException
Exclude all occurrences of each element of the Enumeration. Behaviorally equivalent to
 while (e.hasMoreElements()) exclude(e.nextElement());

Parameters:
e - the enumeration of elements to exclude.
Throws: CorruptedEnumerationException
is propagated if thrown
 o removeElements
 public abstract void removeElements(Enumeration e) throws CorruptedEnumerationException
Remove an occurrence of each element of the Enumeration. Behaviorally equivalent to
 while (e.hasMoreElements()) removeOneOf(e.nextElement());

Parameters:
e - the enumeration of elements to remove.
Throws: CorruptedEnumerationException
is propagated if thrown

All Packages  Class Hierarchy  This Package  Previous  Next  Index