jaggregate
Interface Collection<E>

Type Parameters:

E - a restriction on the types of elements that may be included in the collection

All Known Subinterfaces:

AbstractDictionary<K,V>, ContractibleSequence<E>, ExtensibleCollection<E>, ReadOnlySequence<E>, Sequence<E>

All Known Implementing Classes:

AbstractBag, AbstractCollection, AbstractDictionaryImpl, AbstractExtensibleCollection, AbstractSet, Bag, Dictionary, IdentityBag, IdentityDictionary, IdentitySet, Interval, NaturallySortedCollection, OrderedCollection, Set, SortedCollection

public interface Collection<E>

Provides protocol for manipulating and operating on a collection of objects, called elements, either individually or as a whole. A collection can be fixed or variable-sized, ordered or unordered, and its elements may or may not be accessible by external keys.

Some implementations of collections may choose to use the hash values of either the elements of the collection or the keys by which those elements are accessed (if there are any). If the hash values of such objects are modified, the behavior of any message sent to such a collection is undefined until the collection is rehashed in order to restore its consistency.

Version:

$Id: Collection.java,v 1.7 2008/05/12 23:49:07 pholser Exp $

Author:

Paul Holser

Method Summary

boolean	allSatisfy(UnaryCondition<? super E> discriminator) Answers true if the given discriminator answers true for every element of this collection, or if this collection is empty; otherwise answers false.
boolean	anySatisfy(UnaryCondition<? super E> discriminator) Answers true if the given discriminator answers true for any element of this collection; answers false otherwise, or if this collection is empty.
<R> Collection<R>	collect(UnaryFunctor<? super E,? extends R> transformer) Evaluates the given transformer for each element of this collection, with the element as the parameter, and answers a new collection containing the results of these evaluations.
E	detect(UnaryCondition<? super E> discriminator) Answers the first element of this collection for which the given discriminator answers true when given that element as an argument.
void	forEachDo(UnaryFunctor<? super E,?> operation) For each element of this collection, evaluates the given operation with the element as the parameter.
boolean	includes(E target) Answers true if an element of this collection is equivalent to the given one; answers false otherwise.
<R> R	inject(R initialValue, BinaryFunctor<? super R,? super E,? extends R> operation) Answers the final result of evaluating the given operation using each element of this collection and the previous evaluation result as the parameters.
boolean	isEmpty() Answers true iff this collection's size is zero; otherwise answers false.
int	occurrencesOf(E target) Answers the number of elements of this collection which are equivalent to the given target.
void	rehash() Re-establishes any hash invariants of this collection.
Collection<E>	reject(UnaryCondition<? super E> discriminator) Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer false.
Collection<E>	select(UnaryCondition<? super E> discriminator) Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer true.
int	size() Answers the number of elements in this collection.
Object[]	toArray() Answers an array with the same elements as this collection, with the same size as this collection, and a component class of Object.
Object[]	toArray(Class<? super E> componentClass) Answers an array with the same elements as this collection, with the same size as this collection, and a component type of the given class.
Bag<E>	toBag() Answers a bag with the same elements as this collection.
IdentityBag<E>	toIdentityBag() Answers an identity bag with the same elements as this collection.
IdentitySet<E>	toIdentitySet() Answers an identity set with the same elements as this collection.
OrderedCollection<E>	toOrderedCollection() Answers an ordered collection with the same elements as this collection.
Set<E>	toSet() Answers a set with the same elements as this collection.
SortedCollection<E>	toSortedCollection() Answers a sorted collection with the same elements as this collection.
SortedCollection<E>	toSortedCollection(Comparator<? super E> comparator) Answers a sorted collection with the same elements as this collection, using the given comparator to order the elements.

Method Detail

allSatisfy

boolean allSatisfy(UnaryCondition<? super E> discriminator)

Answers true if the given discriminator answers true for every element of this collection, or if this collection is empty; otherwise answers false.

It is unspecified whether discriminator will be evaluated with every element of this collection.

Parameters:

discriminator - the discriminator to evaluate

Returns:

whether discriminator is true for every element

Throws:

NullPointerException - if discriminator is null

anySatisfy

boolean anySatisfy(UnaryCondition<? super E> discriminator)

Answers true if the given discriminator answers true for any element of this collection; answers false otherwise, or if this collection is empty.

It is unspecified whether discriminator will be evaluated with every element of this collection.

Parameters:

discriminator - the discriminator to evaluate

Returns:

whether discriminator is true for any element

Throws:

NullPointerException - if the discriminator is null

toArray

Object[] toArray()

Answers an array with the same elements as this collection, with the same size as this collection, and a component class of Object. This means that objects of any class may be inserted into the result.

If this collection maintains an ordering for its elements, the order of those elements will be preserved in the result.

Returns:

an array of this collection's elements

See Also:

toArray(Class), Collections.toArray(Collection,Class)

toArray

Object[] toArray(Class<? super E> componentClass)

Answers an array with the same elements as this collection, with the same size as this collection, and a component type of the given class. This means that only elements of the given class or any of its derivatives may be inserted into the result.

Note that even though the given class will be the runtime component class of the result array, the return type of this method is Object[]. With Java generics, it is not possible to express the return type as an array of the component class without sacrificing the flexibility of providing a componentClass that is a supertype of the generic parameter's actual argument. Therefore, the caller should downcast to the desired type, or risk raising ArrayStoreException when inserting via a reference of type Object[].

If this collection maintains an ordering for its elements, the order of those elements will be preserved in the result.

Parameters:

componentClass - the desired type of the result array's components

Returns:

an array of this collection's elements

Throws:

NullPointerException - if componentClass is null

See Also:

Collections.toArray(Collection,Class)

toBag

Bag<E> toBag()

Answers a bag with the same elements as this collection.

Returns:

a bag of this collection's elements

toIdentityBag

IdentityBag<E> toIdentityBag()

Answers an identity bag with the same elements as this collection.

Returns:

a bag of this collection's elements

toIdentitySet

IdentitySet<E> toIdentitySet()

Answers an identity set with the same elements as this collection. Since sets do not store duplicate elements, the result may have fewer elements than this collection.

Returns:

a set of this collection's elements

toOrderedCollection

OrderedCollection<E> toOrderedCollection()

Answers an ordered collection with the same elements as this collection. The result has the same size as this collection.

If this collection maintains an ordering for its elements, the order of those elements will be preserved in the result.

Returns:

an ordered collection of this collection's elements

toSet

Set<E> toSet()

Answers a set with the same elements as this collection. Since sets do not store duplicate elements, the result may have fewer elements than this collection.

Returns:

a set of this collection's elements

toSortedCollection

SortedCollection<E> toSortedCollection()

Answers a sorted collection with the same elements as this collection. If this collection has established an ordering on its elements, then that ordering is used in the answer. Otherwise, order of the elements is arbitrary--in such a case, one should probably use the overload of this method that accepts a comparator.

Returns:

a sorted collection of this collection's elements

toSortedCollection

SortedCollection<E> toSortedCollection(Comparator<? super E> comparator)

Answers a sorted collection with the same elements as this collection, using the given comparator to order the elements.

Parameters:

comparator - a comparator

Returns:

a sorted collection of this collection's elements

collect

<R> Collection<R> collect(UnaryFunctor<? super E,? extends R> transformer)

Evaluates the given transformer for each element of this collection, with the element as the parameter, and answers a new collection containing the results of these evaluations.

The elements are traversed in the order specified by forEachDo for this collection.

Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection.

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

a collection of the transformations

Throws:

NullPointerException - if transformer is null

detect

E detect(UnaryCondition<? super E> discriminator)

Answers the first element of this collection for which the given discriminator answers true when given that element as an argument.

discriminator will only be evaluated until such an object is found or until all of the elements of the collection have been used as arguments. That is, there may be elements of this collection that are never used as arguments to discriminator.

The elements are traversed in the order specified by forEachDo for this collection.

Parameters:

discriminator - the discriminator to evaluate

Returns:

the first element of this collection that satisfies discriminator

Throws:

NoSuchElementException - if no element of this collection satisfies discriminator

NullPointerException - if discriminator is null

forEachDo

void forEachDo(UnaryFunctor<? super E,?> operation)

For each element of this collection, evaluates the given operation with the element as the parameter.

Unless specifically refined, the elements are not traversed in a particular order. Each element is visited exactly once. Conformant protocols may refine this message to specify a particular ordering.

Parameters:

operation - the operation to perform

Throws:

NullPointerException - if operation is null

includes

boolean includes(E target)

Answers true if an element of this collection is equivalent to the given one; answers false otherwise.

Parameters:

target - the object to compare against

Returns:

whether an equivalent object is in the collection

inject

<R> R inject(R initialValue,
             BinaryFunctor<? super R,? super E,? extends R> operation)

Answers the final result of evaluating the given operation using each element of this collection and the previous evaluation result as the parameters.

The first evaluation of operation is performed with the given initial value as the first parameter, and the first element of this collection as the second parameter. Subsequent evaluations are done with the result of the previous evaluation as the first parameter, and the next element as the second parameter. The result of the last evaluation is answered.

If this collection is empty, answers the initial value.

The elements are traversed in the order specified by forEachDo for this collection.

Type Parameters:

R - return type and type of first argument of the operation

Parameters:

initialValue - first parameter for the first evaluation

operation - the operation to evaluate

Returns:

the result of the last evaluation

Throws:

NullPointerException - if operation is null

isEmpty

boolean isEmpty()

Answers true iff this collection's size is zero; otherwise answers false.

Returns:

whether this collection contains any elements

occurrencesOf

int occurrencesOf(E target)

Answers the number of elements of this collection which are equivalent to the given target.

Parameters:

target - the object to compare against

Returns:

the number of occurrences of equivalent objects in this collection

rehash

void rehash()

Re-establishes any hash invariants of this collection.

reject

Collection<E> reject(UnaryCondition<? super E> discriminator)

Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer false.

For each element of this collection, discriminator is evaluated with the element as the parameter. Each element which causes discriminator to answer false is included in the new collection.

The elements are traversed in the order specified by forEachDo for this collection.

Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection. If both this collection and the result maintain an ordering of their elements, the elements of the result will be in the same relative order as the elements of this collection.

Parameters:

discriminator - the discriminator to evaluate

Returns:

a collection of the rejected elements of this collection

Throws:

NullPointerException - if discriminator is null

select

Collection<E> select(UnaryCondition<? super E> discriminator)

Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer true.

For each element of this collection, discriminator is evaluated with the element as the parameter. Each element which causes discriminator to answer true is included in the new collection.

The elements are traversed in order specified by forEachDo for this collection.

Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection. If both this collection and the result maintain an ordering of their elements, the elements of the result will be in the same relative order as the elements of this collection.

Parameters:

discriminator - the discriminator to evaluate

Returns:

a collection of the selected elements of this collection

Throws:

NullPointerException - if discriminator is null

size

int size()

Answers the number of elements in this collection.

Returns:

the number of elements in this collection