Add version history to readme; add comments; "dynamically persistent"

I described BTree as "semi-persistent", but this sounds like something
that is "incomplete" compared to an ordinary "persistent" data
structure, as a semicircle is merely half a circle, when in fact
"semi-persistent" is something fancier than "persistent". I don't want
to popularize confusing terminology, but I think that the category of
"semi-persistent" data structures is a valuable one. Therefore I chose
another name that doesn't have this drawback but isn't already in use.

Note: my Loyc.Collections C# library contains a several other
"dynamically persistent" types: ALists (including types similar to B+
trees), VLists/WLists, Set/MSet, Map/MMap. For more information,
see http://core.loyc.net/collections/

Author: qwertie

b+tree.ts

@@ -1,5 +1,6 @@
 // B+ tree by David Piepgrass. License: MIT
 import { ISortedMap, ISortedMapF } from './interfaces';
+
 export {
   ISetSource, ISetSink, ISet, ISetF, ISortedSetSource, ISortedSet, ISortedSetF,
   IMapSource, IMapSink, IMap, IMapF, ISortedMapSource, ISortedMap, ISortedMapF
@@ -207,7 +208,8 @@ export default class BTree<K=any, V=any> implements ISortedMapF<K,V>, ISortedMap
       this.setPairs(entries);
   }
 
-  // ES6 Map<K,V> methods ///////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////////
+  // ES6 Map<K,V> methods /////////////////////////////////////////////////////
 
   /** Gets the number of key-value pairs in the tree. */
   get size() { return this._size; }
@@ -313,7 +315,8 @@ export default class BTree<K=any, V=any> implements ISortedMapF<K,V>, ISortedMap
     return this.editRange(key, key, true, DeleteRange) !== 0;
   }
 
-  // Clone-mutators /////////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////////
+  // Clone-mutators ///////////////////////////////////////////////////////////
 
   /** Returns a copy of the tree with the specified key set (the value is undefined). */
   with(key: K): BTree<K,V|undefined>;
@@ -419,7 +422,8 @@ export default class BTree<K=any, V=any> implements ISortedMapF<K,V>, ISortedMap
     return p;
   }
 
-  // Iterator methods ///////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////////
+  // Iterator methods /////////////////////////////////////////////////////////
 
   /** Returns an iterator that provides items in order (ascending order if
    *  the collection's comparator uses ascending order, as is the default.)
@@ -686,6 +690,9 @@ export default class BTree<K=any, V=any> implements ISortedMapF<K,V>, ISortedMap
       return BTree.finishCursorWalk(otherCursor, thisCursor, _compare, onlyOther);
   }
 
+  ///////////////////////////////////////////////////////////////////////////
+  // Helper methods for diffAgainst /////////////////////////////////////////
+
   private static finishCursorWalk<K, V, R>(
     cursor: DiffCursor<K, V>,
     cursorFinished: DiffCursor<K, V>,
@@ -817,6 +824,9 @@ export default class BTree<K=any, V=any> implements ISortedMapF<K,V>, ISortedMap
     return depthANormalized - depthBNormalized;
   }
 
+  // End of helper methods for diffAgainst //////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////
+
   /** Returns a new iterator for iterating the keys of each pair in ascending order. 
    *  @param firstKey: Minimum key to include in the output. */
   keys(firstKey?: K): IterableIterator<K> {
@@ -839,7 +849,8 @@ export default class BTree<K=any, V=any> implements ISortedMapF<K,V>, ISortedMap
     });
   }
 
