jaggregate
Class AbstractBag<E>

java.lang.Object
  jaggregate.AbstractCollection<E>
      jaggregate.AbstractExtensibleCollection<E>
          jaggregate.AbstractBag<E>

Type Parameters:

E - a restriction on the types of elements that may be contained in the bag

All Implemented Interfaces:

Collection<E>, ExtensibleCollection<E>

Direct Known Subclasses:

Bag, IdentityBag

public abstract class AbstractBag<E>
extends AbstractExtensibleCollection<E>

Represents an unordered, variable-sized collection whose elements can be added or removed, but cannot be individually accessed by external keys.

A bag is similar to a set but can contain duplicate elements. Elements are duplicates if they are equivalent.

Version:

$Id: AbstractBag.java,v 1.9 2008/10/03 19:01:23 pholser Exp $

Author:

Paul Holser

Method Summary

void	add(E newElement) Adds a new element to this collection.
void	add(E newElement, int occurrences) Adds the given element to this bag a given number of times.
<R> AbstractBag<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.
boolean	equals(Object that) An object is considered equivalent to this bag if the object is assignable to this bag's class and has equivalent contents, as defined by this bag's notion of equivalence.
void	forEachDo(UnaryFunctor<? super E,?> operation) For each element of this collection, evaluates the given operation with the element as the parameter.
int	hashCode()
boolean	includes(E target) Answers true if an element of this collection is equivalent to the given one; answers false otherwise.
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.
AbstractBag<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.
boolean	remove(E oldElement) Removes the first element of this collection which is equivalent to the given element.
AbstractBag<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.
int	size() Answers the number of elements in this collection.
String	toString()

Methods inherited from class jaggregate.AbstractExtensibleCollection

addAll, addAll, addAll, addAll, removeAll, removeAll, removeAll, removeAll, removeIf, retainAll, retainAll, retainAll, retainAll, retainIf

Methods inherited from class jaggregate.AbstractCollection

allSatisfy, anySatisfy, detect, inject, isEmpty, toArray, toArray, toBag, toIdentityBag, toIdentitySet, toOrderedCollection, toSet, toSortedCollection, toSortedCollection

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface jaggregate.Collection

allSatisfy, anySatisfy, detect, inject, isEmpty, toArray, toArray, toBag, toIdentityBag, toIdentitySet, toOrderedCollection, toSet, toSortedCollection, toSortedCollection

Method Detail

collect

public <R> AbstractBag<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>

Specified by:

collect in interface ExtensibleCollection<E>

Overrides:

collect in class AbstractExtensibleCollection<E>

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

a bag of results

forEachDo

public 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

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>

Overrides:

includes in class AbstractCollection<E>

Parameters:

target - the object to compare against

Returns:

whether an equivalent object is in the collection

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>

Overrides:

occurrencesOf in class AbstractCollection<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>

Overrides:

rehash in class AbstractCollection<E>

reject

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

Specified by:

reject in interface ExtensibleCollection<E>

Overrides:

reject in class AbstractExtensibleCollection<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a bag of rejects

select

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

Specified by:

select in interface ExtensibleCollection<E>

Overrides:

select in class AbstractExtensibleCollection<E>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a bag of selections

size

public int size()

Answers the number of elements in this collection.

Returns:

the number of elements in this collection

add

public 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

add

public void add(E newElement,
                int occurrences)

Adds the given element to this bag a given number of times.

Parameters:

newElement - the element to add

occurrences - number of times to add newElement

Throws:

IllegalArgumentException - if occurrences is negative

See Also:

add(Object)

remove

public 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

equals

public boolean equals(Object that)

An object is considered equivalent to this bag if the object is assignable to this bag's class and has equivalent contents, as defined by this bag's notion of equivalence.

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object