totalcross.util

Class IntHashtable

java.lang.Object

totalcross.util.IntHashtable

public class IntHashtable
extends java.lang.Object

This class implements a hashtable, which maps keys to values. Both key and value must be integer values. If an error occurs, an Exception is returned.

An instance of Hashtable has two parameters that affect its efficiency: its capacity and its load factor. The load factor should be between 0.0 and 1.0. When the number of entries in the hashtable exceeds the product of the load factor and the current capacity, the capacity is increased by calling the rehash method. Larger load factors use memory more efficiently, at the expense of larger expected time per lookup.

If many entries are to be made into a Hashtable, creating it with a sufficiently large capacity may allow the entries to be inserted more efficiently than letting it perform automatic rehashing as needed to grow the table.

This example creates a hashtable of numbers. It uses the names of the numbers as keys:

     IntHashtable numbers = new IntHashtable(10);
     numbers.put(1, 1000);
     numbers.put(2, 2000);
     numbers.put(3, 3000);
 

To retrieve a number, use the following code:

     int i = numbers.get(2);
      // "two = " + i;
 

Don't forget to catch the ElementNotFoundException in the methods it is thrown.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IntHashtable.DuplicatedKeyException Exception thrown when allowDuplicateKeys is set to false.
protected static class	IntHashtable.Entry Hashtable collision list.

Field Summary

Fields

Modifier and Type	Field and Description
boolean	allowDuplicateKeys Set to false to throw a IntHashtable.DuplicatedKeyException if you add a key that already exists.
int	collisions Computes the number of collisions for a set of inserts.
protected int	count The total number of entries in the hash table.
protected double	loadFactor The load factor for the hashtable.
protected IntHashtable.Entry[]	table The hash table data.
protected int	threshold Rehashes the table when count exceeds this threshold.

Constructor Summary

Constructors

Constructor and Description
IntHashtable(int initialCapacity) Constructs a new, empty hashtable with the specified initial capacity and default load factor of 0.75f.
IntHashtable(int initialCapacity, double loadFactor) Constructs a new, empty hashtable with the specified initial capacity and the specified load factor.

Method Summary

Modifier and Type	Method and Description
void	clear() Clears this hashtable so that it contains no keys.
boolean	exists(int key) Checks if the value with the specified key is mapped in this hashtable.
int	get(int key) Returns the value to which the specified key is mapped in this hashtable.
int	get(int key, int defaultValue) Returns the value to which the specified key is mapped in this hashtable.
int	get(java.lang.Object key) Returns the value to which the specified key is mapped in this hashtable.
int	getKey(int pos) Returns the key at the given position, or throws ArrayIndexOutOfBounds if the given position does not exist.
IntVector	getKeys() Return an IntVector of the keys in the IntHashtable.
IntVector	getValues() Return a Vector of the values in the Hashtable.
int	incrementValue(int key, int amount) Increments the value of a key by the given amount.
int	put(int key, int value) Maps the specified key to the specified value in this hashtable.
int	put(java.lang.Object key, int value) Takes out the hashCode from the given key object and calls put(int,int).
protected void	rehash() Rehashes the contents of the hashtable into a hashtable with a larger capacity.
int	remove(int key) Removes the key (and its corresponding value) from this hashtable.
int	size() Returns the number of keys in this hashtable.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

table

protected IntHashtable.Entry[] table

The hash table data.

count

protected transient int count

The total number of entries in the hash table.

threshold

protected int threshold

Rehashes the table when count exceeds this threshold.

loadFactor

protected double loadFactor

The load factor for the hashtable.

collisions

public int collisions

Computes the number of collisions for a set of inserts. You must zero this each time you want to compute it. Here's a sample of how to determine the best values. Keep in mind that the lower collisions is better, but don't waste too much memory if its too high.

 int max = 0xFFFFFFF;
 for (int h = 5; ; h++)
 {
    IntHashtable ht = new IntHashtable(h);
    ht.put("nbsp".hashCode(),' ');
    ht.put("shy".hashCode(),'­');
    ht.put("quot".hashCode(),'"');
    ...
    if (ht.collisions < max)
    {
       Vm.debug("h: "+h+" colli: "+ht.collisions);
       max = ht.collisions;
       if (max == 0)
          break;
    }
 }
 

Since:

SuperWaba 5.71.

allowDuplicateKeys

public boolean allowDuplicateKeys

