ch.javasoft.util.intcoll
Class IntHashMap<V>

java.lang.Object
  ch.javasoft.util.intcoll.IntHashMap<V>

All Implemented Interfaces:

IntMap<V>, Serializable, Cloneable, Map<Integer,V>

public class IntHashMap<V>
extends Object
implements IntMap<V>, Cloneable, Serializable

Same as HashMap, but implementing IntMap.

Hash table based implementation of the Map interface. This implementation provides all of the optional map operations, and permits null values and the null key. (The IntHashMap class is roughly equivalent to Hashtable, except that it is unsynchronized and permits nulls.) This class makes no guarantees as to the order of the map; in particular, it does not guarantee that the order will remain constant over time.

This implementation provides constant-time performance for the basic operations (get and put), assuming the hash function disperses the elements properly among the buckets. Iteration over collection views requires time proportional to the "capacity" of the IntHashMap instance (the number of buckets) plus its size (the number of key-value mappings). Thus, it's very important not to set the initial capacity too high (or the load factor too low) if iteration performance is important.

An instance of IntHashMap has two parameters that affect its performance: initial capacity and load factor. The capacity is the number of buckets in the hash table, and the initial capacity is simply the capacity at the time the hash table is created. The load factor is a measure of how full the hash table is allowed to get before its capacity is automatically increased. When the number of entries in the hash table exceeds the product of the load factor and the current capacity, the capacity is roughly doubled by calling the rehash method.

As a general rule, the default load factor (.75) offers a good tradeoff between time and space costs. Higher values decrease the space overhead but increase the lookup cost (reflected in most of the operations of the IntHashMap class, including get and put). The expected number of entries in the map and its load factor should be taken into account when setting its initial capacity, so as to minimize the number of rehash operations. If the initial capacity is greater than the maximum number of entries divided by the load factor, no rehash operations will ever occur.

If many mappings are to be stored in a IntHashMap instance, creating it with a sufficiently large capacity will allow the mappings to be stored more efficiently than letting it perform automatic rehashing as needed to grow the table.

Note that this implementation is not synchronized. If multiple threads access this map concurrently, and at least one of the threads modifies the map structurally, it must be synchronized externally. (A structural modification is any operation that adds or deletes one or more mappings; merely changing the value associated with a key that an instance already contains is not a structural modification.) This is typically accomplished by synchronizing on some object that naturally encapsulates the map. If no such object exists, the map should be "wrapped" using the Collections.synchronizedMap method. This is best done at creation time, to prevent accidental unsynchronized access to the map:

 Map m = Collections.synchronizedMap(new IntHashMap(...));
 

The iterators returned by all of this class's "collection view methods" are fail-fast: if the map is structurally modified at any time after the iterator is created, in any way except through the iterator's own remove or add methods, the iterator will throw a ConcurrentModificationException. Thus, in the face of concurrent modification, the iterator fails quickly and cleanly, rather than risking arbitrary, non-deterministic behavior at an undetermined time in the future.

Note that the fail-fast behavior of an iterator cannot be guaranteed as it is, generally speaking, impossible to make any hard guarantees in the presence of unsynchronized concurrent modification. Fail-fast iterators throw ConcurrentModificationException on a best-effort basis. Therefore, it would be wrong to write a program that depended on this exception for its correctness: the fail-fast behavior of iterators should be used only to detect bugs.

This class is a member of the Java Collections Framework.

Since:

1.2

Version:

1.63, 02/19/04

Author:

Doug Lea, Josh Bloch, Arthur van Hoff, Neal Gafter

See Also:

Object.hashCode(), Collection, Map, TreeMap, Hashtable, IntHashMap, Serialized Form

Nested Class Summary

static class

IntHashMap.IntEntry<VV>

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Field Summary

static int	DEFAULT_INITIAL_CAPACITY The default initial capacity - MUST be a power of two.
static float	DEFAULT_LOAD_FACTOR The load factor used when none specified in constructor.
protected ch.javasoft.util.intcoll.IntHashMap.IntEntrySet	entrySet
protected IntSet	keySet
static int	MAXIMUM_CAPACITY The maximum capacity, used if a higher value is implicitly specified by either of the constructors with arguments.
protected Collection<V>	values

Constructor Summary