-  // Additional methods /////////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////////
+  // Additional methods ///////////////////////////////////////////////////////
 
   /** Returns the maximum number of children/values before nodes will split. */
   get maxNodeSize() {
@@ -1164,6 +1175,7 @@ class BNode<K,V> {
     this.isShared = undefined;
   }
 
+  ///////////////////////////////////////////////////////////////////////////
   // Shared methods /////////////////////////////////////////////////////////
 
   maxKey() {
@@ -1240,6 +1252,7 @@ class BNode<K,V> {
     return c === 0 ? i : i ^ failXor;*/
   }
 
+  /////////////////////////////////////////////////////////////////////////////
   // Leaf Node: misc //////////////////////////////////////////////////////////
 
   minKey() {
@@ -1273,6 +1286,7 @@ class BNode<K,V> {
     return kL;
   }
 
+  /////////////////////////////////////////////////////////////////////////////
   // Leaf Node: set & node splitting //////////////////////////////////////////
 
   set(key: K, value: V, overwrite: boolean|undefined, tree: BTree<K,V>): boolean|BNode<K,V> { 
@@ -1365,6 +1379,7 @@ class BNode<K,V> {
     return new BNode<K,V>(keys, values);
   }
 
+  /////////////////////////////////////////////////////////////////////////////
   // Leaf Node: scanning & deletions //////////////////////////////////////////
 
   forRange<R>(low: K, high: K, includeHigh: boolean|undefined, editMode: boolean, tree: BTree<K,V>, count: number,
@@ -1491,6 +1506,7 @@ class BNodeInternal<K,V> extends BNode<K,V> {
     return size;
   }
 
+  /////////////////////////////////////////////////////////////////////////////
   // Internal Node: set & node splitting //////////////////////////////////////
 
   set(key: K, value: V, overwrite: boolean|undefined, tree: BTree<K,V>): boolean|BNodeInternal<K,V> {
@@ -1566,6 +1582,7 @@ class BNodeInternal<K,V> extends BNode<K,V> {
     this.children.unshift((lhs as BNodeInternal<K,V>).children.pop()!);
   }
 
+  /////////////////////////////////////////////////////////////////////////////
   // Internal Node: scanning & deletions //////////////////////////////////////
 
   // Note: `count` is the next value of the third argument to `onFound`. 

readme.md

@@ -24,9 +24,9 @@ Features
 - Supports O(1) fast cloning with subtree sharing. This works by marking the
   root node as "shared between instances". This makes the tree read-only 
   with copy-on-edit behavior; both copies of the tree remain mutable.
-  I call this category of data structure "semi-persistent" because AFAIK no
-  one else has given it a name; it walks the line between mutating and 
-  [persistent](https://en.wikipedia.org/wiki/Persistent_data_structure).
+  I call this category of data structure "dynamically persistent" because 
+  AFAIK no one else has given it a name; it walks the line between mutating 
+  and [persistent](https://en.wikipedia.org/wiki/Persistent_data_structure).
 - Includes persistent methods such as `with` and `without`, which return a
   modified tree without changing the original (in O(log(size)) time).
 - When a node fills up, items are shifted to siblings when possible to 
@@ -36,7 +36,7 @@ Features
   with all keys in a given node.
 - Includes neat stuff such as `Range` methods for batch operations
 - Throws an exception if you try to use `NaN` as a key, but infinity is allowed.
-- No dependencies. 16K minified.
+- No dependencies. 18K minified.
 - Includes a lattice of interfaces for TypeScript users (see below)
 - Supports diffing computation between two trees that is highly optimized for the case
   in which a majority of nodes are shared (such as when persistent methods are used).
@@ -58,7 +58,7 @@ Features
 - Get largest key/pair that is lower than `k`: `t.nextLowerKey(k)`, `t.nextLowerPair(k)`
 - Freeze to prevent modifications: `t.freeze()` (you can also `t.unfreeze()`)
 - Fast clone: `t.clone()`
-- Compute a diff between two trees: `t.diffAgainst(otherTree, ...)`
+- Compute a diff between two trees (quickly skipping shared subtrees): `t.diffAgainst(otherTree, ...)`
 - For more information, **see [full documentation](https://github.com/qwertie/btree-typescript/blob/master/b%2Btree.ts) in the source code.**
 
 **Note:** Confusingly, the ES6 `Map.forEach(c)` method calls `c(value,key)` instead of `c(key,value)`, in contrast to other methods such as `set()` and `entries()` which put the key first. I can only assume that they reversed the order on the hypothesis that users would usually want to examine values and ignore keys. BTree's `forEach()` therefore works the same way, but there is a second method `.forEachPair((key,value)=>{...})` which sends you the key first and the value second; this method is slightly faster because it is the "native" for-each method for this class.
@@ -375,6 +375,12 @@ Benchmarks (in milliseconds for integer keys/values)
 Version history
 ---------------
 
+### v1.5.0 ###
+
+- Added `BTree.diffAgainst` method (PR #16)
+- Added `simpleComparator` function (PR #15)
+- Improved `defaultComparator` (PR #15) to support edge cases better. Most notably, heterogenous key types will no longer cause trouble such as failure to find keys that are, in fact, present in the tree. `BTree` is slightly slower using the new default comparator, but the benchmarks above have not been refreshed. For maximum performance, use `simpleComparator` or a custom comparator as the second constructor parameter. The simplest possible comparator is `(a, b) => a - b`, which works for finite numbers only.
+
 ### v1.4.0 ###
 
 - Now built as CommonJS module instead of UMD module, for better compatibility with webpack. No semantic change.
@@ -419,7 +425,6 @@ Version history
 
 ♥ This package was made to help people [learn TypeScript & React](http://typescript-react-primer.loyc.net/).
 
-Are you a C# developer? You might like the similar data structures I made for C#: 
-BDictionary, BList, etc. See http://core.loyc.net/collections/
+Are you a C# developer? You might like the similar data structures I made for C# ([BDictionary, BList, etc.](core.loyc.net/collections/alists-part2)), and other [dynamically persistent collection types](http://core.loyc.net/collections/).
 
 You might think that the package name "sorted btree" is overly redundant, but I _did_ make a data structure similar to B+ Tree that is _not_ sorted. I called it the [A-List](http://core.loyc.net/collections/alists-part1) (C#). But yeah, the names `btree` and `bplustree` were already taken, so what was I supposed to do, right?