Improves site text.

Author: brianburton

src/site/markdown/index.md

@@ -1,15 +1,15 @@
 Overview
 ---
 
-The JImmutable Collections library provides a useful set of immutable/persistent collection classes designed with performance and ease of integration in mind. These collections are intended to replace the java.util collection classes when you require the thread safety and other benefits that immutability provides.
+The JImmutable Collections library provides a powerful set of immutable/persistent collection classes designed with performance and ease of integration in mind. These collections are intended to replace the java.util collection classes when you require the thread safety and other benefits that immutability provides.
 
-Immutability and persistence are terms which people tend to interpret in different ways. The JImmutable collection classes are immutable in the sense that once once a given collection has been created it cannot be modified. This means that it can be safely shared throughout a program without the need for synchronization or defensive copying.
+Immutability and persistence are terms which people tend to interpret in different ways. The JImmutable collection classes are immutable in the sense that once a given collection has been created it cannot be modified. This means that it can be safely shared throughout a program without the need for synchronization or defensive copying.
 
-However the collections are designed to allow themselves to be easily modified as well. Each collection provides methods for adding and removing elements. Each of these methods creates a new collection of the same type while leaving the original collection intact (i.e. the original persists). The data structures used to implement the collections (linked lists, 2-3 trees, and integer tries) allow for almost all of the structure of the original collection to be shared by the new collection. Since all objects within each collection are immutable this sharing is completely safe. The collections are persistent in the functional programming sense. The collections are not persistent in the database sense. All contents are stored in memory at all times.
+However the collections are designed to allow themselves to be easily modified as well. Each collection provides methods for adding and removing elements. Each of these methods creates a new collection of the same type while leaving the original collection intact (i.e. the original persists). The data structures used to implement the collections (linked lists, b-trees, and array mapped tries) allow for almost all of the structure of the original collection to be shared by the new collection. Since all objects within each collection are immutable this sharing is completely safe. The collections are persistent in the functional programming sense. The collections are not persistent in the database sense. All contents are stored in memory at all times.
 
 Each collection class provides adapter methods to create java.util style unmodifiable collections backed by the immutable collection. Unlike the Guava immutable collection classes these adapters do not create defensive copies of all elements from the original collections. They simply access elements within the original collection. If you have code that needs a java.util.Map to do its work you can still use a PersisentHashMap and simply call it's asMap() method when you need to pass a java.util.Map to your older code.
 
-The library uses a Cursor class to allow iteration over the collection elements. Cursor is similar to Iterator but is immutable and allows for lazy evaluation. An adapter is provided to easily turn a Cursor into an Iterator for easier integration with standard java classes. All collections implement the Iterable interface so you can use them in foreach loops.
+The collections provide methods to create efficient Iterators and Streams.  In addition the library contains a Cursor class that is similar to Iterator but is immutable and allows for lazy evaluation. All collections implement the Iterable interface so you can use them in foreach loops.
 
 The library is designed to have no dependencies on other libraries but it should interact well with others. Standard java interfaces are used where appropriate. Class names were chosen so as not to conflict with Guava's immutable container class names.
 
@@ -33,9 +33,9 @@ The library itself is distributed as a single jar so adding the jar itself to sm
 
 **List Tutorial**
 
-JImmutable Collections provides two interfaces with signatures similar to java.util.List.  Both of these interfaces provide access to elements in the List using an integer index.  As with List valid indexes are always in the range zero through `size() - 1`.  JImmutable Collections uses assign() instead of set(), insert() instead of add(), and delete() instead of remove() so that when converting code from java.util.List to JImmutableList the compiler will find all of the places that you need to replace a simple method call with an assignment.
+JImmutable Collections provides two interfaces with signatures similar to java.util.List.  Both of these interfaces provide access to elements in the list using an integer index.  As with List valid indexes are always in the range zero through `size() - 1`.  JImmutable Collections uses assign() instead of set(), insert() instead of add(), and delete() instead of remove() so that when converting code from java.util.List to JImmutableList the compiler will find all of the places that you need to replace a simple method call with an assignment.
 
-The simpler interface, JImmutableList, provides indexed access to elements within the list but restricts addition and removal of values to the end of the list.  Values added to the list are always stored in the order based on how they were added.  Cursors also traverse the values in the same order.  The current implementation uses a 32-way tree which provides O(log32(n)) performance for all operations. (see [Comparative Performance](https://github.com/brianburton/java-immutable-collections/wiki/Comparative-Performance))
+The simpler interface, JImmutableList, provides indexed access to elements within the list but restricts addition and removal of values to the end of the list.  Values added to the list are always stored in  order based on how they were added.  Cursors also traverse the values in the same order.  The current implementation uses a 32-way tree which provides O(log32(n)) performance for all operations. (see [Comparative Performance](https://github.com/brianburton/java-immutable-collections/wiki/Comparative-Performance))
 
 As with all of the immutable collection classes any method that modifies the list actually creates a new list instance and returns it as the method's result.  This result can be assigned to the original list variable or to a new variable as needed.  The original, unmodified, version of the list remains in memory until garbage collected.  The lists reuse as much structure as possible so adding and removing elements requires very little copying and only a small amount of additional memory.
 
@@ -91,9 +91,9 @@ The JImmutables.ralist() factory method can be used to create new JImmutableRand
 
 The JImmutable 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.  JImmutable Collections 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](https://github.com/brianburton/java-immutable-collections/wiki/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](https://github.com/brianburton/java-immutable-collections/wiki/Hash-Keys) for advice on selecting keys for maps)
+JImmutables.map() uses a hash mapped integer trie to store its values.  This provides O(log32(n)) performance for all operations.  (see [Comparative Performance](https://github.com/brianburton/java-immutable-collections/wiki/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 an Iterator, Stream, or Cursor will visit entries. (see [Hash Keys](https://github.com/brianburton/java-immutable-collections/wiki/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.
+JImmutables.sortedMap() uses a b-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 Comparator class.  Care must be taken to write robust and correct implementations of Comparable/Comparator to ensure the tree operates as expected.
 
 ````
     JImmutableMap<Integer, Integer> hmap = JImmutables.map();
@@ -141,7 +141,7 @@ JImmutable Collections provides a sparse array implementation.  A sparse array i
 
 - it implements JImmutableArray instead of JImmutableMap
 - its keys are ints (not Integers) so no boxing/unboxing is needed for them
-- its cursors iterate in sorted order by key using natural integer ordering (negative indexes then positive indexes)
+- its iterators, streams, and cursors iterate in sorted order by key using natural integer ordering (negative indexes then positive indexes)
 
 Any valid 32-bit integer can be used as an index to a sparse array.  Like a map the array efficiently manages memory so an array with widely dispersed keys will use approximately the same amount of memory as one with contiguous keys.
 
@@ -164,7 +164,7 @@ Since arrays are not contiguous there is no concept of "insertion", only assignm
 Factory Methods
 ---
 
-Internally JImmutable Collections uses integer tries, B-Trees, 32-way trees, and 2-3 trees for the collection implementations but it strives to hide that fact from its users. There is no reason to directly create objects of the implementation classes. Your code will be cleaner and more future proof if you always create new collections using the factory methods in the JImmutables class.
+Internally JImmutable Collections uses integer tries, B-Trees, and 32-way trees for the collection implementations but it strives to hide that fact from its users. There is no reason to directly create objects of the implementation classes. Your code will be cleaner and more future proof if you always create new collections using the factory methods in the JImmutables class.
 
 Static methods in JImmutables can be used to create new instances of each collection interface. For example:
 
@@ -251,7 +251,7 @@ If your program is CPU bound and works with enormous data structures it might re
 Collections
 ---
 
-JImmutable Collections contains a variety of fully immutable collections designed to suit different needs in an application. This page describes the various collections (as of version 1.5) and their general performance characteristics. For each collection the summary lists the JImmutables factory method used to create an instance, the general algorithmic complexity of the collection, and a description of the collection's uses and characteristics.
+JImmutable Collections contains a variety of fully immutable collections designed to suit different needs in an application. This page describes the various collections (as of version 2.2) and their general performance characteristics. For each collection the summary lists the JImmutables factory method used to create an instance, the general algorithmic complexity of the collection, and a description of the collection's uses and characteristics.
 
 The complexity is expressed in big-oh notation which means "on the order of" or "within some constant multiple of" the value in parentheses. logX(n) means log to the base X of the number of elements in the collection. To give an idea of scale log32(100000) is 3.3 while log2(100000) is 16.6. "Within some constant factor" means that there will be fixed costs associated with the implementation so one algorithm with a given big-oh complexity might be 2-3 times faster than another with the same complexity.
 
@@ -260,9 +260,9 @@ Generally speaking ArrayList will be much faster than JImmutableList since it si
 Factory|Complexity|Description
 ---|---|---
 JImmutables.array()|O(log32(n))|A sparse array allowing any integer (positive or negative) as index. Indexes do not need to be consecutive and the array allocates memory only for indexes actually inserted into the array. Implemented internally as an integer trie with 32-way branching. Cursors visit elements in order by index with negative indexes visited before positive indexes. No direct java.util analog but similar to a TreeMap but with better performance.
-JImmutables.map()|O(log32(n))|A hash map using hashCode() and equals() methods of keys. Keys and values are stored in hash mapped array tries using linked lists or 2-3 trees for collision handling (two keys having same hash code). Performance scales roughly linearly with size of the collection since depth of the trie never exceeds 7 levels. Intended as a replacement for java.util.HashMap. Cursors visit elements in an unspecified order.
-JImmutables.sortedMap()|O(log2(n))|A tree map using a Comparator object to sort and compare keys. Keys and values are stored in B-trees. Intended as a replacement for java.util.TreeMap. Cursors visit elements in sort order of keys as specified by the Comparator.
-JImmutables.insertOrderMap()|O(2 * log32(n))|A hash map using hashCode() and equals() methods of keys. Keys and values are stored in hash mapped array tries using linked lists or 2-3 trees for collision handling (two keys having same hash code). A second integer trie is also used to govern cursor order. Performance scales roughly linearly with size of the collection since depth of the trie never exceeds 7 levels. Perhaps as much as twice the overhead of a map() since it maintains two data structures internally. Intended as a replacement for java.util.LinkedHashMap. Cursors visit elements in the order they were originally inserted into the map.
+JImmutables.map()|O(log32(n))|A hash map using hashCode() and equals() methods of keys. Keys and values are stored in hash mapped array tries using linked lists or b-trees for collision handling (two keys having same hash code). Performance scales roughly linearly with size of the collection since depth of the trie never exceeds 7 levels. Intended as a replacement for java.util.HashMap. Cursors visit elements in an unspecified order.
+JImmutables.sortedMap()|O(log2(n))|A tree map using a Comparator object to sort and compare keys. Keys and values are stored in B-trees. Intended as a replacement for java.util.TreeMap. Iterators, Streams, and Cursors visit elements in sort order of keys as specified by the Comparator.
+JImmutables.insertOrderMap()|O(2 * log32(n))|A hash map using hashCode() and equals() methods of keys. Keys and values are stored in hash mapped array tries using linked lists or b-trees for collision handling (two keys having same hash code). A second integer trie is also used to govern cursor order. Performance scales roughly linearly with size of the collection since depth of the trie never exceeds 7 levels. Perhaps as much as twice the overhead of a map() since it maintains two data structures internally. Intended as a replacement for java.util.LinkedHashMap. Iterators, Streams, and Cursors visit elements in the order they were originally inserted into the map.
 JImmutables.stack()|O(1) inserts/deletes at head, O(n) searches|A singly linked linear list of elements maintained in reverse insertion order. Extremely fast inserts and deletes from the head but searches require looping through all elements to find a match. Does not support insertion or deletion inside the list. Useful as a stack or a fast temporary list of items where LIFO order is acceptable. Cursors visit elements in LIFO (last in first out) order.
 JImmutables.list()|O(log32(n))|A "list" implemented internally as a 32-way tree. Allows elements to be inserted or removed only at either end of the list. Allows elements to be replaced anywhere within the list. Intended as a replacement for java.util.List. Cursors visit elements in order by index.
 JImmutables.ralist()|O(log2(n))|A "list" implemented internally as a B-tree. Allows elements to be inserted, removed, and updated anywhere within the list. Intended as a replacement for java.util.List in algorithms that require insertion or removal from the middle of the list. Otherwise use list(). Cursors visit elements in order by index.
@@ -283,7 +283,7 @@ JImmutables.insertOrderMultiset()|O(2 * log32(n))|A multiset implemented interna
 Hash Keys
 ---
 
-JImmutable Collections includes two basic types of maps ([Map Tutorial](https://github.com/brianburton/java-immutable-collections/wiki/Map-Tutorial)): sorted and unsorted.  A third type, insert order maps, use an unsorted map for their implementation internally so they won't be addressed here.  Sorted maps are implemented using balanced 2-3 trees.  Unsorted maps are implemented using hash array mapped tries (HAMT).
+JImmutable Collections includes two basic types of maps ([Map Tutorial](https://github.com/brianburton/java-immutable-collections/wiki/Map-Tutorial)): sorted and unsorted.  A third type, insert order maps, use an unsorted map for their implementation internally so they won't be addressed here.  Sorted maps are implemented using balanced b-trees.  Unsorted maps are implemented using hash array mapped tries (HAMT).
 
 Most hash map implementations use an array sufficiently large to hold all of the elements in the map plus some extra capacity to allow for growth and minimize hash collisions.  These implementations compute an integer hash code for each key (in Java the hashCode() method is used for this purpose) and then take the modulus of this code and the size of the array to produce an index into the array.  Since hash codes are 32-bit integers the arrays themselves are tiny in comparison to the 4 billion potential hash codes.  When two different hash codes map to the same array index this is called a "hash collision".  Allowing extra space in the array and using a prime number for its size can help to reduce the number of collisions.