jaggregate
Class AbstractDictionaryImpl<K,V>

java.lang.Object
  jaggregate.AbstractCollection<E>
      jaggregate.AbstractExtensibleCollection<Pair<K,V>>
          jaggregate.AbstractDictionaryImpl<K,V>

Type Parameters:

K - a restriction on the types of the keys that may be contained in the dictionary

V - a restriction on the types of the values that may be contained in the dictionary

All Implemented Interfaces:

AbstractDictionary<K,V>, Collection<Pair<K,V>>, ExtensibleCollection<Pair<K,V>>

Direct Known Subclasses:

Dictionary, IdentityDictionary

public abstract class AbstractDictionaryImpl<K,V>
extends AbstractExtensibleCollection<Pair<K,V>>
implements AbstractDictionary<K,V>

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

Version:

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

Author:

Paul Holser

Method Summary

void	add(Pair<K,V> newElement) Adds a new element to this collection.
V	at(K key) Answers the element associated with the given key in this dictionary.
<R> AbstractBag<R>	collect(UnaryFunctor<? super Pair<K,V>,? 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.
<R> AbstractDictionary<K,R>	collectValues(UnaryFunctor<? super V,? extends R> transformer) Answers a new dictionary whose keys are this dictionary's keys, and whose corresponding elements are the results of evaluating the given transformer with each corresponding element of this dictionary.
boolean	equals(Object that) An object is considered equivalent to this dictionary if the object is assignable to this dictionary's class and has equivalent contents, as defined by this dictionary's notion of equivalence.
void	forEachDo(UnaryFunctor<? super Pair<K,V>,?> operation) For each element of this collection, evaluates the given operation with the element as the parameter.
int	hashCode()
boolean	includes(Pair<K,V> target) Answers true if an element of this collection is equivalent to the given one; answers false otherwise.
boolean	includesKey(K key) Answers true if this dictionary contains an element stored at the given key, else answers false.
K	keyAt(V value) Answers a key such that the element associated with this key is equivalent to the given value.
AbstractSet<K>	keys() Answers a set of keys at which there is an element stored in this dictionary.
void	keysAndValuesDo(BinaryFunctor<? super K,? super V,?> operation) Iteratively evaluates the given operation with each of this dictionary's keys and values.
<R> void	keysDo(UnaryFunctor<? super K,? extends R> operation) Iteratively evaluates the given operation with each of this dictionary's keys at which there are elements stored.
int	occurrencesOf(Pair<K,V> target) Answers the number of elements of this collection which are equivalent to the given target.
void	putAll(AbstractDictionary<? extends K,? extends V> newPairs) Stores the elements of the given dictionary in this dictionary at the corresponding key from the given dictionary.
V	putAt(K key, V newElement) Stores a new element at a given key in this dictionary.
void	rehash() Re-establishes any hash invariants of this collection.
AbstractDictionary<K,V>	reject(UnaryCondition<? super Pair<K,V>> 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.
AbstractDictionary<K,V>	rejectValues(UnaryCondition<? super V> discriminator) Answers a new dictionary which excludes the elements in this dictionary that cause the given discriminator to answer true.
boolean	remove(Pair<K,V> oldElement) Removes the first element of this collection which is equivalent to the given element.
void	removeAllKeys(Collection<? extends K> oldKeys) Removes any elements from this dictionary which are stored at any of the given keys.
void	removeAllKeys(Iterable<? extends K> oldKeys)
void	removeAllKeys(K[] oldKeys)
void	removeAllKeys(K oldKey, K... restOfOldKeys)
boolean	removeIfKey(UnaryCondition<? super K> discriminator) Removes each element of this dictionary whose key causes the given discriminator to answer true.
boolean	removeIfValue(UnaryCondition<? super V> discriminator) Removes each element of this dictionary which causes the given discriminator to answer true.
V	removeKey(K key) Removes the element stored at the given key in this dictionary.
boolean	retainAllKeys(Collection<? extends K> keepers) Removes any elements from this dictionary which are not stored at any of the given keys.
boolean	retainAllKeys(Iterable<? extends K> keepers)
boolean	retainAllKeys(K[] keepers)
boolean	retainAllKeys(K keeper, K... restOfKeepers)
boolean	retainIfKey(UnaryCondition<? super K> discriminator) Removes each element of this dictionary whose key causes the given discriminator to answer false.
boolean	retainIfValue(UnaryCondition<? super V> discriminator) Removes each element of this dictionary which causes the given discriminator to answer false.
AbstractDictionary<K,V>	select(UnaryCondition<? super Pair<K,V>> 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.
AbstractDictionary<K,V>	selectValues(UnaryCondition<? super V> discriminator) Answers a new dictionary which contains the elements in this dictionary whose keys cause the given discriminator to answer true.
int	size() Answers the number of elements in this collection.
String	toString()
AbstractBag<V>	values() Answers a collection of this dictionary's elements.

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

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

Methods inherited from interface jaggregate.Collection

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

Method Detail

add

public void add(Pair<K,V> 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.

Specified by:

add in interface ExtensibleCollection<Pair<K,V>>

Parameters:

newElement - the element to add

collect

public <R> AbstractBag<R> collect(UnaryFunctor<? super Pair<K,V>,? 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 AbstractDictionary<K,V>

Specified by:

collect in interface Collection<Pair<K,V>>

Specified by:

collect in interface ExtensibleCollection<Pair<K,V>>

Overrides:

collect in class AbstractExtensibleCollection<Pair<K,V>>

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

a collection of the transformations

forEachDo

public void forEachDo(UnaryFunctor<? super Pair<K,V>,?> 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.

Specified by:

forEachDo in interface Collection<Pair<K,V>>

Parameters:

operation - the operation to perform

includes

public boolean includes(Pair<K,V> target)

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

Specified by:

includes in interface Collection<Pair<K,V>>

Overrides:

includes in class AbstractCollection<Pair<K,V>>

Parameters:

target - the object to compare against

Returns:

whether an equivalent object is in the collection

occurrencesOf

public int occurrencesOf(Pair<K,V> target)

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

Specified by:

occurrencesOf in interface Collection<Pair<K,V>>

Overrides:

occurrencesOf in class AbstractCollection<Pair<K,V>>

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<Pair<K,V>>

Overrides:

rehash in class AbstractCollection<Pair<K,V>>

reject

public AbstractDictionary<K,V> reject(UnaryCondition<? super Pair<K,V>> 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 AbstractDictionary<K,V>

Specified by:

reject in interface Collection<Pair<K,V>>

Specified by:

reject in interface ExtensibleCollection<Pair<K,V>>

Overrides:

reject in class AbstractExtensibleCollection<Pair<K,V>>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a collection of the rejected elements of this collection

select

public AbstractDictionary<K,V> select(UnaryCondition<? super Pair<K,V>> 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 AbstractDictionary<K,V>

Specified by:

select in interface Collection<Pair<K,V>>

Specified by:

select in interface ExtensibleCollection<Pair<K,V>>

Overrides:

select in class AbstractExtensibleCollection<Pair<K,V>>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a collection of the selected elements of this collection

size

public int size()

Answers the number of elements in this collection.

Specified by:

size in interface Collection<Pair<K,V>>

Returns:

the number of elements in this collection

putAll

public void putAll(AbstractDictionary<? extends K,? extends V> newPairs)

Stores the elements of the given dictionary in this dictionary at the corresponding key from the given dictionary.

This message is equivalent to repeatedly performing putAt on this dictionary with each of the keys and elements from newPairs in turn. If a key in newPairs is key-equivalent to a key in this dictionary, the associated element in newPairs replaces the element in this dictionary.

Specified by:

putAll in interface AbstractDictionary<K,V>

Parameters:

newPairs - the pairs to add

at

public V at(K key)

Answers the element associated with the given key in this dictionary.

Specified by:

at in interface AbstractDictionary<K,V>

Parameters:

key - the key to look up

Returns:

the associated element, or null if there is no such element

collectValues

public <R> AbstractDictionary<K,R> collectValues(UnaryFunctor<? super V,? extends R> transformer)

Answers a new dictionary whose keys are this dictionary's keys, and whose corresponding elements are the results of evaluating the given transformer with each corresponding element of this dictionary. For each of this dictionary's keys, a new element is obtained by evaluating transformer with the corresponding element of this dictionary as a parameter.

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

Specified by:

collectValues in interface AbstractDictionary<K,V>

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

the results of evaluating transformer with the elements of this dictionary

includesKey

public boolean includesKey(K key)

Answers true if this dictionary contains an element stored at the given key, else answers false.

Specified by:

includesKey in interface AbstractDictionary<K,V>

Parameters:

key - the key to lookup

Returns:

whether the key is in this dictionary

keyAt

public K keyAt(V value)

Answers a key such that the element associated with this key is equivalent to the given value.

Note that if there are multiple elements in this dictionary that are equivalent to the given value, then the one whose key answered is arbitrary.

Specified by:

keyAt in interface AbstractDictionary<K,V>

Parameters:

value - the value to look up

Returns:

an associated key, or null if there is no such key

keys

public AbstractSet<K> keys()

Answers a set of keys at which there is an element stored in this dictionary.

The size of the result is equal to the size of this dictionary.

Specified by:

keys in interface AbstractDictionary<K,V>

Returns:

a set of the keys in this dictionary

keysAndValuesDo

public void keysAndValuesDo(BinaryFunctor<? super K,? super V,?> operation)

Iteratively evaluates the given operation with each of this dictionary's keys and values.

For each of this dictionary's elements, operation is evaluated with the corresponding key as the first argument and the element as the second argument.

The order in which the elements are visited is not specified. Each key is visited exactly once.

Specified by:

keysAndValuesDo in interface AbstractDictionary<K,V>

Parameters:

operation - the operation to perform

keysDo

public <R> void keysDo(UnaryFunctor<? super K,? extends R> operation)

Iteratively evaluates the given operation with each of this dictionary's keys at which there are elements stored.

For each of this dictionary's elements, operation is evaluated with the corresponding key as the argument.

The order in which the elements are visited is not specified. Each key is visited exactly once.

Specified by:

keysDo in interface AbstractDictionary<K,V>

Type Parameters:

R - a constraint on the return type of the operation

Parameters:

operation - the operation to perform

putAt

public V putAt(K key,
               V newElement)

Stores a new element at a given key in this dictionary.

If lookup succeeds for key, then newElement replaces the element previously stored at key. Otherwise, newElement is stored at the new key. In either case, subsequent successful lookups for key will answer newElement.

Specified by:

putAt in interface AbstractDictionary<K,V>

Parameters:

key - a key

newElement - the new element to associate with key

Returns:

the element previously associated with key, or null if there is no such element

rejectValues

public AbstractDictionary<K,V> rejectValues(UnaryCondition<? super V> discriminator)

Answers a new dictionary which excludes the elements in this dictionary that cause the given discriminator to answer true.

For each of this dictionary's keys, discriminator is evaluated with the corresponding element as the argument. If the element causes discriminator to answer false, the key is added to the answer with the element as its corresponding value.

Specified by:

rejectValues in interface AbstractDictionary<K,V>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a dictionary of rejects

remove

public boolean remove(Pair<K,V> 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.

Specified by:

remove in interface ExtensibleCollection<Pair<K,V>>

Parameters:

oldElement - the element to remove

Returns:

true if any removal occurred

removeKey

public V removeKey(K key)

Removes the element stored at the given key in this dictionary.

Specified by:

removeKey in interface AbstractDictionary<K,V>

Parameters:

key - the key to remove

Returns:

the removed element, or null if there is no such element

removeAllKeys

public void removeAllKeys(Collection<? extends K> oldKeys)

Removes any elements from this dictionary which are stored at any of the given keys.

This message has the same effect as repeatedly performing removeKey on this dictionary for each element in oldKeys.

Specified by:

removeAllKeys in interface AbstractDictionary<K,V>

Parameters:

oldKeys - the keys to remove

removeAllKeys

public void removeAllKeys(K[] oldKeys)

Specified by:

removeAllKeys in interface AbstractDictionary<K,V>

Parameters:

oldKeys - the keys to remove

See Also:

AbstractDictionary.removeAllKeys(Collection)

removeAllKeys

public void removeAllKeys(K oldKey,
                          K... restOfOldKeys)

Specified by:

removeAllKeys in interface AbstractDictionary<K,V>

Parameters:

oldKey - the first key to remove

restOfOldKeys - the remainder of keys to remove

See Also:

AbstractDictionary.removeAllKeys(Collection)

removeAllKeys

public void removeAllKeys(Iterable<? extends K> oldKeys)

Specified by:

removeAllKeys in interface AbstractDictionary<K,V>

Parameters:

oldKeys - the keys to remove

See Also:

AbstractDictionary.removeAllKeys(Collection)

removeIfKey

public boolean removeIfKey(UnaryCondition<? super K> discriminator)

Removes each element of this dictionary whose key causes the given discriminator to answer true.

Specified by:

removeIfKey in interface AbstractDictionary<K,V>

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

removeIfValue

public boolean removeIfValue(UnaryCondition<? super V> discriminator)

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

Specified by:

removeIfValue in interface AbstractDictionary<K,V>

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

retainAllKeys

public boolean retainAllKeys(Collection<? extends K> keepers)

Removes any elements from this dictionary which are not stored at any of the given keys.

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

Specified by:

retainAllKeys in interface AbstractDictionary<K,V>

Parameters:

keepers - the keys to retain

Returns:

true if any elements were removed from this dictionary

retainAllKeys

public boolean retainAllKeys(K[] keepers)

Specified by:

retainAllKeys in interface AbstractDictionary<K,V>

Parameters:

keepers - the keys to retain

Returns:

true if any elements were removed from this dictionary

See Also:

AbstractDictionary.retainAllKeys(Collection)

retainAllKeys

public boolean retainAllKeys(K keeper,
                             K... restOfKeepers)

Specified by:

retainAllKeys in interface AbstractDictionary<K,V>

Parameters:

keeper - the first key to retain

restOfKeepers - the remainder of keys to retain

Returns:

true if any elements were removed from this dictionary

See Also:

AbstractDictionary.retainAllKeys(Collection)

retainAllKeys

public boolean retainAllKeys(Iterable<? extends K> keepers)

Specified by:

retainAllKeys in interface AbstractDictionary<K,V>

Parameters:

keepers - the keys to retain

Returns:

true if any elements were removed from this dictionary

See Also:

AbstractDictionary.retainAllKeys(Collection)

retainIfKey

public boolean retainIfKey(UnaryCondition<? super K> discriminator)

Removes each element of this dictionary whose key causes the given discriminator to answer false.

Specified by:

retainIfKey in interface AbstractDictionary<K,V>

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

retainIfValue

public boolean retainIfValue(UnaryCondition<? super V> discriminator)

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

Specified by:

retainIfValue in interface AbstractDictionary<K,V>

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

selectValues

public AbstractDictionary<K,V> selectValues(UnaryCondition<? super V> discriminator)

Answers a new dictionary which contains the elements in this dictionary whose keys cause the given discriminator to answer true.

For each of this dictionary's keys, discriminator is evaluated with the corresponding element as the argument. If the element causes discriminator to answer true, the key is added to the answer with the element as its corresponding value.

Specified by:

selectValues in interface AbstractDictionary<K,V>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a dictionary of matches

values

public AbstractBag<V> values()

Answers a collection of this dictionary's elements.

Specified by:

values in interface AbstractDictionary<K,V>

Returns:

a bag of the values in this dictionary

equals

public boolean equals(Object that)

An object is considered equivalent to this dictionary if the object is assignable to this dictionary's class and has equivalent contents, as defined by this dictionary'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