IntHashMap()
Constructs an empty IntHashMap with the default initial capacity (16) and the default load factor (0.75).

IntHashMap(int initialCapacity)
Constructs an empty IntHashMap with the specified initial capacity and the default load factor (0.75).

IntHashMap(int initialCapacity, float loadFactor)
Constructs an empty IntHashMap with the specified initial capacity and load factor.

IntHashMap(Map<? extends Integer,? extends V> m)
Constructs a new IntHashMap with the same mappings as the specified Map.

Method Summary

void	clear() Removes all mappings from this map.
IntHashMap<V>	clone() Returns a shallow copy of this IntHashMap instance: the keys and values themselves are not cloned.
boolean	containsKey(int key) Returns true if this map contains a mapping for the specified key.
boolean	containsKey(Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(Object value) Returns true if this map maps one or more keys to the specified value.
Set<Map.Entry<Integer,V>>	entrySet() Returns a collection view of the mappings contained in this map.
boolean	equals(Object o) Compares the specified object with this map for equality.
V	get(int key) Returns the value to which the specified key is mapped in this identity hash map, or null if the map contains no mapping for this key.
V	get(Object key) Returns the value to which the specified key is mapped in this identity hash map, or null if the map contains no mapping for this key.
protected IntHashMap.IntEntry<V>	getEntry(int key) Returns the entry associated with the specified key in the IntHashMap.
int	hashCode() Returns the hash code value for this map.
protected int	indexFor(int key, int length) Returns index for key
Set<IntMap.IntEntry<V>>	intEntrySet()
boolean	isEmpty() Returns true if this map contains no key-value mappings.
IntSet	keySet() Returns a set view of the keys contained in this map.
protected Iterator<Map.Entry<Integer,V>>	newEntryIterator()
protected Iterator<IntMap.IntEntry<V>>	newIntEntryIterator()
protected IntIterator	newKeyIterator()
protected Iterator<V>	newValueIterator()
V	put(Integer key, V value) Associates the specified value with the specified key in this map.
V	put(int key, V value) Associates the specified value with the specified key in this map.
void	putAll(IntMap<? extends V> map) Copies all of the mappings from the specified map to this map These mappings will replace any mappings that this map had for any of the keys currently in the specified map.
void	putAll(Map<? extends Integer,? extends V> m) Copies all of the mappings from the specified map to this map These mappings will replace any mappings that this map had for any of the keys currently in the specified map.
V	remove(int key) Removes the mapping for this key from this map if present.
V	remove(Object key) Removes the mapping for this key from this map if present.
protected IntHashMap.IntEntry<V>	removeEntryForKey(int key) Removes and returns the entry associated with the specified key in the IntHashMap.
protected IntHashMap.IntEntry<V>	removeMapping(Object o) Special version of remove for EntrySet.
protected void	resize(int newCapacity) Rehashes the contents of this map into a new array with a larger capacity.
int	size() Returns the number of key-value mappings in this map.
String	toString() Returns a string representation of this map.
Collection<V>	values() Returns a collection view of the values contained in this map.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_INITIAL_CAPACITY

public static final int DEFAULT_INITIAL_CAPACITY

The default initial capacity - MUST be a power of two.

See Also:

Constant Field Values

MAXIMUM_CAPACITY

public static final int MAXIMUM_CAPACITY

The maximum capacity, used if a higher value is implicitly specified by either of the constructors with arguments. MUST be a power of two <= 1<<30.

See Also:

Constant Field Values

DEFAULT_LOAD_FACTOR

public static final float DEFAULT_LOAD_FACTOR

The load factor used when none specified in constructor.

See Also:

Constant Field Values

entrySet

protected transient ch.javasoft.util.intcoll.IntHashMap.IntEntrySet entrySet

keySet

protected transient volatile IntSet keySet

values

protected transient volatile Collection<V> values

Constructor Detail

IntHashMap

public IntHashMap(int initialCapacity,
                  float loadFactor)

Constructs an empty IntHashMap with the specified initial capacity and load factor.

Parameters:

initialCapacity - The initial capacity.

loadFactor - The load factor.

Throws:

IllegalArgumentException - if the initial capacity is negative or the load factor is nonpositive.

IntHashMap

public IntHashMap(int initialCapacity)

Constructs an empty IntHashMap with the specified initial capacity and the default load factor (0.75).

Parameters:

initialCapacity - the initial capacity.

Throws:

IllegalArgumentException - if the initial capacity is negative.

IntHashMap

public IntHashMap()

Constructs an empty IntHashMap with the default initial capacity (16) and the default load factor (0.75).

IntHashMap

public IntHashMap(Map<? extends Integer,? extends V> m)

Constructs a new IntHashMap with the same mappings as the specified Map. The IntHashMap is created with default load factor (0.75) and an initial capacity sufficient to hold the mappings in the specified Map.

Parameters:

m - the map whose mappings are to be placed in this map.

Throws:

NullPointerException - if the specified map is null.

Method Detail

indexFor

protected int indexFor(int key,
                       int length)

Returns index for key

size

public int size()

Returns the number of key-value mappings in this map.

Specified by:

size in interface Map<Integer,V>

Returns:

the number of key-value mappings in this map.

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings.

Specified by:

isEmpty in interface Map<Integer,V>

Returns:

true if this map contains no key-value mappings.

get

public V get(Object key)

Returns the value to which the specified key is mapped in this identity hash map, or null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it is also possible that the map explicitly maps the key to null. The containsKey method may be used to distinguish these two cases.

Specified by:

get in interface Map<Integer,V>

Parameters:

key - the key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key.

See Also:

Map.put(Object, Object)

get

public V get(int key)

Returns the value to which the specified key is mapped in this identity hash map, or null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it is also possible that the map explicitly maps the key to null. The containsKey method may be used to distinguish these two cases.

Specified by:

get in interface IntMap<V>

Parameters:

key - the key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key.

See Also:

Map.put(Object, Object)

containsKey

public boolean containsKey(int key)

Returns true if this map contains a mapping for the specified key.

Specified by:

containsKey in interface IntMap<V>

Parameters:

key - The key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key.

containsKey

public boolean containsKey(Object key)

Returns true if this map contains a mapping for the specified key.

Specified by:

containsKey in interface Map<Integer,V>

Parameters:

key - The key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key.

getEntry

protected IntHashMap.IntEntry<V> getEntry(int key)

Returns the entry associated with the specified key in the IntHashMap. Returns null if the IntHashMap contains no mapping for this key.

put

public V put(Integer key,
             V value)

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced.

Specified by:

put in interface Map<Integer,V>

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the IntHashMap previously associated null with the specified key.

Throws:

NullPointerException - if the key is null

put

public V put(int key,
             V value)

Associates the specified value with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced.

Specified by:

put in interface IntMap<V>

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the IntHashMap previously associated null with the specified key.

Throws:

NullPointerException - if the key is null

resize

protected void resize(int newCapacity)

Rehashes the contents of this map into a new array with a larger capacity. This method is called automatically when the number of keys in this map reaches its threshold. If current capacity is MAXIMUM_CAPACITY, this method does not resize the map, but sets threshold to Integer.MAX_VALUE. This has the effect of preventing future calls.

Parameters:

newCapacity - the new capacity, MUST be a power of two; must be greater than current capacity unless current capacity is MAXIMUM_CAPACITY (in which case value is irrelevant).

putAll

public void putAll(IntMap<? extends V> map)

Copies all of the mappings from the specified map to this map These mappings will replace any mappings that this map had for any of the keys currently in the specified map.

Specified by:

putAll in interface IntMap<V>

Parameters:

map - mappings to be stored in this map.

Throws:

NullPointerException - if the specified map is null.

putAll

public void putAll(Map<? extends Integer,? extends V> m)

Copies all of the mappings from the specified map to this map These mappings will replace any mappings that this map had for any of the keys currently in the specified map.

Specified by:

putAll in interface Map<Integer,V>

Parameters:

m - mappings to be stored in this map.

Throws:

NullPointerException - if the specified map is null.

remove

public V remove(int key)

Removes the mapping for this key from this map if present.

Specified by:

remove in interface IntMap<V>

Parameters:

key - key whose mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key.

remove

public V remove(Object key)

Removes the mapping for this key from this map if present.

Specified by:

remove in interface Map<Integer,V>

Parameters:

key - key whose mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key.

removeEntryForKey

protected IntHashMap.IntEntry<V> removeEntryForKey(int key)

Removes and returns the entry associated with the specified key in the IntHashMap. Returns null if the IntHashMap contains no mapping for this key.

removeMapping

protected IntHashMap.IntEntry<V> removeMapping(Object o)

Special version of remove for EntrySet.

clear

public void clear()

Removes all mappings from this map.

Specified by:

clear in interface Map<Integer,V>

containsValue

public boolean containsValue(Object value)

Returns true if this map maps one or more keys to the specified value.

Specified by:

containsValue in interface Map<Integer,V>

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this map maps one or more keys to the specified value.

clone

public IntHashMap<V> clone()

Returns a shallow copy of this IntHashMap instance: the keys and values themselves are not cloned.

Overrides:

clone in class Object

Returns:

a shallow copy of this map.

newKeyIterator

protected IntIterator newKeyIterator()

newValueIterator

protected Iterator<V> newValueIterator()

newIntEntryIterator

protected Iterator<IntMap.IntEntry<V>> newIntEntryIterator()

newEntryIterator

protected Iterator<Map.Entry<Integer,V>> newEntryIterator()

keySet

public IntSet keySet()

Returns a set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. The set supports element removal, which removes the corresponding mapping from this map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:

keySet in interface IntMap<V>

Specified by:

keySet in interface Map<Integer,V>

Returns:

a set view of the keys contained in this map.

values

public Collection<V> values()

Returns a collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from this map, via the Iterator.remove, Collection.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:

values in interface Map<Integer,V>

Returns:

a collection view of the values contained in this map.

entrySet

public Set<Map.Entry<Integer,V>> entrySet()

Returns a collection view of the mappings contained in this map. Each element in the returned collection is a Map.Entry. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:

entrySet in interface IntMap<V>

Specified by:

entrySet in interface Map<Integer,V>

Returns:

a collection view of the mappings contained in this map.

See Also:

Map.Entry

intEntrySet

public Set<IntMap.IntEntry<V>> intEntrySet()

Specified by:

intEntrySet in interface IntMap<V>

equals

public boolean equals(Object o)

Compares the specified object with this map for equality. Returns true if the given object is also a map and the two maps represent the same mappings. More formally, two maps t1 and t2 represent the same mappings if t1.keySet().equals(t2.keySet()) and for every key k in t1.keySet(), (t1.get(k)==null ? t2.get(k)==null : t1.get(k).equals(t2.get(k))) . This ensures that the equals method works properly across different implementations of the map interface.

This implementation first checks if the specified object is this map; if so it returns true. Then, it checks if the specified object is a map whose size is identical to the size of this set; if not, it returns false. If so, it iterates over this map's entrySet collection, and checks that the specified map contains each mapping that this map contains. If the specified map fails to contain such a mapping, false is returned. If the iteration completes, true is returned.

Specified by:

equals in interface Map<Integer,V>

Overrides:

equals in class Object

Parameters:

o - object to be compared for equality with this map.

Returns:

true if the specified object is equal to this map.

hashCode

public int hashCode()

Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hash codes of each entry in the map's entrySet() view. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two maps t1 and t2, as required by the general contract of Object.hashCode.

This implementation iterates over entrySet(), calling hashCode on each element (entry) in the Collection, and adding up the results.

Specified by:

hashCode in interface Map<Integer,V>

Overrides:

hashCode in class Object

Returns:

the hash code value for this map.

See Also:

Map.Entry.hashCode(), Object.hashCode(), Object.equals(Object), Set.equals(Object)

toString

public String toString()

Returns a string representation of this map. The string representation consists of a list of key-value mappings in the order returned by the map's entrySet view's iterator, enclosed in braces ("{}"). Adjacent mappings are separated by the characters ", " (comma and space). Each key-value mapping is rendered as the key followed by an equals sign ("=") followed by the associated value. Keys and values are converted to strings as by String.valueOf(Object).

This implementation creates an empty string buffer, appends a left brace, and iterates over the map's entrySet view, appending the string representation of each map.entry in turn. After appending each entry except the last, the string ", " is appended. Finally a right brace is appended. A string is obtained from the stringbuffer, and returned.

Overrides:

toString in class Object

Returns:

a String representation of this map.