Map (Crater Dog Java Collection Framework 3.3 API)

java.lang.Object
- craterdog.collections.abstractions.Collection<E>
- - craterdog.collections.abstractions.SortableCollection<Association<K,V>>
  - - craterdog.collections.Map<K,V>

Type Parameters:

K - The type of the key in the association.

V - The type of the value in the association.

All Implemented Interfaces:

Accessible<Association<K,V>>, Associative<K,V>, Iteratable<Association<K,V>>, Sortable<Association<K,V>>, Composite, Sequential<Association<K,V>>, java.lang.Iterable<Association<K,V>>

Direct Known Subclasses:

Dictionary
```
public class Map<K,V>
extends SortableCollection<Association<K,V>>
implements Associative<K,V>
```
This collection class implements a sortable collection containing key-value associations. The implementation is optimized for both inserting new associations and looking up values based on their key. The implementation also dynamically scales up and down the number of buckets as the number of associations changes over time.

Author:

Derk Norton

Constructor Summary

Constructors
Constructor and Description
`Map()` This constructor creates a new empty map.
`Map(Iteratable<K> keys, Iteratable<V> values)` This constructor creates a new map using the specified keys and values.
`Map(K[] keys, V[] values)` This constructor creates a new map using the specified key and value arrays.
`Map(Map<K,V> elements)` This constructor creates a new map using the elements provided in the specified map.
`Map(java.util.Map<K,V> elements)` This constructor creates a new map using the elements provided in a java map.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addElement(Association<K,V> element)` This method adds a new element to the collection.
`void`	`associateKeyWithValue(K key, V value)` This method associates in this collection a new value with a key.
`static <K,V> Map<K,V>`	`concatenate(Map<K,V> map1, Map<K,V> map2)` This function returns a new map that contains the all the associations from both the specified maps.
`boolean`	`containsElement(Association<K,V> element)` This method determines if an element is contained in the collection.
`Iterator<Association<K,V>>`	`createDefaultIterator()` This method creates a new default iterator for the collection.
`Manipulator<Association<K,V>>`	`createDefaultManipulator()` This method creates a new default manipulator for the collection.
`Iteratable<Association<K,V>>`	`getAssociations()` This method returns the list of associations between keys and values for this collection.
`Iteratable<? super K>`	`getKeys()` This method returns the list of keys for the associations in this collection.
`int`	`getNumberOfElements()`
`V`	`getValueForKey(K key)` This method returns the value associated with the specified key.
`Iteratable<? super V>`	`getValues()` This method returns the list of values for the associations in this collection.
`static <K,V> Map<K,V>`	`reduce(Map<K,V> map, Set<K> keys)` This function returns a new map that contains only the associations with the specified keys.
`void`	`removeAllElements()` This method removes all elements from the collection.
`boolean`	`removeElement(Association<K,V> element)` This method removes the specified element from the collection.
`V`	`removeValueForKey(K key)` This method removes from this collection the value associated with a key.

Methods inherited from class craterdog.collections.abstractions.SortableCollection
concatenate, sortElements, sortElements, sorter

Methods inherited from class craterdog.collections.abstractions.Collection
addElements, addElements, containsAllElementsIn, containsAnyElementsIn, equals, hashCode, isEmpty, iterator, normalizedIndex, removeElements, removeElements, toArray, toString, toString

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface craterdog.core.Sequential
isEmpty, iterator, toArray

Methods inherited from interface java.lang.Iterable
forEach, spliterator

Methods inherited from interface craterdog.core.Composite
toString

- Constructor Detail
  - Map
```
public Map()
```
    This constructor creates a new empty map.
  - Map
```
public Map(K[] keys,
           V[] values)
```
    This constructor creates a new map using the specified key and value arrays. The number of keys must equal the number of values or an exception is thrown.
    
    Parameters:
    
    keys - The array of keys that should be used to create the map.
    
    values - The array of values that should be used to create the map.
  - Map
```
public Map(Iteratable<K> keys,
           Iteratable<V> values)
