danbikel.util
Interface MapToPrimitive<K>

All Superinterfaces:

Map<K,Object>

All Known Subinterfaces:

CountsTable<K>

All Known Implementing Classes:

AbstractMapToPrimitive, BiCountsTable, CountsTableImpl, FileBackedTrainerEventMap, HashMapDouble, HashMapInt, HashMapPrimitive, HashMapTwoDoubles, HashMapTwoInts, ProbabilityCache

public interface MapToPrimitive<K>
extends Map<K,Object>

Specifies methods that allow mappings from arbitrary objects to primitive types that are bundled in the map entries for efficiency. This interface specifies methods to access map entries directly via a key in the map, (via the getEntry(K) and getEntryMRU(K) methods) both to obtain the "canonical" key objects contained in the map, as well as to get at the primitive values for those keys more efficiently. Finally, this interface specifies methods useful to building caches that wish to implement various cache-replacement strategies.

The methods specified both in this interface and in the MapToPrimitive.Entry interface allow implementors to associate multiple primitive types with each key, and for each primitive type, there can be multiple vales of that type, accessible via index. For example, if an implementation simply stored one byte value for each key, then it would create map entries that extended AbstractPrimitiveMapEntry and that overrode only the MapToPrimitive.Entry.numBytes(), MapToPrimitive.Entry.getByteValue() and MapToPrimitive.Entry.getByteValue(int) methods. The MapToPrimitive.Entry#numBytes() method would simply return 1, and the other two methods would return the byte value (the implementation of getByteValue(int) should throw an exception if the argument is anything other than 0, as specified in the API documentation for that method).

Nested Class Summary

static interface

MapToPrimitive.Entry<K> Interface that provides methods for all the possible primitive types that could be associated with keys in a MapToPrimitive map.

Method Summary

void	add(K key, byte addend) Adds the specified addend to the byte value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend.
void	add(K key, double addend) Adds the specified addend to the double value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend.
void	add(K key, float addend) Adds the specified addend to the float value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend.
void	add(K key, int addend) Adds the specified addend to the int value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend.
void	add(K key, int index, byte addend) Adds the specified addend to the byte value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index.
void	add(K key, int index, double addend) Adds the specified addend to the double value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index.
void	add(K key, int index, float addend) Adds the specified addend to the float value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index.
void	add(K key, int index, int addend) Adds the specified addend to the int value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index.
void	add(K key, int index, long addend) Adds the specified addend to the long value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index.
void	add(K key, int index, short addend) Adds the specified addend to the short value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index.
void	add(K key, long addend) Adds the specified addend to the long value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend.
void	add(K key, short addend) Adds the specified addend to the short value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend.
MapToPrimitive.Entry	getEntry(K key) Gets the map entry associated with the specified key, or null if this map does not contain such a mapping.
MapToPrimitive.Entry	getEntry(K key, int hashCode)
MapToPrimitive.Entry	getEntryMRU(K key) Returns the map entry for the specified key and, as a side-effect, puts the map entry at the front of the bucket list, indicating that it is the most-recently used entry (useful for caches implementing a bucket-LRU replacement scheme).
MapToPrimitive.Entry	getEntryMRU(K key, int hashCode)
byte	put(K key, byte value) Associates the specified byte value (at index 0) with the specified key.
char	put(K key, char value)
double	put(K key, double value)
float	put(K key, float value)
int	put(K key, int value)
byte	put(K key, int index, byte value)
char	put(K key, int index, char value)
double	put(K key, int index, double value)
float	put(K key, int index, float value)
int	put(K key, int index, int value)
long	put(K key, int index, long addend)
short	put(K key, int index, short value)
long	put(K key, long addend)
short	put(K key, short value)
void	removeRandom() Removes a random mapping from this map (optional operation).
void	removeRandom(int bucketIndex) Removes a random from the bucket at the specified index (optional operation).

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

getEntry

MapToPrimitive.Entry getEntry(K key)

Gets the map entry associated with the specified key, or null if this map does not contain such a mapping. This is the preferred way to obtain a value for a key, as nullity serves as a check for whether a mapping exists for the specified key.

Parameters:

key - the key for which to look up a map entry

Returns:

the map entry for the specified key, or null if no such mapping exists in this map

getEntry

MapToPrimitive.Entry getEntry(K key,
                              int hashCode)

getEntryMRU

MapToPrimitive.Entry getEntryMRU(K key)

Returns the map entry for the specified key and, as a side-effect, puts the map entry at the front of the bucket list, indicating that it is the most-recently used entry (useful for caches implementing a bucket-LRU replacement scheme). This is an optional operation.

Parameters:

key - the key whose map entry is to be retrieved and made the MRU in its bucket inside the hash map

Returns:

the map entry for the specified key and, as a side-effect, puts the map entry at the front of the bucket list, indicating that it is the most-recently used entry

Throws:

UnsupportedOperationException - if this map is not a hash map

getEntryMRU

MapToPrimitive.Entry getEntryMRU(K key,
                                 int hashCode)

removeRandom

void removeRandom()

Removes a random mapping from this map (optional operation).

Throws:

UnsupportedOperationException - if this operation is not supported

removeRandom

void removeRandom(int bucketIndex)

