jaggregate
Interface ExtensibleCollection<E>

Type Parameters:

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

All Superinterfaces:

Collection<E>

All Known Subinterfaces:

AbstractDictionary<K,V>

All Known Implementing Classes:

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

public interface ExtensibleCollection<E>
extends Collection<E>

Provides protocol for adding elements to and removing elements from a variable-sized collection.

Version:

$Id: ExtensibleCollection.java,v 1.4 2008/05/07 06:00:48 pholser Exp $

Author:

Paul Holser

Method Summary

void	add(E newElement) Adds a new element to this collection.
void	addAll(Collection<? extends E> newElements) Adds each element of the given collection to this collection.
void	addAll(E[] newElements)
void	addAll(E newElement, E... restOfNewElements)
void	addAll(Iterable<? extends E> newElements)
<R> ExtensibleCollection<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.
ExtensibleCollection<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.
boolean	remove(E oldElement) Removes the first element of this collection which is equivalent to the given element.
boolean	removeAll(Collection<? extends E> oldElements) For each element in the given collection, removes the first element from this collection which is equivalent to this element.
boolean	removeAll(E[] oldElements)
boolean	removeAll(E oldElement, E... restOfNewElements)
boolean	removeAll(Iterable<? extends E> oldElements)
boolean	removeIf(UnaryCondition<? super E> discriminator) Removes each element of this collection which causes the given discriminator to answer true.
boolean	retainAll(Collection<? extends E> keepers) Removes each element of this collection that is not contained in the given collection.
boolean	retainAll(E[] keepers)
boolean	retainAll(E keeper, E... restOfKeepers)
boolean	retainAll(Iterable<? extends E> keepers)
boolean	retainIf(UnaryCondition<? super E> discriminator) Removes each element of this collection which causes the given discriminator to answer false.
ExtensibleCollection<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.

Methods inherited from interface jaggregate.Collection

allSatisfy, anySatisfy, detect, forEachDo, includes, inject, isEmpty, occurrencesOf, rehash, size, toArray, toArray, toBag, toIdentityBag, toIdentitySet, toOrderedCollection, toSet, toSortedCollection, toSortedCollection

Method Detail

collect

<R> ExtensibleCollection<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 extensible collection of the transformations

reject

ExtensibleCollection<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:

an extensible collection of the rejected elements of this collection

select

ExtensibleCollection<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:

an extensible collection of the selected elements of this collection

add

void add(E newElement)

Adds a new element to this collection. Unless specifically refined, the position of newElement in the element traversal order is unspecified.

Conformant protocols may place restrictions on the characteristics of objects that are valid elements. Unless otherwise specified, any object that is of the same class as or of a subclass of this collection's type parameter is acceptable.

Parameters:

newElement - the element to add

Throws:

IllegalArgumentException - if newElement is found to violate restrictions on the characteristics of valid elements

addAll

void addAll(Collection<? extends E> newElements)

Adds each element of the given collection to this collection.

The operation is equivalent to adding each element of newElements to this collection using add with the element as the parameter. The newElements are traversed in the order specified by forEachDo for newElements.

Parameters:

newElements - the elements to add

Throws:

NullPointerException - if newElements is null

IllegalArgumentException - if any of newElements is found to violate restrictions on the characteristics of valid elements

addAll

void addAll(E[] newElements)

Parameters:

newElements - the elements to add

Throws:

NullPointerException - if newElements is null

IllegalArgumentException - if any of newElements is found to violate restrictions on the characteristics of valid elements

See Also:

addAll(Collection)

addAll

void addAll(E newElement,
            E... restOfNewElements)

Parameters:

newElement - first new element to add

restOfNewElements - remainder of the elements to add

Throws:

NullPointerException - if restOfNewElements is null

IllegalArgumentException - if any of the new elements is found to violate restrictions on the characteristics of valid elements

See Also:

addAll(Collection)

addAll

void addAll(Iterable<? extends E> newElements)

Parameters:

newElements - the elements to add

Throws:

NullPointerException - if newElements is null

IllegalArgumentException - if any of newElements is found to violate restrictions on the characteristics of valid elements

See Also:

addAll(Collection)

remove

boolean remove(E oldElement)

Removes the first element of this collection which is equivalent to the given element.

The elements are tested in the same order in which they would be enumerated by forEachDo for this collection.

Parameters:

oldElement - the element to remove

Returns:

true if any removal occurred

removeAll

boolean removeAll(Collection<? extends E> oldElements)

For each element in the given collection, removes the first element from this collection which is equivalent to this element.

The operation is defined to be equivalent to removing each element of oldElements from this collection using remove with the element as the parameter.

Parameters:

oldElements - the elements to remove

Returns:

true if any removal occurred

Throws:

NullPointerException - if oldElements is null

removeAll

boolean removeAll(E[] oldElements)

Parameters:

oldElements - the elements to remove

Returns:

true if any removal occurred

Throws:

NullPointerException - if oldElements is null

See Also:

removeAll(Collection)

removeAll

boolean removeAll(E oldElement,
                  E... restOfNewElements)

Parameters:

oldElement - first element to remove

restOfNewElements - remainder of the elements to remove

Returns:

true if any removal occurred

Throws:

NullPointerException - if restOfOldElements is null

See Also:

removeAll(Collection)

removeAll

boolean removeAll(Iterable<? extends E> oldElements)

Parameters:

oldElements - the elements to remove

Returns:

true if any removal occurred

Throws:

NullPointerException - if oldElements is null

See Also:

removeAll(Collection)

removeIf

boolean removeIf(UnaryCondition<? super E> discriminator)

Removes each element of this collection which causes the given discriminator to answer true.

The elements are tested in the same order in which they would be enumerated by forEachDo for this collection.

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

Throws:

NullPointerException - if discriminator is null

retainAll

boolean retainAll(Collection<? extends E> keepers)

Removes each element of this collection that is not contained in the given collection.

Note that if the given collection is empty, this method has the effect of "clearing" this collection.

Parameters:

keepers - the elements to retain

Returns:

true if any removal occurred

Throws:

NullPointerException - if keepers is null

retainAll

boolean retainAll(E[] keepers)

Parameters:

keepers - the elements to retain

Returns:

true if any removal occurred

Throws:

NullPointerException - if keepers is null

See Also:

retainAll(Collection)

retainAll

boolean retainAll(E keeper,
                  E... restOfKeepers)

Parameters:

keeper - first element to retain

restOfKeepers - remainder of the elements to retain

Returns:

true if any removal occurred

Throws:

NullPointerException - if restOfKeepers is null

See Also:

retainAll(Collection)

retainAll

boolean retainAll(Iterable<? extends E> keepers)

Parameters:

keepers - the elements to retain

Returns:

true if any removal occurred

Throws:

NullPointerException - if keepers is null

See Also:

retainAll(Collection)

retainIf

boolean retainIf(UnaryCondition<? super E> discriminator)

Removes each element of this collection which causes the given discriminator to answer false.

The elements are tested in the same order in which they would be enumerated by forEachDo for this collection.

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

Throws:

NullPointerException - if discriminator is null