All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface collections.Collection

public interface interface Collection

extends ImplementationCheckable, Cloneable, Serializable

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.

 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

 public abstract int size()

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

Returns:

number of elements

 public abstract boolean isEmpty()

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

Returns:

true iff size() == 0

 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

 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)

 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.

 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) 
 

 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.

 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).

 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)

 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)

 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