Lookup preceding object (in tree order)

Author: Joris-van-der-Wel

lib/SymbolTree.js

@@ -110,6 +110,37 @@ module.exports = class SymbolTree {
                 return this._node(object).parent;
         }
 
+        /**
+         * Find the preceding object (A) of the given object (B).
+         * An object A is preceding an object B if A and B are in the same tree
+         * and A comes before B in tree order.
+         * @method preceding
+         * @param {Object} object
+         * @param {Object} [treeRoot] If set, `treeRoot` must be an inclusive ancestor
+         *        of the return value (or else null is returned). This check _assumes_
+         *        that `root` is also an inclusive ancestor of the given `node`
+         * @returns {?Object}
+         */
+        preceding(object, treeRoot) {
+                if (object === treeRoot) {
+                        return null;
+                }
+
+                // if we have a previous sibling, return the last child of the last child of the ...
+                if (this._node(object).prev) {
+                        object = this._node(object).prev;
+
+                        while (this._node(object).last) {
+                                object = this._node(object).last;
+                        }
+
+                        return object;
+                }
+
+                // if there is no previous sibling return the parent (might be null)
+                return this._node(object).parent;
+        }
+
         /**
          * Remove the object from this tree.
          * `O(1)`

test/SymbolTree.js

@@ -437,3 +437,69 @@ test('Multiple SymbolTree instances should not conflict', function(t) {
 
         t.end();
 });
+
+test('look up preceding with a previous sibling', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const b = {};
+
+        tree.insertAfter(b, a);
+
+        t.equal(null, tree.preceding(a));
+        t.equal(a, tree.preceding(b));
+
+        t.end();
+});
+
+test('look up preceding with a previous sibling with a child', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const aa = {};
+        const ab = {};
+        const b = {};
+
+        tree.insertLast(aa, a);
+        tree.insertLast(ab, a);
+        tree.insertAfter(b, a);
+
+        t.equal(null, tree.preceding(a));
+        t.equal(a   , tree.preceding(aa));
+        t.equal(aa  , tree.preceding(ab));
+        t.equal(ab  , tree.preceding(b));
+
+        t.end();
+});
+
+test('look up preceding with a previous sibling with a descendants', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const aa = {};
+        const ab = {};
+        const aba = {};
+        const abaa = {};
+        const b = {};
+
+        tree.insertLast(aa, a);
+        tree.insertLast(ab, a);
+        tree.insertLast(aba, ab);
+        tree.insertLast(abaa, aba);
+        tree.insertAfter(b, a);
+
+        t.equal(abaa, tree.preceding(b));
+
+        t.end();
+});
+
+test('look up preceding using a specified root', function(t) {
+        const tree = new SymbolTree();
+        const a = {};
+        const aa = {};
+
+        tree.insertLast(aa, a);
+
+        t.equal(null, tree.preceding(a, a));
+        t.equal(a   , tree.preceding(aa, a));
+        t.equal(null, tree.preceding(aa, aa));
+
+        t.end();
+});