Set to false to throw a IntHashtable.DuplicatedKeyException if you add a key that already exists. Its very rare to have two Objects with same key, but it could occur. This is good to improve program's correctness.

Since:

TotalCross 1.14

Constructor Detail

IntHashtable

public IntHashtable(int initialCapacity)

Constructs a new, empty hashtable with the specified initial capacity and default load factor of 0.75f.

Parameters:

initialCapacity - The number of elements you think the hashtable will end with. The hashtable will grow if necessary, but using a number near or above the final size can improve performance.

IntHashtable

public IntHashtable(int initialCapacity,
                    double loadFactor)

Constructs a new, empty hashtable with the specified initial capacity and the specified load factor. If initialCapacity is zero, it is changed to 5.

Parameters:

initialCapacity - The number of elements you think the hashtable will end with. The hashtable will grow if necessary, but using a number near or above the final size can improve performance.

loadFactor - a number between 0.0 and 1.0.

Method Detail

clear

public void clear()

Clears this hashtable so that it contains no keys.

get

public int get(int key)
        throws ElementNotFoundException

Returns the value to which the specified key is mapped in this hashtable.

Parameters:

key - a key in the hashtable.

Returns:

the value to which the key is mapped in this hashtable.

Throws:

ElementNotFoundException - When the key was not found.

See Also:

get(int, int)

get

public int get(java.lang.Object key)
        throws ElementNotFoundException

Returns the value to which the specified key is mapped in this hashtable.

Parameters:

key - an Object who's hashcode is the key in the hashtable.

Returns:

the value to which the key is mapped in this hashtable.

Throws:

ElementNotFoundException - When the key was not found.

java.lang.NullPointerException - If the key is null

See Also:

get(int, int)

exists

public boolean exists(int key)

Checks if the value with the specified key is mapped in this hashtable.

Parameters:

key - a key in the hashtable.

Returns:

True if the key exists, false otherwise.

Since:

SuperWaba 5.8

getValues

public IntVector getValues()

Return a Vector of the values in the Hashtable. The order is the same of the getKeys method.

Since:

SuperWaba 5.11

getKeys

public IntVector getKeys()

Return an IntVector of the keys in the IntHashtable. The order is the same of the getValues method. Added ds@120. corrected by dgecawich@200

put

public int put(java.lang.Object key,
               int value)

Takes out the hashCode from the given key object and calls put(int,int). To increase safeness, set allowDuplicateKeys to false.

See Also:

put(int, int)

put

public int put(int key,
               int value)

Maps the specified key to the specified value in this hashtable.

The value can be retrieved by calling the get method with a key that is equal to the original key.

Parameters:

key - the hashtable key.

value - the value.

Returns:

the previous value of the specified key in this hashtable, or the given value if it did not have one.

Throws:

IntHashtable.DuplicatedKeyException - if allowDuplicateKeys is set to false and another key is already added.

See Also:

Object.equals(java.lang.Object), allowDuplicateKeys

rehash

protected void rehash()

Rehashes the contents of the hashtable into a hashtable with a larger capacity. This method is called automatically when the number of keys in the hashtable exceeds this hashtable's capacity and load factor.

remove

public int remove(int key)
           throws ElementNotFoundException

Removes the key (and its corresponding value) from this hashtable. This method does nothing if the key is not in the hashtable.

Parameters:

key - the key that needs to be removed.

Returns:

the value to which the key had been mapped in this hashtable, or INVALID if the key did not have a mapping.

Throws:

ElementNotFoundException - When the key was not found.

size

public int size()

Returns the number of keys in this hashtable.

Returns:

the number of keys in this hashtable.

get

public int get(int key,
               int defaultValue)

Returns the value to which the specified key is mapped in this hashtable.

Parameters:

key - a key in the hashtable.

Returns:

the value to which the key is mapped in this hashtable; or defaultValue if the key is not mapped to any value in this hashtable.

Since:

TotalCross 1.0

getKey

public int getKey(int pos)

Returns the key at the given position, or throws ArrayIndexOutOfBounds if the given position does not exist. Note that the first key has no relation with the smallest key.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the position is out of range

Since:

TotalCross 1.0

incrementValue

public int incrementValue(int key,
                          int amount)

Increments the value of a key by the given amount. If the key doesn't exist, a new one is created with the amount. Otherwise, its value is changed by the amount. This method is useful to use an IntHashtable as a multi counter.

Returns:

The current value.

Since:

TotalCross 1.2