    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Interface collections.Collection

public interface interface Collection
extends ImplementationCheckable, Cloneable, Serializable

Collection is the base interface for most classes in this package.

##

canInclude(Object)
  Report whether the collection COULD contain element, i.e., that it is valid with respect to the Collection's element screener if it has one.
duplicate()
  public version of java.lang.Object.clone All Collections implement clone.
elements()
  Return an enumeration that may be used to traverse through the elements in the collection.
excluding(Object)
  Construct a new Collection that is a clone of self except that it does not include any occurrences of the indicated element.
includes(Object)
  Report whether the collection contains element.
isEmpty()
  Report whether this collection has no elements.
occurrencesOf(Object)
  Report the number of occurrences of element in collection.
removingOneOf(Object)
  Construct a new Collection that is a clone of self except that it does not include an occurrence of the indicated element.
replacingAllOf(Object, Object)
  Construct a new Collection that is a clone of self except that all occurrences of oldElement are replaced with newElement.
replacingOneOf(Object, Object)
  Construct a new Collection that is a clone of self except that one occurrence of oldElement is replaced with newElement.
sameStructure(Collection)
  Report whether other has the same element structure as this.
size()
  Report the number of elements in the collection.

##

duplicate

     public abstract Collection duplicate()

  public version of java.lang.Object.clone All Collections implement clone. But this is a protected method. Duplicate allows public access.

  See Also:
    clone

size

     public abstract int size()

  Report the number of elements in the collection. No other spurious effects.

  Returns:
    number of elements

isEmpty

     public abstract boolean isEmpty()

  Report whether this collection has no elements. Behaviorally equivalent to `size() == 0`.

  Returns:
    true iff size() == 0

canInclude

     public abstract boolean canInclude(Object element)

  Report whether the collection COULD contain element, i.e., that it is valid with respect to the Collection's element screener if it has one. Always returns false if element == null. A constant function: if canInclude(v) is ever true it is always true. (This property is not in any way enforced however.) No other spurious effects.

  Returns:
    true if non-null and passes element screener check

occurrencesOf

     public abstract int occurrencesOf(Object element)

  Report the number of occurrences of element in collection. Always returns 0 if element == null. Otherwise Object.equals is used to test for equality.

  Parameters:
    element - the element to look for
  Returns:
    the number of occurrences (always nonnegative)

includes

     public abstract boolean includes(Object element)

  Report whether the collection contains element. Behaviorally equivalent to `occurrencesOf(element) >= 0`.

  Parameters:
    element - the element to look for
  Returns:
    true iff contains at least one member that is equal to element.

elements

     public abstract CollectionEnumeration elements()

  Return an enumeration that may be used to traverse through the elements in the collection. Standard usage, for some collection c, and some operation `use(Object obj)':

       for (Enumeration e = c.elements(); e.hasMoreElements(); )
         use(e.nextElement());

  (The values of nextElement very often need to be coerced to types that you know they are.)

  All Collections return instances of CollectionEnumeration, that can report the number of remaining elements, and also perform consistency checks so that for UpdatableCollections, element enumerations may become invalidated if the collection is modified during such a traversal (which could in turn cause random effects on the collection. TO prevent this, CollectionEnumerations raise CorruptedEnumerationException on attempts to access nextElements of altered Collections.) Note: Since all collection implementations are synchronizable, you may be able to guarantee that element traversals will not be corrupted by using the java `synchronized` construct around code blocks that do traversals. (Use with care though, since such constructs can cause deadlock.)

  Guarantees about the nature of the elements returned by nextElement of the returned Enumeration may vary accross sub-interfaces. In all cases, the enumerations provided by elements() are guaranteed to step through (via nextElement) ALL elements in the collection. Unless guaranteed otherwise (for example in Seq), elements() enumerations need not have any particular nextElement() ordering so long as they allow traversal of all of the elements. So, for example, two successive calls to element() may produce enumerations with the same elements but different nextElement() orderings. Again, sub-interfaces may provide stronger guarantees. In particular, Seqs produce enumerations with nextElements in index order, ElementSortedCollections enumerations are in ascending sorted order, and KeySortedCollections are in ascending order of keys.

  Returns:
    an enumeration e such that

           e.numberOfRemainingElements() == size() &&
           foreach (v in e) includes(e)

sameStructure

     public abstract boolean sameStructure(Collection other)

  Report whether other has the same element structure as this. That is, whether other is of the same size, and has the same elements() properties. This is a useful version of equality testing. But is not named `equals' in part because it may not be the version you need.

  The easiest way to decribe this operation is just to explain how it is interpreted in standard sub-interfaces:

  - Seq and ElementSortedCollection: other.elements() has the same order as this.elements().
  - Bag: other.elements has the same occurrencesOf each element as this.
  - Set: other.elements includes all elements of this
  - Map: other includes all (key, element) pairs of this.
  - KeySortedCollection: other includes all (key, element) pairs as this, and with keys enumerated in the same order as this.keys().

  Parameters:
    other, - a Collection
  Returns:
    true if considered to have the same size and elements.

excluding

     public abstract Collection excluding(Object element)

  Construct a new Collection that is a clone of self except that it does not include any occurrences of the indicated element. It is NOT an error to exclude a non-existent element.

  Parameters:
    element - the element to exclude from the new collection
  Returns:
    a new Collection, c, with the sameStructure as this except that !c.includes(element).

removingOneOf

     public abstract Collection removingOneOf(Object element)

  Construct a new Collection that is a clone of self except that it does not include an occurrence of the indicated element. It is NOT an error to remove a non-existent element.

  Parameters:
    element - the element to exclude from the new collection
  Returns:
    a new Collection, c, with the sameStructure as this except that c.occurrencesOf(element) == max(0,occurrencesOf(element)-1)

replacingOneOf

     public abstract Collection replacingOneOf(Object oldElement,
                                               Object newElement) throws IllegalElementException

  Construct a new Collection that is a clone of self except that one occurrence of oldElement is replaced with newElement. It is NOT an error to replace a non-existent element.

  Parameters:
    oldElement - the element to replace
    newElement - the replacement
  Returns:
    a new Collection, c, with the sameStructure as this, except:

         let int delta = oldElement.equals(newElement)? 0 :
                       max(1, this.occurrencesOf(oldElement) in
          c.occurrencesOf(oldElement) == this.occurrencesOf(oldElement) - delta &&
          c.occurrencesOf(newElement) ==  (this instanceof Set) ?
                 max(1, this.occurrencesOf(oldElement) + delta):
                        this.occurrencesOf(oldElement) + delta) &&

  Throws: IllegalElementException
    if includes(oldElement) and !canInclude(newElement)

replacingAllOf

     public abstract Collection replacingAllOf(Object oldElement,
                                               Object newElement) throws IllegalElementException

  Construct a new Collection that is a clone of self except that all occurrences of oldElement are replaced with newElement. It is NOT an error to convert a non-existent element.

  Parameters:
    oldElement - the element to replace
    newElement - the replacement
  Returns:
    a new Collection, c, with the sameStructure as this except

         let int delta = oldElement.equals(newElement)? 0 :
        occurrencesOf(oldElement) in
          c.occurrencesOf(oldElement) == this.occurrencesOf(oldElement) - delta &&
          c.occurrencesOf(newElement) ==  (this instanceof Set) ?
                 max(1, this.occurrencesOf(oldElement) + delta):
                        this.occurrencesOf(oldElement) + delta)

  Throws: IllegalElementException
    if includes(oldElement) and !canInclude(newElement)

    All Packages  Class Hierarchy  This Package  Previous  Next  Index