|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface OrderedCollection<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. |
|
|
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 |
---|
boolean add(E o)
true
if this collection changed as a result of the
call.
This always happens because ordered collections allow duplicates.
o
- - the element to store in the ordered collection
true
if this collection changed as a result of the
call.boolean addAll(OrderedCollection<E> o)
true
if this collection changed as a result of the
call.void clear()
boolean isEmpty()
true
if this ordered collection has no elements.
true
if this ordered collection has no elements.int size()
E remove()
NoSuchElementException
- if the ordered collection is emptyE peek()
NoSuchElementException
- if the ordered collection is emptyboolean equals(java.lang.Object o)
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.
equals
in class java.lang.Object
o
- - Object to be compared for equality with this collection.
true
if the specified object is equal to this
collectionObject.equals(Object)
int hashCode()
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.hashCode
method.
In particular, c1.equals(c2)
implies that
c1.hashCode()==c2.hashCode()
.
hashCode
in class java.lang.Object
Object.hashCode()
,
Object.equals(Object)
java.util.Iterator<E> iterator()
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).
iterator
in interface java.lang.Iterable<E>
iterator
over the elements in this ordered
collectionjava.lang.Object[] toArray()
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.
<T> T[] toArray(T[] a)
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.
java.util.Collection toCollection()
This method acts as bridge between collection-based and ordred collection-based APIs.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |