@procedures/collections 0.46.0 → 0.47.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @procedures/collections
 
+## 0.47.1
+
+### Patch Changes
+
+- Updated dependencies [f845c6d]
+  - @procedures/client@0.47.1
+
+## 0.47.0
+
+### Patch Changes
+
+- 397dd4b: Add `SummaryTree<Leaf, Summary>` and `summaryTree(spec, leaves)`: a persistent sequence of leaves with a monoid summary in each node. `concat`, `splitAt`, `split` (a monotone predicate over the prefix summary), `search`, `slice`, `splice`, `insert`, `remove`, `set` and `at` are O(log n). The tree is an AVL tree with the join algorithms.
+- e1ce6f4: `SummaryTree` gets `locate(key, target)`, which finds the leaf and the offset of a position of an additive key and calls no `combine`. The new optional `spec.merge(left, right)` joins two neighbor leaves at each seam of `concat`, `append`, `prepend`, `splice`, `insert` and `remove`. `set` and a `splice` of 8 leaves or fewer copy only the paths to their leaves. A rope edit of 100k characters in leaves of 256 calls `combine` and `measure` 21 times at most, and 135 times before. Each node keeps the summary of its left subtree and its leaf, so a copy that changes only the right subtree calls `combine` once. The new type `SummaryLocation` is the result of `locate`.
+- Updated dependencies [c9125a8]
+- Updated dependencies [335728b]
+- Updated dependencies [d987202]
+- Updated dependencies [45a737f]
+- Updated dependencies [d77e9e8]
+- Updated dependencies [e913014]
+- Updated dependencies [2f0c7b0]
+- Updated dependencies [ad70c38]
+- Updated dependencies [47819c6]
+  - @procedures/client@0.47.0
+
 ## 0.46.0
 
 ### Patch Changes

package/README.md

@@ -408,6 +408,34 @@ const pq = new PriorityQueue<Task>((a, b) => a.priority - b.priority);
 const deque = new ArrayDeque<Message>(); // Double-ended queue
 ```
 
+### Sequences with a summary: `SummaryTree`
+
+`SummaryTree<Leaf, Summary>` is a persistent sequence of leaves. Each node keeps the summary of its part of the sequence. A summary is a value of a monoid that you give as data: `empty` and an associative `combine`.
+
+- `concat`, `splitAt`, `split`, `slice`, `splice`, `insert`, `remove`, `set` and `at` are O(log n).
+- `split(predicate)` splits before the first leaf whose prefix summary satisfies a monotone predicate. `search(predicate)` finds that leaf and changes nothing.
+- `locate(key, target)` finds the leaf that holds a position of an additive key, and the offset in that leaf. It calls no `combine`, so it costs nothing when `combine` is slow.
+- `set` and a `splice` of 8 leaves or fewer copy only the paths to their leaves. Each level of each path calls `combine` 1 or 2 times. A leaf that becomes two leaves costs one descent.
+- The optional `spec.merge(left, right)` joins two neighbor leaves into one at each seam that an edit makes. A rope uses it to keep its chunks large.
+- Each edit returns a new tree. The old tree does not change, and the two trees share the nodes that did not change.
+- The tree is an AVL tree, so its height is at most 1.45 log2(n + 2).
+
+```typescript
+import { summaryTree } from "@procedures/collections";
+
+const spec = {
+  monoid: { empty: 0, combine: (a: number, b: number) => a + b },
+  measure: (line: string) => line.length,
+};
+const lines = summaryTree(spec, ["first line", "second", "third"]);
+lines.summary; // 21
+const hit = lines.search((length) => length > 12); // { index: 1, leaf: "second", before: 10, through: 16 }
+const edited = lines.splice(1, 1, ["2nd"]); // lines does not change
+const at = lines.locate((length) => length, 12); // { index: 1, leaf: "second", offset: 2 }
+```
+
+Use the same `spec` object for each tree that `concat` or `splice` joins. A tree of a different spec causes a `TypeError`.
+
 ## Behavior Decorators
 
 ### Bounded Collections