jaggregate
Class AbstractCollection<E>

java.lang.Object
  jaggregate.AbstractCollection<E>

Type Parameters:

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

All Implemented Interfaces:

Collection<E>

Direct Known Subclasses:

AbstractExtensibleCollection, Interval

public abstract class AbstractCollection<E>
extends Object
implements Collection<E>

Implementation of the collection concept that should be common for most concrete implementations.

Version:

$Id: AbstractCollection.java,v 1.8 2008/10/03 19:01:23 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.
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.
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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface jaggregate.Collection

forEachDo, size

Method Detail

allSatisfy

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

Specified by:

allSatisfy in interface Collection<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

whether discriminator is true for every element

anySatisfy

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

Specified by:

anySatisfy in interface Collection<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

whether discriminator is true for any element

toArray

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

Specified by:

toArray in interface Collection<E>

Returns:

an array of this collection's elements

See Also:

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

toArray

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

Specified by:

toArray in interface Collection<E>

Parameters:

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

Returns:

an array of this collection's elements

See Also:

Collections.toArray(Collection,Class)

toBag

public Bag<E> toBag()

Answers a bag with the same elements as this collection.

Specified by:

toBag in interface Collection<E>

Returns:

a bag of this collection's elements

toIdentityBag

public IdentityBag<E> toIdentityBag()

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

Specified by:

toIdentityBag in interface Collection<E>

Returns:

a bag of this collection's elements

toIdentitySet

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

Specified by:

toIdentitySet in interface Collection<E>

Returns:

a set of this collection's elements

toOrderedCollection

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

Specified by:

toOrderedCollection in interface Collection<E>

Returns:

an ordered collection of this collection's elements

toSet

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

Specified by:

toSet in interface Collection<E>

Returns:

a set of this collection's elements

toSortedCollection

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

Specified by:

toSortedCollection in interface Collection<E>

Returns:

a sorted collection of this collection's elements

toSortedCollection

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

Specified by:

toSortedCollection in interface Collection<E>

Parameters:

comparator - a comparator

Returns:

a sorted collection of this collection's elements

collect

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

Specified by:

collect in interface Collection<E>

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

a collection of the transformations

detect

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

Specified by:

detect in interface Collection<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

the first element of this collection that satisfies discriminator

includes

public boolean includes(E target)

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

Specified by:

includes in interface Collection<E>

Parameters:

target - the object to compare against

Returns:

whether an equivalent object is in the collection

inject

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

Specified by:

inject in interface Collection<E>

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

isEmpty

public boolean isEmpty()

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

Specified by:

isEmpty in interface Collection<E>

Returns:

whether this collection contains any elements

occurrencesOf

public int occurrencesOf(E target)

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

Specified by:

occurrencesOf in interface Collection<E>

Parameters:

target - the object to compare against

Returns:

the number of occurrences of equivalent objects in this collection

rehash

public void rehash()

Re-establishes any hash invariants of this collection.

Specified by:

rehash in interface Collection<E>

reject

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

Specified by:

reject in interface Collection<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a collection of the rejected elements of this collection

select

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

Specified by:

select in interface Collection<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a collection of the selected elements of this collection