Package totalcross.util

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

    • Field Summary

      Fields 
      Modifier and Type Field 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 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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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

      • 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