Recent changes to Map Tutorial

Map Tutorial modified by Brian Burton

Brian Burton — Fri, 18 Apr 2014 19:57:30 -0000

--- v8
+++ v9
@@ -1,6 +1,6 @@
 The Javimmutable library provides a JImmutableMap interface that is very similar to java.util.Map.  Like other immutable interfaces all of the methods that modify the map return a new map as their result.  The old and new maps share almost all of their structure in common to minimize memory and CPU overhead.  Two implementations are provided.  Nulls are not permitted as keys but can be used as values.  Javimmutable uses assign() instead of put() and delete() instead of remove() so that when converting code from java.util.Map to JImmutableMap the compiler will find all of the places that you need to replace a simple method call with an assignment.

-JImmutables.map() uses a hash mapped integer trie to store its values.  This provides O(log32(n)) performance for all operations.  (see [Comparative Performance])  Values within the map are stored in an ordering based on the hash codes of the keys so no guarantee is made about what order a Cursor will return entries.
+JImmutables.map() uses a hash mapped integer trie to store its values.  This provides O(log32(n)) performance for all operations.  (see [Comparative Performance])  Values within the map are stored in an ordering based on the hash codes of the keys so no guarantee is made about what order a Cursor will return entries. (see [Hash Keys] for advice on selecting keys for maps)

 JImmutables.sortedMap() uses a 2-3 tree with a Comparator object to store its values.  This provides O(log2(n)) performance for all operations.  Values within the map are stored in sorted order based on the Comparator used by the tree.  Usually you will use objects which implement the Comparable interface as keys and when you do so the keys will be stored in their natural ordering.  When you need to use keys that do not implement Comparable or if you need to use a different ordering you can create the tree with your own Comparable class.  Care must be taken to write robust and correct implementations of Comparable to ensure the tree operates as expected.

Map Tutorial modified by Brian Burton

Brian Burton — Mon, 03 Mar 2014 00:39:06 -0000

--- v7
+++ v8
@@ -1,8 +1,8 @@
-The Javimmutable library provides a JImmutableMap interface that is very similar to java.util.Map.  Like other persistent interfaces all of the methods that modify the map return a new map as their result.  The old and new maps share almost all of their structure in common to minimize memory and CPU overhead.  Two implementations are provided.  Nulls are not permitted as keys but can be used as values.  Javimmutable uses assign() instead of put() and delete() instead of remove() so that when converting code from java.util.Map to JImmutableMap the compiler will find all of the places that you need to replace a simple method call with an assignment.
+The Javimmutable library provides a JImmutableMap interface that is very similar to java.util.Map.  Like other immutable interfaces all of the methods that modify the map return a new map as their result.  The old and new maps share almost all of their structure in common to minimize memory and CPU overhead.  Two implementations are provided.  Nulls are not permitted as keys but can be used as values.  Javimmutable uses assign() instead of put() and delete() instead of remove() so that when converting code from java.util.Map to JImmutableMap the compiler will find all of the places that you need to replace a simple method call with an assignment.

-JImmutableHashMap uses a hash mapped integer trie to store its values.  This provides roughly O(1) performance for all operations.  Values within the map are stored in an ordering based on the hash codes of the keys so no guarantee is made about what order a Cursor will return entries.
+JImmutables.map() uses a hash mapped integer trie to store its values.  This provides O(log32(n)) performance for all operations.  (see [Comparative Performance])  Values within the map are stored in an ordering based on the hash codes of the keys so no guarantee is made about what order a Cursor will return entries.

-JImmutableTreeMap uses a 2-3 tree with a Comparator object to store its values.  This provides O(logn) performance for all operations.  Values within the map are stored in sorted order based on the Comparator used by the tree.  Usually you will use objects which implement the Comparable interface as keys and when you do so the keys will be stored in their natural ordering.  When you need to use keys that do not implement Comparable or if you need to use a different ordering you can create the tree with your own Comparable class.  Care must be taken to write robust and correct implementations of Comparable to ensure the tree operates as expected.
+JImmutables.sortedMap() uses a 2-3 tree with a Comparator object to store its values.  This provides O(log2(n)) performance for all operations.  Values within the map are stored in sorted order based on the Comparator used by the tree.  Usually you will use objects which implement the Comparable interface as keys and when you do so the keys will be stored in their natural ordering.  When you need to use keys that do not implement Comparable or if you need to use a different ordering you can create the tree with your own Comparable class.  Care must be taken to write robust and correct implementations of Comparable to ensure the tree operates as expected.

 ~~~~~
 JImmutableMap hmap = JImmutables.map();
@@ -33,7 +33,7 @@
 assertEquals(null, hmap2.find(80).getValue());
 ~~~~~

-JImmutableMap includes an getMap() method that returns an object implementing java.util.Map.  The returned Map is immutable (set, remove, etc throw UnsupportedOperationException) and uses the original JImmutableMap to access values.  getMap() has very low overhead since contents of the JImmutableMap are not copied when creating the Map.  Use this method when you want to share the JImmutableMap's contents with code that only understands java.util.Map.
+JImmutableMap includes a getMap() method that returns an object implementing java.util.Map.  The returned Map is immutable (set, remove, etc throw UnsupportedOperationException) and uses the original JImmutableMap to access values.  getMap() has very low overhead since contents of the JImmutableMap are not copied when creating the Map.  Use this method when you want to share the JImmutableMap's contents with code that only understands java.util.Map.

 Sorted maps work exactly the same way as hash maps but their cursors provide access to entries in sorted order based on their keys.  In the example below the keySet() and values() methods provide their contents sorted based on the order of the corresponding keys in the map.

Map Tutorial modified by Brian Burton

Brian Burton — Thu, 28 Nov 2013 15:06:26 -0000

--- v6
+++ v7
@@ -40,7 +40,7 @@
 ~~~~~
 JImmutableMap smap = JImmutables.sortedMap();
 smap = smap.assign(10, 80).assign(20, 21).assign(30, 31).assign(20, 19);
-assertEquals(Arrays.asList(10, 20, 30), new ArrayList(smap.asMap().keySet()));
-assertEquals(Arrays.asList(80, 19, 31), new ArrayList(smap.asMap().values()));
+assertEquals(Arrays.asList(10, 20, 30), new ArrayList(smap.getMap().keySet()));
+assertEquals(Arrays.asList(80, 19, 31), new ArrayList(smap.getMap().values()));
 ~~~~~

Map Tutorial modified by Brian Burton

Brian Burton — Sun, 29 Sep 2013 22:06:30 -0000

--- v5
+++ v6
@@ -1,14 +1,14 @@
-The Javimmutable library provides a PersistentMap interface that is very similar to java.util.Map.  Like other persistent interfaces all of the methods that modify the map return a new map as their result.  The old and new maps share almost all of their structure in common to minimize memory and CPU overhead.  Two implementations are provided.  Nulls are not permitted as keys but can be used as values.  Javimmutable uses assign() instead of put() and delete() instead of remove() so that when converting code from java.util.Map to PersistentMap the compiler will find all of the places that you need to replace a simple method call with an assignment.
+The Javimmutable library provides a JImmutableMap interface that is very similar to java.util.Map.  Like other persistent interfaces all of the methods that modify the map return a new map as their result.  The old and new maps share almost all of their structure in common to minimize memory and CPU overhead.  Two implementations are provided.  Nulls are not permitted as keys but can be used as values.  Javimmutable uses assign() instead of put() and delete() instead of remove() so that when converting code from java.util.Map to JImmutableMap the compiler will find all of the places that you need to replace a simple method call with an assignment.

-PersistentHashMap uses a hash mapped integer trie to store its values.  This provides roughly O(1) performance for all operations.  Values within the map are stored in an ordering based on the hash codes of the keys so no guarantee is made about what order a Cursor will return entries.
+JImmutableHashMap uses a hash mapped integer trie to store its values.  This provides roughly O(1) performance for all operations.  Values within the map are stored in an ordering based on the hash codes of the keys so no guarantee is made about what order a Cursor will return entries.

-PersistentTreeMap uses a 2-3 tree with a Comparator object to store its values.  This provides O(logn) performance for all operations.  Values within the map are stored in sorted order based on the Comparator used by the tree.  Usually you will use objects which implement the Comparable interface as keys and when you do so the keys will be stored in their natural ordering.  When you need to use keys that do not implement Comparable or if you need to use a different ordering you can create the tree with your own Comparable class.  Care must be taken to write robust and correct implementations of Comparable to ensure the tree operates as expected.
+JImmutableTreeMap uses a 2-3 tree with a Comparator object to store its values.  This provides O(logn) performance for all operations.  Values within the map are stored in sorted order based on the Comparator used by the tree.  Usually you will use objects which implement the Comparable interface as keys and when you do so the keys will be stored in their natural ordering.  When you need to use keys that do not implement Comparable or if you need to use a different ordering you can create the tree with your own Comparable class.  Care must be taken to write robust and correct implementations of Comparable to ensure the tree operates as expected.

 ~~~~~
-PersistentMap hmap = Immutables.map();
+JImmutableMap hmap = JImmutables.map();
 hmap = hmap.assign(10, 11).assign(20, 21).assign(30, 31).assign(20, 19);

-PersistentMap hmap2 = hmap.delete(20).assign(18,19);
+JImmutableMap hmap2 = hmap.delete(20).assign(18,19);

 assertEquals(11, hmap.get(10));
 assertEquals(19, hmap.get(20));
@@ -20,7 +20,7 @@
 assertEquals(31, hmap2.get(30));
 ~~~~~

-The get() method operates in the same manner as java.util.Map.get().  If the map does not contain a value for the specified key null is returned.  Since PersistentMaps allow nulls as values the get() method's result can be ambiguous.  PersistentMap provides a find() method which is similar to get() but always returns a non-null Holder object that can be used to determine unambiguously whether or not a value was found matching the key.
+The get() method operates in the same manner as java.util.Map.get().  If the map does not contain a value for the specified key null is returned.  Since JImmutableMaps allow nulls as values the get() method's result can be ambiguous.  JImmutableMap provides a find() method which is similar to get() but always returns a non-null Holder object that can be used to determine unambiguously whether or not a value was found matching the key.

 ~~~~~
 hmap2 = hmap2.assign(80, null);
@@ -33,12 +33,12 @@
 assertEquals(null, hmap2.find(80).getValue());
 ~~~~~

-PersistentMap includes an getMap() method that returns an object implementing java.util.Map.  The returned Map is immutable (set, remove, etc throw UnsupportedOperationException) and uses the original PersistentMap to access values.  getMap() has very low overhead since contents of the PersistentMap are not copied when creating the Map.  Use this method when you want to share the PersistentMap's contents with code that only understands java.util.Map.
+JImmutableMap includes an getMap() method that returns an object implementing java.util.Map.  The returned Map is immutable (set, remove, etc throw UnsupportedOperationException) and uses the original JImmutableMap to access values.  getMap() has very low overhead since contents of the JImmutableMap are not copied when creating the Map.  Use this method when you want to share the JImmutableMap's contents with code that only understands java.util.Map.

 Sorted maps work exactly the same way as hash maps but their cursors provide access to entries in sorted order based on their keys.  In the example below the keySet() and values() methods provide their contents sorted based on the order of the corresponding keys in the map.

 ~~~~~
-PersistentMap smap = Immutables.sortedMap();
+JImmutableMap smap = JImmutables.sortedMap();
 smap = smap.assign(10, 80).assign(20, 21).assign(30, 31).assign(20, 19);
 assertEquals(Arrays.asList(10, 20, 30), new ArrayList(smap.asMap().keySet()));
 assertEquals(Arrays.asList(80, 19, 31), new ArrayList(smap.asMap().values()));

Map Tutorial modified by Brian Burton

Brian Burton — Sun, 29 Sep 2013 18:01:39 -0000

--- v4
+++ v5
@@ -33,7 +33,7 @@
 assertEquals(null, hmap2.find(80).getValue());
 ~~~~~

-PersistentMap includes an asMap() method that returns an object implementing java.util.Map.  The returned Map is immutable (set, remove, etc throw UnsupportedOperationException) and uses the original PersistentMap to access values.  asMap() has very low overhead since contents of the PersistentMap are not copied when creating the Map.  Use this method when you want to share the PersistentMap's contents with code that only understands java.util.Map.
+PersistentMap includes an getMap() method that returns an object implementing java.util.Map.  The returned Map is immutable (set, remove, etc throw UnsupportedOperationException) and uses the original PersistentMap to access values.  getMap() has very low overhead since contents of the PersistentMap are not copied when creating the Map.  Use this method when you want to share the PersistentMap's contents with code that only understands java.util.Map.

 Sorted maps work exactly the same way as hash maps but their cursors provide access to entries in sorted order based on their keys.  In the example below the keySet() and values() methods provide their contents sorted based on the order of the corresponding keys in the map.

Map Tutorial modified by Brian Burton

Brian Burton — Sat, 28 Sep 2013 21:39:15 -0000

--- v3
+++ v4
@@ -1,4 +1,4 @@
-The Javimmutable library provides a PersistentMap interface that is very similar to java.util.Map.  Like other persistent interfaces all of the methods that modify the map return a new map as their result.  The old and new maps share almost all of their structure in common to minimize memory and CPU overhead.  Two implementations are provided.  Nulls are not permitted as keys but can be used as values.
+The Javimmutable library provides a PersistentMap interface that is very similar to java.util.Map.  Like other persistent interfaces all of the methods that modify the map return a new map as their result.  The old and new maps share almost all of their structure in common to minimize memory and CPU overhead.  Two implementations are provided.  Nulls are not permitted as keys but can be used as values.  Javimmutable uses assign() instead of put() and delete() instead of remove() so that when converting code from java.util.Map to PersistentMap the compiler will find all of the places that you need to replace a simple method call with an assignment.

 PersistentHashMap uses a hash mapped integer trie to store its values.  This provides roughly O(1) performance for all operations.  Values within the map are stored in an ordering based on the hash codes of the keys so no guarantee is made about what order a Cursor will return entries.

Map Tutorial modified by Brian Burton

Brian Burton — Sat, 28 Sep 2013 21:37:37 -0000

--- v2
+++ v3
@@ -6,9 +6,9 @@

 ~~~~~
 PersistentMap hmap = Immutables.map();
-hmap = hmap.set(10, 11).set(20, 21).set(30, 31).set(20, 19);
+hmap = hmap.assign(10, 11).assign(20, 21).assign(30, 31).assign(20, 19);

-PersistentMap hmap2 = hmap.remove(20).set(18,19);
+PersistentMap hmap2 = hmap.delete(20).assign(18,19);

 assertEquals(11, hmap.get(10));
 assertEquals(19, hmap.get(20));
@@ -23,7 +23,7 @@
 The get() method operates in the same manner as java.util.Map.get().  If the map does not contain a value for the specified key null is returned.  Since PersistentMaps allow nulls as values the get() method's result can be ambiguous.  PersistentMap provides a find() method which is similar to get() but always returns a non-null Holder object that can be used to determine unambiguously whether or not a value was found matching the key.

 ~~~~~
-hmap2 = hmap2.set(80, null);
+hmap2 = hmap2.assign(80, null);
 assertEquals(null, hmap2.get(20));
 assertEquals(true, hmap2.find(20).isEmpty());
 // hmap2.find(20).getValue() would throw since the Holder is empty
@@ -39,7 +39,7 @@

 ~~~~~
 PersistentMap smap = Immutables.sortedMap();
-smap = smap.set(10, 80).set(20, 21).set(30, 31).set(20, 19);
+smap = smap.assign(10, 80).assign(20, 21).assign(30, 31).assign(20, 19);
 assertEquals(Arrays.asList(10, 20, 30), new ArrayList(smap.asMap().keySet()));
 assertEquals(Arrays.asList(80, 19, 31), new ArrayList(smap.asMap().values()));
 ~~~~~

