jaggregate
Interface AbstractDictionary<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 Superinterfaces:

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

All Known Implementing Classes:

AbstractDictionaryImpl, Dictionary, IdentityDictionary

public interface AbstractDictionary<K,V>
extends ExtensibleCollection<Pair<K,V>>

Provides protocol for accessing, adding, removing, and iterating over the elements of an unordered collection whose elements are accessed using an explicitly assigned external key.

Version:

$Id: AbstractDictionary.java,v 1.5 2008/05/08 03:49:37 pholser Exp $

Author:

Paul Holser

Method Summary

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.
<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	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.
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.
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.
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.
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.
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.
AbstractBag<V>	values() Answers a collection of this dictionary's elements.

Methods inherited from interface jaggregate.ExtensibleCollection

add, addAll, addAll, addAll, addAll, remove, removeAll, removeAll, removeAll, removeAll, removeIf, retainAll, retainAll, retainAll, retainAll, retainIf

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

Specified by:

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

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

a bag of results

reject

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

Specified by:

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

Parameters:

discriminator - the discriminator to evaluate

Returns:

a dictionary of rejects

select

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

Specified by:

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

Parameters:

discriminator - the discriminator to evaluate

Returns:

a dictionary of matches

at

V at(K key)

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

Parameters:

key - the key to look up

Returns:

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

collectValues

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

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

Throws:

NullPointerException - if transformer is null

includesKey

boolean includesKey(K key)

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

Parameters:

key - the key to lookup

Returns:

whether the key is in this dictionary

keyAt

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.

Parameters:

value - the value to look up

Returns:

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

keys

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.

Returns:

a set of the keys in this dictionary

keysAndValuesDo

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.

Parameters:

operation - the operation to perform

Throws:

NullPointerException - if operation is null

keysDo

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

Type Parameters:

R - a constraint on the return type of the operation

Parameters:

operation - the operation to perform

Throws:

NullPointerException - if operation is null

putAll

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.

Parameters:

newPairs - the pairs to add

Throws:

NullPointerException - if newPairs is null

putAt

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.

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

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.

Parameters:

discriminator - the discriminator to evaluate

Returns:

a dictionary of rejects

Throws:

NullPointerException - if discriminator is null

removeAllKeys

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.

Parameters:

oldKeys - the keys to remove

Throws:

NullPointerException - if oldKeys is null

removeAllKeys

void removeAllKeys(K[] oldKeys)

Parameters:

oldKeys - the keys to remove

Throws:

NullPointerException - if restOfOldKeys is null

See Also:

removeAllKeys(Collection)

removeAllKeys

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

Parameters:

oldKey - the first key to remove

restOfOldKeys - the remainder of keys to remove

Throws:

NullPointerException - if restOfOldKeys is null

See Also:

removeAllKeys(Collection)

removeAllKeys

void removeAllKeys(Iterable<? extends K> oldKeys)

Parameters:

oldKeys - the keys to remove

Throws:

NullPointerException - if oldKeys is null

See Also:

removeAllKeys(Collection)

removeKey

V removeKey(K key)

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

Parameters:

key - the key to remove

Returns:

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

removeIfKey

boolean removeIfKey(UnaryCondition<? super K> discriminator)

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

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

Throws:

NullPointerException - if discriminator is null

removeIfValue

boolean removeIfValue(UnaryCondition<? super V> discriminator)

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

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

Throws:

NullPointerException - if discriminator is null

retainAllKeys

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.

Parameters:

keepers - the keys to retain

Returns:

true if any elements were removed from this dictionary

Throws:

NullPointerException - if keepers is null

retainAllKeys

boolean retainAllKeys(K[] keepers)

Parameters:

keepers - the keys to retain

Returns:

true if any elements were removed from this dictionary

Throws:

NullPointerException - if keepers is null

See Also:

retainAllKeys(Collection)

retainAllKeys

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

Parameters:

keeper - the first key to retain

restOfKeepers - the remainder of keys to retain

Returns:

true if any elements were removed from this dictionary

Throws:

NullPointerException - if restOfKeepers is null

See Also:

retainAllKeys(Collection)

retainAllKeys

boolean retainAllKeys(Iterable<? extends K> keepers)

Parameters:

keepers - the keys to retain

Returns:

true if any elements were removed from this dictionary

Throws:

NullPointerException - if keepers is null

See Also:

retainAllKeys(Collection)

retainIfKey

boolean retainIfKey(UnaryCondition<? super K> discriminator)

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

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

Throws:

NullPointerException - if discriminator is null

retainIfValue

boolean retainIfValue(UnaryCondition<? super V> discriminator)

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

Parameters:

discriminator - the discriminator to evaluate

Returns:

true if any removal occurred

Throws:

NullPointerException - if discriminator is null

selectValues

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.

Parameters:

discriminator - the discriminator to evaluate

Returns:

a dictionary of matches

Throws:

NullPointerException - if discriminator is null

values

AbstractBag<V> values()

Answers a collection of this dictionary's elements.

Returns:

a bag of the values in this dictionary