edu.cmu.cs.pattis.cs151xx.orderedCollections
Interface OrderedCollection<E>

All Superinterfaces:
java.lang.Iterable<E>
All Known Implementing Classes:
AbstractOrderedCollection, AbstractPriorityQueue, AbstractQueue, AbstractStack, ArrayPriorityQueue, ArrayQueue, ArrayStack, ArrayUnsortedPriorityQueue, LinkedQueue, LinkedStack

public interface OrderedCollection<E>
extends java.lang.Iterable<E>

The root interface in the ordered collection hierarchy. An ordered collection represents a group of objects, known as its elements. Ordered collections allow duplicate elements. This interface is typically used to pass ordered collections around and manipulate them where maximum generality is desired.

All general-purpose OrderedCollection implementation classes (which typically implement OrdredCollection directly) should provide two "standard" constructors: a void (no arguments) constructor, which creates an empty ordred collection, and a constructor with a single argument of type OrdredCollection, which creates a new ordred collection with the same elements as its argument. In effect, the latter constructor allows the user to copy any collection, producing an equivalent collection of the desired implementation type. There is no way to enforce this convention (as interfaces cannot contain constructors) but all of the general-purpose OrderedCollection implementations provide here comply.


Method Summary
 boolean add(E o)
          Ensures that this ordered collection contains the specified element.
 boolean addAll(OrderedCollection<E> o)
          Adds all of the elements in the specified ordered collection to this collection.
 void clear()
          Removes all of the elements from this ordered collection.
 boolean equals(java.lang.Object o)
          Compares the specified object with this collection for equality.
 int hashCode()
          Returns the hash code value for this collection.
 boolean isEmpty()
          Returns true if this ordered collection has no elements.
 java.util.Iterator<E> iterator()
          Returns an iterator over the elements in this ordered collection.
 E peek()
          Returns (without removing) the next elements in this ordered collection, according to how it is ordered.
 E remove()
          Returns/removes the next element in this ordered collection, according to how it is ordered.
 int size()
          Returns the number of elements in this ordered collection.
 java.lang.Object[] toArray()
          Returns an array containing all of the elements in this ordered collection, in order.
<T> T[]
toArray(T[] a)
          Returns an array containing all of the elements in this ordered collection, in order, whose runtime type is that of the specified array.
 java.util.Collection toCollection()
          Returns a collection containing all of the elements in this ordered collection.
 

Method Detail

add

boolean add(E o)
Ensures that this ordered collection contains the specified element. Returns true if this collection changed as a result of the call. This always happens because ordered collections allow duplicates.

Parameters:
o - - the element to store in the ordered collection
Returns:
true if this collection changed as a result of the call.

addAll

boolean addAll(OrderedCollection<E> o)
Adds all of the elements in the specified ordered collection to this collection. The behavior of this operation is undefined if the specified ordered collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified ordered collection is this collection, and this collection is nonempty.)

Returns:
true if this collection changed as a result of the call.

clear

void clear()
Removes all of the elements from this ordered collection. This collection will be empty after this method returns


isEmpty

boolean isEmpty()
Returns true if this ordered collection has no elements.

Returns:
true if this ordered collection has no elements.

size

int size()
Returns the number of elements in this ordered collection.

Returns:
the number of elements in this collection

remove

E remove()
Returns/removes the next element in this ordered collection, according to how it is ordered.

Returns:
the next element in this ordered collection, according to how it is ordered.
Throws:
NoSuchElementException - if the ordered collection is empty

peek

E peek()
Returns (without removing) the next elements in this ordered collection, according to how it is ordered.

Returns:
the next element in this ordered collection, according to how it is ordered.
Throws:
NoSuchElementException - if the ordered collection is empty

equals

boolean equals(java.lang.Object o)
Compares the specified object with this collection for equality.

While the Collection interface adds no stipulations to the general contract for the Object.equals, programmers who implement the Collection interface "directly" (in other words, create a class that is a Collection but is not a Stack or a Queuet or PriorityQueue) must exercise care if they choose to override the Object.equals. It is not necessary to do so, and the simplest course of action is to rely on Object's implementation, but the implementer may wish to implement a "value comparison" in place of the default "reference comparison."

The general contract for the Object.equals method states that equals must be symmetric (in other words, a.equals(b) if and only if b.equals(a)). The contracts for Stack.equals, for instance, states that stacks are only equal to other stacks.

Overrides:
equals in class java.lang.Object
Parameters:
o - - Object to be compared for equality with this collection.
Returns:
true if the specified object is equal to this collection
See Also:
Object.equals(Object)

hashCode

int hashCode()
Returns the hash code value for this collection. While the Collection interface adds no stipulations to the general contract for the Object.hashCode method, programmers should take note that any class that overrides the Object.equals method must also override the Object.hashCode method in order to satisfy the general contract for the Object.hashCodemethod. In particular, c1.equals(c2) implies that c1.hashCode()==c2.hashCode().

Overrides:
hashCode in class java.lang.Object
Returns:
the hash code value for this collection
See Also:
Object.hashCode(), Object.equals(Object)

iterator

java.util.Iterator<E> iterator()
Returns an iterator over the elements in this ordered collection. There are no guarantees concerning the order in which the elements are returned (unless this ordered collection is an instance of some class that provides a guarantee).

Specified by:
iterator in interface java.lang.Iterable<E>
Returns:
an iterator over the elements in this ordered collection

toArray

java.lang.Object[] toArray()
Returns an array containing all of the elements in this ordered collection, in order. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Returns:
an array containing the elements of this ordered collection

toArray

<T> T[] toArray(T[] a)
Returns an array containing all of the elements in this ordered collection, in order, whose runtime type is that of the specified array.

If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

Returns:
an array containing the elements of this ordred collection

toCollection

java.util.Collection toCollection()
Returns a collection containing all of the elements in this ordered collection. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

This method acts as bridge between collection-based and ordred collection-based APIs.

Returns:
a collection containing the elements of this ordred collection