Map Tutorial modified by Brian Burton

Brian Burton — Sat, 28 Sep 2013 16:53:00 -0000

--- v1
+++ v2
@@ -34,3 +34,13 @@
 ~~~~~

 PersistentMap includes an asMap() method that returns an object implementing java.util.Map.  The returned Map is immutable (set, remove, etc throw UnsupportedOperationException) and uses the original PersistentMap to access values.  asMap() has very low overhead since contents of the PersistentMap are not copied when creating the Map.  Use this method when you want to share the PersistentMap's contents with code that only understands java.util.Map.
+
+Sorted maps work exactly the same way as hash maps but their cursors provide access to entries in sorted order based on their keys.  In the example below the keySet() and values() methods provide their contents sorted based on the order of the corresponding keys in the map.
+
+~~~~~
+PersistentMap smap = Immutables.sortedMap();
+smap = smap.set(10, 80).set(20, 21).set(30, 31).set(20, 19);
+assertEquals(Arrays.asList(10, 20, 30), new ArrayList(smap.asMap().keySet()));
+assertEquals(Arrays.asList(80, 19, 31), new ArrayList(smap.asMap().values()));
+~~~~~
+

Map Tutorial modified by Brian Burton

Brian Burton — Sat, 28 Sep 2013 16:44:34 -0000

The Javimmutable library provides a PersistentMap interface that is very similar to java.util.Map. Like other persistent interfaces all of the methods that modify the map return a new map as their result. The old and new maps share almost all of their structure in common to minimize memory and CPU overhead. Two implementations are provided. Nulls are not permitted as keys but can be used as values.

PersistentHashMap uses a hash mapped integer trie to store its values. This provides roughly O(1) performance for all operations. Values within the map are stored in an ordering based on the hash codes of the keys so no guarantee is made about what order a Cursor will return entries.

PersistentTreeMap uses a 2-3 tree with a Comparator object to store its values. This provides O(logn) performance for all operations. Values within the map are stored in sorted order based on the Comparator used by the tree. Usually you will use objects which implement the Comparable interface as keys and when you do so the keys will be stored in their natural ordering. When you need to use keys that do not implement Comparable or if you need to use a different ordering you can create the tree with your own Comparable class. Care must be taken to write robust and correct implementations of Comparable to ensure the tree operates as expected.

PersistentMap<Integer, Integer> hmap = Immutables.map();
hmap = hmap.set(10, 11).set(20, 21).set(30, 31).set(20, 19);

PersistentMap<Integer, Integer> hmap2 = hmap.remove(20).set(18,19);

assertEquals(11, hmap.get(10));
assertEquals(19, hmap.get(20));
assertEquals(31, hmap.get(30));

assertEquals(11, hmap2.get(10));
assertEquals(19, hmap2.get(18));
assertEquals(null, hmap2.get(20));
assertEquals(31, hmap2.get(30));

The get() method operates in the same manner as java.util.Map.get(). If the map does not contain a value for the specified key null is returned. Since PersistentMaps allow nulls as values the get() method's result can be ambiguous. PersistentMap provides a find() method which is similar to get() but always returns a non-null Holder object that can be used to determine unambiguously whether or not a value was found matching the key.

hmap2 = hmap2.set(80, null);
assertEquals(null, hmap2.get(20));
assertEquals(true, hmap2.find(20).isEmpty());
// hmap2.find(20).getValue() would throw since the Holder is empty

assertEquals(null, hmap2.get(80));
assertEquals(false, hmap2.find(80).isEmpty());
assertEquals(null, hmap2.find(80).getValue());

PersistentMap includes an asMap() method that returns an object implementing java.util.Map. The returned Map is immutable (set, remove, etc throw UnsupportedOperationException) and uses the original PersistentMap to access values. asMap() has very low overhead since contents of the PersistentMap are not copied when creating the Map. Use this method when you want to share the PersistentMap's contents with code that only understands java.util.Map.