All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface collections.UpdatableCollection

public interface interface UpdatableCollection

extends Collection

clear()

Cause the collection to become empty.

exclude(Object)

Exclude all occurrences of the indicated element from the collection.

excludeElements(Enumeration)

Exclude all occurrences of each element of the Enumeration.

removeElements(Enumeration)

Remove an occurrence of each element of the Enumeration.

removeOneOf(Object)

Remove an instance of the indicated element from the collection.

replaceAllOf(Object, Object)

Replace all occurrences of oldElement with newElement.

replaceOneOf(Object, Object)

Replace an occurrence of oldElement with newElement.

take()

Remove and return an element.

version()

All updatable collections maintain a `version number'.

 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

 public abstract void clear()

Cause the collection to become empty.

Returns:

condition:

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

 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)
 

 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
 

 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)

 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)

 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.

 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
  

 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