Removes a random from the bucket at the specified index (optional operation).

Parameters:

bucketIndex - the index of the bucket from which to remove an element

Throws:

IllegalArgumentException - if

0 <= bucketIndex < getCapacity()

is false

UnsupportedOperationException - if this map is not a hash map

put

byte put(K key,
         byte value)

Associates the specified byte value (at index 0) with the specified key.

Returns:

the previous byte value associated with this key; if there was no previous mapping for the specified key or if the previous mapping mapped the key to 0b (the default value for byte instance variables), then 0b is returned; the containsKey method can be used to distinguish between these two cases

Throws:

UnsupportedOperationException - if this map does not map keys to byte values

put

byte put(K key,
         int index,
         byte value)

add

void add(K key,
         byte addend)

Adds the specified addend to the byte value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend. If this map maps keys to multiple byte values, then the other bytes will be set to their default instance-variable value, 0.

Parameters:

key - the key whose byte value is to be incremented

addend - the amount by which to increment the byte value for the specified key

add

void add(K key,
         int index,
         byte addend)

Adds the specified addend to the byte value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index. If this map maps keys to multiple byte values, then the other bytes will be set to their default instance-variable value, 0.

Parameters:

key - the key whose byte value is to be incremented, or for which a mapping is to be added to the specified addend

index - the index of the byte value to be incremented

addend - the amount by which to increment the byte value for the specified key

put

char put(K key,
         char value)

put

char put(K key,
         int index,
         char value)

put

short put(K key,
          short value)

put

short put(K key,
          int index,
          short value)

add

void add(K key,
         short addend)

Adds the specified addend to the short value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend. If this map maps keys to multiple short values, then the other shorts will be set to their default instance-variable value, 0.

Parameters:

key - the key whose short value is to be incremented

addend - the amount by which to increment the short value for the specified key

add

void add(K key,
         int index,
         short addend)

Adds the specified addend to the short value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index. If this map maps keys to multiple short values, then the other shorts will be set to their default instance-variable value, 0.

Parameters:

key - the key whose short value is to be incremented, or for which a mapping is to be added to the specified addend

index - the index of the short value to be incremented

addend - the amount by which to increment the short value for the specified key

Throws:

IllegalArgumentException - if the index is out of range

put

int put(K key,
        int value)

put

int put(K key,
        int index,
        int value)

add

void add(K key,
         int addend)

Adds the specified addend to the int value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend. If this map maps keys to multiple int values, then the other ints will be set to their default instance-variable value, 0.

Parameters:

key - the key whose int value is to be incremented

addend - the amount by which to increment the int value for the specified key

add

void add(K key,
         int index,
         int addend)

Adds the specified addend to the int value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index. If this map maps keys to multiple int values, then the other ints will be set to their default instance-variable value, 0.

Parameters:

key - the key whose int value is to be incremented, or for which a mapping is to be added to the specified addend

index - the index of the int value to be incremented

addend - the amount by which to increment the int value for the specified key

put

long put(K key,
         long addend)

put

long put(K key,
         int index,
         long addend)

add

void add(K key,
         long addend)

Adds the specified addend to the long value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend. If this map maps keys to multiple long values, then the other longs will be set to their default instance-variable value, 0.

Parameters:

key - the key whose long value is to be incremented

addend - the amount by which to increment the long value for the specified key

add

void add(K key,
         int index,
         long addend)

Adds the specified addend to the long value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index. If this map maps keys to multiple long values, then the other longs will be set to their default instance-variable value, 0.

Parameters:

key - the key whose long value is to be incremented, or for which a mapping is to be added to the specified addend

index - the index of the long value to be incremented

addend - the amount by which to increment the long value for the specified key

put

float put(K key,
          float value)

put

float put(K key,
          int index,
          float value)

add

void add(K key,
         float addend)

Adds the specified addend to the float value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend. If this map maps keys to multiple float values, then the other floats will be set to their default instance-variable value, 0.

Parameters:

key - the key whose float value is to be incremented

addend - the amount by which to increment the float value for the specified key

add

void add(K key,
         int index,
         float addend)

Adds the specified addend to the float value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index. If this map maps keys to multiple float values, then the other floats will be set to their default instance-variable value, 0.

Parameters:

key - the key whose float value is to be incremented, or for which a mapping is to be added to the specified addend

index - the index of the float value to be incremented

addend - the amount by which to increment the float value for the specified key

put

double put(K key,
           double value)

put

double put(K key,
           int index,
           double value)

add

void add(K key,
         double addend)

Adds the specified addend to the double value (at index 0) associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend. If this map maps keys to multiple double values, then the other doubles will be set to their default instance-variable value, 0.

Parameters:

key - the key whose double value is to be incremented

addend - the amount by which to increment the double value for the specified key

add

void add(K key,
         int index,
         double addend)

Adds the specified addend to the double value at the specified index associated with the specified key, or if no mapping previously existed for the specified key, then this method adds a new map entry mapping the key to the specified addend at the specified index. If this map maps keys to multiple double values, then the other doubles will be set to their default instance-variable value, 0.

Parameters:

key - the key whose double value is to be incremented, or for which a mapping is to be added to the specified addend

index - the index of the double value to be incremented

addend - the amount by which to increment the double value for the specified key