```
    This constructor creates a new map using the specified keys and values. The number of keys must equal the number of values or an exception is thrown.
    
    Parameters:
    
    keys - The keys that should be used to create the map.
    
    values - The values that should be used to create the map.
  - Map
```
public Map(Map<K,V> elements)
```
    This constructor creates a new map using the elements provided in the specified map.
    
    Parameters:
    
    elements - The map containing the key-value pairs to be mapped.
  - Map
```
public Map(java.util.Map<K,V> elements)
```
    This constructor creates a new map using the elements provided in a java map.
    
    Parameters:
    
    elements - The java map containing the key-value pairs to be mapped.
- Method Detail
  - getNumberOfElements
```
public final int getNumberOfElements()
```
    Specified by:
    
    getNumberOfElements in interface Sequential<Association<K,V>>
  - containsElement
```
public final boolean containsElement(Association<K,V> element)
```
    Description copied from interface: Accessible
    
    This method determines if an element is contained in the collection.
    
    Specified by:
    
    containsElement in interface Accessible<Association<K,V>>
    
    Parameters:
    
    element - The element to be checked for in the collection.
    
    Returns:
    
    Whether or not the specified element is contained in the collection.
  - createDefaultIterator
```
public Iterator<Association<K,V>> createDefaultIterator()
```
    Description copied from interface: Iteratable
    
    This method creates a new default iterator for the collection.
    
    Specified by:
    
    createDefaultIterator in interface Iteratable<Association<K,V>>
    
    Returns:
    
    A new default iterator for the collection.
  - addElement
```
public final boolean addElement(Association<K,V> element)
```
    Description copied from interface: Accessible
    
    This method adds a new element to the collection. If the collection is empty then the new element will be the first element in the collection.
    
    Specified by:
    
    addElement in interface Accessible<Association<K,V>>
    
    Parameters:
    
    element - The new element to be added.
    
    Returns:
    
    Whether or not the element was actually added to the collection.
  - removeElement
```
public final boolean removeElement(Association<K,V> element)
```
    Description copied from interface: Accessible
    
    This method removes the specified element from the collection. If the element is not found in the collection, no changes are made.
    
    Specified by:
    
    removeElement in interface Accessible<Association<K,V>>
    
    Parameters:
    
    element - The element to be removed.
    
    Returns:
    
    Whether or not the element was found.
  - removeAllElements
```
public final void removeAllElements()
```
    Description copied from interface: Iteratable
    
    This method removes all elements from the collection.
    
    Specified by:
    
    removeAllElements in interface Iteratable<Association<K,V>>
  - createDefaultManipulator
```
public Manipulator<Association<K,V>> createDefaultManipulator()
```
    Description copied from interface: Sortable
    
    This method creates a new default manipulator for the collection.
    
    Specified by:
    
    createDefaultManipulator in interface Sortable<Association<K,V>>
    
    Returns:
    
    The new manipulator.
  - getKeys
```
public final Iteratable<? super K> getKeys()
```
    Description copied from interface: Associative
    
    This method returns the list of keys for the associations in this collection.
    
    Specified by:
    
    getKeys in interface Associative<K,V>
    
    Returns:
    
    The keys for this collection.
  - getValues
```
public final Iteratable<? super V> getValues()
```
    Description copied from interface: Associative
    
    This method returns the list of values for the associations in this collection.
    
    Specified by:
    
    getValues in interface Associative<K,V>
    
    Returns:
    
    The values for this collection.
  - getAssociations
```
public final Iteratable<Association<K,V>> getAssociations()
```
    Description copied from interface: Associative
    
    This method returns the list of associations between keys and values for this collection.
    
    Specified by:
    
    getAssociations in interface Associative<K,V>
    
    Returns:
    
    A list of the key/value associations that make up this collection.
  - getValueForKey
```
public final V getValueForKey(K key)
```
    Description copied from interface: Associative
    
    This method returns the value associated with the specified key.
    
    Specified by:
    
    getValueForKey in interface Associative<K,V>
    
    Parameters:
    
    key - The key for the value to be retrieved.
    
    Returns:
    
    The value associated with the key.
  - associateKeyWithValue
```
public final void associateKeyWithValue(K key,
                                        V value)
```
    Description copied from interface: Associative
    
    This method associates in this collection a new value with a key. If there is already a value associated with the specified key, the new value replaces the old value.
    
    Specified by:
    
    associateKeyWithValue in interface Associative<K,V>
    
    Parameters:
    
    key - The key for the new value.
    
    value - The new value to be associated with the key.
  - removeValueForKey
```
public final V removeValueForKey(K key)
```
    Description copied from interface: Associative
    
    This method removes from this collection the value associated with a key. If no value is associated with the specified key then null is returned.
    
    Specified by:
    
    removeValueForKey in interface Associative<K,V>
    
    Parameters:
    
    key - The key for the value to be removed.
    
    Returns:
    
    The value associated with the key.
  - concatenate
```
public static <K,V> Map<K,V> concatenate(Map<K,V> map1,
                                         Map<K,V> map2)
```
    This function returns a new map that contains the all the associations from both the specified maps.
    
    Type Parameters:
    
    K - The type of key contained in the maps.
    
    V - The type of value contained in the maps.
    
    Parameters:
    
    map1 - The first map whose elements are to be added.
    
    map2 - The second map whose elements are to be added.
    
    Returns:
    
    The resulting map.
  - reduce
```
public static <K,V> Map<K,V> reduce(Map<K,V> map,
                                    Set<K> keys)
```
    This function returns a new map that contains only the associations with the specified keys.
    
    Type Parameters:
    
    K - The type of key contained in the maps.
    
    V - The type of value contained in the maps.
    
    Parameters:
    
    map - The map whose elements are to be reduced.
    
    keys - The set of keys for the associates to be saved.
    
    Returns:
    
    The resulting map.

Class Map<K,V>

Constructor Summary

Method Summary

Methods inherited from class craterdog.collections.abstractions.SortableCollection

Methods inherited from class craterdog.collections.abstractions.Collection

Methods inherited from class java.lang.Object

Methods inherited from interface craterdog.core.Sequential

Methods inherited from interface java.lang.Iterable

Methods inherited from interface craterdog.core.Composite

Constructor Detail

Map

Map

Map

Map

Map

Method Detail

getNumberOfElements

containsElement

createDefaultIterator

addElement

removeElement

removeAllElements

createDefaultManipulator

getKeys

getValues

getAssociations

getValueForKey

associateKeyWithValue

removeValueForKey

concatenate

reduce