Cleaned up the Hash Array Mapped Trie (HAMT) data structure.

git-svn-id: https://java-algorithms-implementation.googlecode.com/svn/trunk@431 032fbc0f-8cab-eb90-e552-f08422b9a96a

Author: phishman3579

src/com/jwetherell/algorithms/data_structures/HashArrayMappedTrie.java

@@ -9,23 +9,30 @@
  * array that combines the characteristics of a hash table and an array mapped 
  * trie. It is a refined version of the more general notion of a hash tree.
  * 
+ * This implementation is 32-bit and steps in 5-bit intervals, maximum tree
+ * height of 7.
+ * 
  * http://en.wikipedia.org/wiki/Hash_array_mapped_trie
  * 
  * @author Justin Wetherell <phishman3579@gmail.com>
  */
 @SuppressWarnings("unchecked")
-public class HashArrayMappedTrie<K extends Number, V> implements IMap<K,V> {
+public class HashArrayMappedTrie<K, V> implements IMap<K,V> {
 
     private static final byte MAX_BITS = 32;
     private static final byte BITS = 5;
-    private static final byte MAX_DEPTH = MAX_BITS/BITS; // default 6
+    private static final byte MAX_DEPTH = MAX_BITS/BITS; // 6
 
     private Node root = null;
     private int size = 0;
 
+    /**
+     * Convert a big-endian binary string to a little-endian binary string
+     * and also pads with zeros to make it "BITS" length.
+     * 
+     * e.g. BITS=5 value==6 big-endian=110 little-endian=011 (pad) return=01100
+     */
     private static final String toBinaryString(int value) {
-        if (value<0) return "null";
-
         StringBuilder builder = new StringBuilder(Integer.toBinaryString(value));
         builder = builder.reverse();
         while (builder.length()<BITS) {
@@ -34,11 +41,16 @@ private static final String toBinaryString(int value) {
         return builder.toString();
     }
 
-    private static final int getPosition(int level, int value) {
-        return (value >>> level*BITS) & 0x01f;
+    /**
+     * Get the "BITS" length integer starting at height*BITS position.
+     * 
+     * e.g. BITS=5 height=1 value==266 big-endian=100001010 (shifts height*BITS off the right) return=1000 (8 in decimal)
+     */
+    private static final int getPosition(int height, int value) {
+        return (value >>> height*BITS) & 0x01f;
     }
 
-    private V put(ArrayNode parent, Node node, byte level, int key, V value) {
+    private V put(ArrayNode parent, Node node, byte height, int key, V value) {
         if (node instanceof KeyValueNode) {
             KeyValueNode<V> kvNode = (KeyValueNode<V>) node;
             if (key==kvNode.key) {
@@ -48,10 +60,10 @@ private V put(ArrayNode parent, Node node, byte level, int key, V value) {
             }
             // Key already exists but doesn't match current key
             KeyValueNode<V> oldParent = kvNode;
-            int newParentPosition = getPosition(level-1, key);
-            int oldParentPosition = getPosition(level, oldParent.key);
-            int childPosition = getPosition(level, key);
-            ArrayNode newParent = new ArrayNode(parent, key, level);
+            int newParentPosition = getPosition(height-1, key);
+            int oldParentPosition = getPosition(height, oldParent.key);
+            int childPosition = getPosition(height, key);
+            ArrayNode newParent = new ArrayNode(parent, key, height);
             newParent.parent = parent;
             if (parent==null) {
                 // Only the root doesn't have a parent, so new root
@@ -69,18 +81,18 @@ private V put(ArrayNode parent, Node node, byte level, int key, V value) {
             }
             while (oldParentPosition == childPosition) {
                 // Handle the case when the new children map to same position.
-                level++;
-                if (level>MAX_DEPTH) {
+                height++;
+                if (height>MAX_DEPTH) {
                     // We have found two keys which match exactly.
                     System.err.println("Yikes! Found two keys which match exactly.");
                     return null;
                 }
-                newParentPosition = getPosition(level-1, key);
-                ArrayNode newParent2 = new ArrayNode(newParent, key, level);
+                newParentPosition = getPosition(height-1, key);
+                ArrayNode newParent2 = new ArrayNode(newParent, key, height);
                 newParent.addChild(newParentPosition, newParent2);
 
-                oldParentPosition = getPosition(level, oldParent.key);
-                childPosition = getPosition(level, key);
+                oldParentPosition = getPosition(height, oldParent.key);
+                childPosition = getPosition(height, key);
                 if (oldParentPosition != childPosition) {
                     newParent2.addChild(oldParentPosition, oldParent);
                     oldParent.parent = newParent2;
@@ -92,14 +104,14 @@ private V put(ArrayNode parent, Node node, byte level, int key, V value) {
             return value;
         } else if (node instanceof ArrayNode) {
             ArrayNode arrayRoot = (ArrayNode) node;
-            int position = getPosition(arrayRoot.level, key);
+            int position = getPosition(arrayRoot.height, key);
             Node child = arrayRoot.getChild(position);
             if (child==null) {
                 // Found an empty slot in parent
                 arrayRoot.addChild(position, new KeyValueNode<V>(arrayRoot, key, value));
                 return value;
             }
-            return put(arrayRoot, child, (byte)(level+1), key, value);
+            return put(arrayRoot, child, (byte)(height+1), key, value);
         }
         return null;
     }
@@ -109,39 +121,35 @@ private V put(ArrayNode parent, Node node, byte level, int key, V value) {
      */
     @Override
     public V put(K key, V value) {
-        //System.out.println("put="+key);
-        //System.out.println(this.toString());
-        int intKey = key.intValue();
+        int intKey = key.hashCode();
         V toReturn = null;
         if (root==null) {
             root = new KeyValueNode<V>(null, intKey, value);
             toReturn = value;
         } else {
             toReturn = put(null, root, (byte)0, intKey, value);
         }
-        //System.out.println(this.toString());
         if (toReturn!=null) size++;
         return toReturn;
     }
 
-    private Node find(Node node, K key) {
+    private Node find(Node node, int key) {
         if (node instanceof KeyValueNode) {
             KeyValueNode<V> kvNode = (KeyValueNode<V>) node;
-            if (key.equals(kvNode.key))
+            if (kvNode.key==key)
                 return kvNode;
             return null;
         } else if (node instanceof ArrayNode) {
             ArrayNode arrayNode = (ArrayNode)node;
-            int intKey = key.intValue();
-            int position = getPosition(arrayNode.level, intKey);
+            int position = getPosition(arrayNode.height, key);
             Node possibleNode = arrayNode.getChild(position);
             if (possibleNode==null) return null;
             return find(possibleNode,key);
         }
         return null;
     }
 
-    private Node find(K key) {
+    private Node find(int key) {
         if (root==null) return null;
         return find(root, key);
     }
@@ -151,23 +159,30 @@ private Node find(K key) {
      */
     @Override
     public V get(K key) {
-        Node node = find(key);
+        Node node = find(key.hashCode());
         if (node==null) return null;
         if (node instanceof KeyValueNode) return ((KeyValueNode<V>)node).value;
         return null;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean contains(K key) {
+        Node node = find(key.hashCode());
+        return (node!=null);
+    }
+
     /**
      * {@inheritDoc}
      */
     @Override
     public V remove(K key) {
-        Node node = this.find(key);
+        Node node = find(key.hashCode());
         if (node==null) return null;
         if (node instanceof ArrayNode) return null;
 
-        //System.out.println("remove="+key);
-        //System.out.println(this.toString());
         KeyValueNode<V> kvNode = (KeyValueNode<V>)node;
         V value = kvNode.value;
         if (node.parent==null) {
@@ -176,7 +191,7 @@ public V remove(K key) {
         } else {
             ArrayNode parent = node.parent;
             // Remove child from parent
-            int position = getPosition(parent.level, node.key);
+            int position = getPosition(parent.height, node.key);
             parent.removeChild(position);
             // Go back up the tree, pruning any array nodes which no longer have children.
             int numOfChildren = parent.getNumberOfChildren();
@@ -188,25 +203,15 @@ public V remove(K key) {
                     root = null;
                     break;
                 }
-                position = getPosition(parent.level, node.key);
+                position = getPosition(parent.height, node.key);
                 parent.removeChild(position);
                 numOfChildren = parent.getNumberOfChildren();
             }
         }
-        //System.out.println(this.toString());
         size--;
         return value;
     }
 
-    /**
-     * {@inheritDoc}
-     */
-    @Override
-    public boolean contains(K key) {
-        Node node = find(key);
-        return (node!=null);
-    }
-
     /**
      * {@inheritDoc}
      */
@@ -215,18 +220,18 @@ public int size() {
         return size;
     }
 
-    private static <K extends Number, V> boolean validate(ArrayNode parent, KeyValueNode<V> child) {
-        if (parent==null || parent.level==0) return true;
+    private static <K, V> boolean validate(ArrayNode parent, KeyValueNode<V> child) {
+        if (parent==null || parent.height==0) return true;
 
-        int parentPosition = getPosition(parent.level-1,parent.key);
-        int childPosition = getPosition(parent.level-1,child.key);
+        int parentPosition = getPosition(parent.height-1,parent.key);
+        int childPosition = getPosition(parent.height-1,child.key);
         return (childPosition==parentPosition);
     }
 
-    private static <K extends Number, V> boolean validate(ArrayNode parent, ArrayNode node) {
+    private static <K, V> boolean validate(ArrayNode parent, ArrayNode node) {
         if (parent!=null) {
             if (parent.key != (node.parent.key)) return false;
-            if (parent.level+1 != node.level) return false;
+            if (parent.height+1 != node.height) return false;
         }
 
         int children = 0;
@@ -278,33 +283,59 @@ protected static class Node {
 
     private static final class ArrayNode extends Node {
 
-        private byte level = 0;
+        private byte height = 0;
         private int bitmap = 0;
         private Node[] children = new Node[2];
 
-        private ArrayNode(ArrayNode parent, int key, byte level) {
+        private ArrayNode(ArrayNode parent, int key, byte height) {
             this.parent = parent;
             this.key = key;
-            this.level = level;
+            this.height = height;
         }
 
+        /**
+         * Set the bit at position (zero based)
+         * 
+         * e.g. bitmap=0000 position==3 result=1000
+         */
         private void set(int position) {
             bitmap |= (1 << position);
         }
 
+        /**
+         * Unset the bit at position (zero based)
+         * 
+         * e.g. bitmap==110 position=1 result=100
+         */
         private void unset(int position) {
             bitmap &= ~(1 << position);
         }
 
+        /**
+         * Is the bit at position set (zero based)
+         * 
+         * e.g. bitmap=01110 position=3 result=00110
+         */
         private boolean isSet(int position) {
             return ((bitmap &(1 << position)) >>> position)==1;
         }
 
+        /**
+         * Count the number of 1s in the bitmap between 0 and position (zero based)
+         * 
+         * Because each 1 in the bitmap means a child exists, you can use the 1s count
+         * to calculate the index of the child at the given position.
+         * 
+         * e.g. bitmap=01110010 position=5 result=3
+         */
         private int getIndex(int position){
             position = (1 << position)-1;
             return Integer.bitCount(bitmap & position);
         }
 
+        /**
+         * Calculates the height by doubling the size with a max size of MAX_BITS
+         */
         private static int calcNewLength(int size) {
             if (size==MAX_BITS) return size;
 
@@ -362,7 +393,7 @@ private int getNumberOfChildren() {
         @Override
         public String toString() {
             StringBuilder builder = new StringBuilder();
-            builder.append("level=").append(level).append(" key=").append(toBinaryString(key)).append("\n");
+            builder.append("height=").append(height).append(" key=").append(toBinaryString(key)).append("\n");
             for (int i=0; i<MAX_BITS; i++) {
                 Node c = getChild(i);
                 if (c!=null) builder.append(c.toString()).append(", ");
@@ -401,32 +432,32 @@ public String toString() {
 
     protected static class TreePrinter {
 
-        public static <K extends Number, V> String getString(HashArrayMappedTrie<K,V> tree) {
+        public static <K, V> String getString(HashArrayMappedTrie<K,V> tree) {
             if (tree.root == null) return "Tree has no nodes.";
-            return getString(tree.root, -1, "", true);
+            return getString(null, tree.root, -1, "", true);
         }
 
-        private static <K, V> String getString(Node node, int level, String prefix, boolean isTail) {
+        private static <K, V> String getString(Node parent, Node node, int height, String prefix, boolean isTail) {
             StringBuilder builder = new StringBuilder();
 
             if (node instanceof KeyValueNode) {
                 KeyValueNode<V> kvNode = (KeyValueNode<V>) node;
-                int position = getPosition(level,kvNode.key);
-                builder.append(prefix + (isTail ? "└── " : "├── ") + toBinaryString(position) + "=" + toBinaryString(kvNode.key) + "=" + kvNode.value + "\n");
+                int position = getPosition(height,kvNode.key);
+                builder.append(prefix + (isTail ? "└── " : "├── ") + ((parent==null)?null:toBinaryString(position)) + "=" + toBinaryString(kvNode.key) + "=" + kvNode.value + "\n");
             } else {
                 ArrayNode arrayNode = (ArrayNode) node;
-                int position = getPosition(level,arrayNode.key);
-                builder.append(prefix + (isTail ? "└── " : "├── ") + toBinaryString(position) + " level=" + arrayNode.level + " bitmap=" + toBinaryString(arrayNode.bitmap) + "\n");
+                int position = (arrayNode.parent==null)?-1:getPosition(height,arrayNode.key);
+                builder.append(prefix + (isTail ? "└── " : "├── ") + ((parent==null)?null:toBinaryString(position)) + " height=" + ((height<0)?null:height) + " bitmap=" + toBinaryString(arrayNode.bitmap) + "\n");
                 List<Node> children = new LinkedList<Node>();
                 for (int i=0; i<MAX_BITS; i++) {
                     Node child = arrayNode.getChild(i);
                     if (child != null) children.add(child);
                 }
                 for (int i = 0; i<(children.size()-1); i++) {
-                    builder.append(getString(children.get(i), level+1, prefix+(isTail ? "    " : "│   "), false));
+                    builder.append(getString(arrayNode, children.get(i), height+1, prefix+(isTail ? "    " : "│   "), false));
                 }
                 if (children.size() >= 1) {
-                    builder.append(getString(children.get(children.size()-1), level+1, prefix+(isTail ? "    " : "│   "), true));
+                    builder.append(getString(arrayNode, children.get(children.size()-1), height+1, prefix+(isTail ? "    " : "│   "), true));
                 }
             }
             return builder.toString();
@@ -441,7 +472,7 @@ public Map<K,V> toMap() {
         return (new JavaCompatibleHashMap<K,V>(this));
     }
 
-    private static class JavaCompatibleIteratorWrapper<K extends Number,V> implements java.util.Iterator<java.util.Map.Entry<K, V>> {
+    private static class JavaCompatibleIteratorWrapper<K,V> implements java.util.Iterator<java.util.Map.Entry<K, V>> {
 
         private HashArrayMappedTrie<K,V> map = null;
         private java.util.Iterator<java.util.Map.Entry<K, V>> iter = null;
@@ -484,7 +515,7 @@ public void remove() {
         }
     }
 
-    private static class JavaCompatibleMapEntry<K extends Number,V> extends java.util.AbstractMap.SimpleEntry<K,V> {
+    private static class JavaCompatibleMapEntry<K,V> extends java.util.AbstractMap.SimpleEntry<K,V> {
 
         private static final long serialVersionUID = -2943023801121889519L;
 
@@ -493,7 +524,7 @@ public JavaCompatibleMapEntry(K key, V value) {
         }
     }
 
-    private static class JavaCompatibleHashMap<K extends Number, V> extends java.util.AbstractMap<K,V> {
+    private static class JavaCompatibleHashMap<K, V> extends java.util.AbstractMap<K,V> {
 
         private HashArrayMappedTrie<K,V> map = null;