denebola 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28307dc01292f1215dcfb5466ba9fe182633346c622d69d336456983c00276e2
-  data.tar.gz: 24520e65a734fb920588210d4d9b829ef0ec0997178e0ab88b708d49af604ad1
+  metadata.gz: 84880d06ec622bb6081d11f260b1e64cbfba37a9480a717208356afbfcc28108
+  data.tar.gz: 5e7c2cba1e6fb6ecfd5f6cc49c517ff038ca09a85dc81da268e69fe74142172d
 SHA512:
-  metadata.gz: 8a29c867cdb4fa7f3e7d74c27f7556d8ecb50c08706f814d22c9ff43c90dfa776c4a4a502969a3708c67bdb9bccb8f6149c09d3656105ea97b3e925aaa378519
-  data.tar.gz: 36f141d074afb7bce936876e301df6d1884881c9806803619fea3d9f20f86aa0627c2ef5baaeb6c7bb5ea23041748d72c9d2891084bc9c92fce65f0ecd094edf
+  metadata.gz: 26cf63ddd365e57f19af10f195db576f21de2e7c1cf865025c6c868cfdc876f33fe8bc055366513106b68b666973eb9cd7a596bd2856273e2de23e358ff22627
+  data.tar.gz: b26f9e6372cd7dea2413c82e29996692bca7a810f473b24cdb1fbe13e31e1702746f541b4d0a73d432880733bad5a149d6f42ea31d56c7b3ef2a2d271c4cdec4

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.0 — 2026-09-23
+
+- Add persistent sparse two-dimensional sheets with range summaries.
+- Add efficient batch writes for importing sparse or dense cell ranges.
+
+## 0.2.2 — 2026-09-18
+
+- Add persistent batched edits and bounded line-window access to `LazyRope`; related snapshots share one backing-file close lifecycle.
+
 ## 0.2.1 — 2026-09-16
 
 - Keep same-offset batch edit ordering deterministic across ropes and anchors.

data/README.md

@@ -17,17 +17,19 @@
   <a href="#installation">Installation</a> ·
   <a href="#quick-start">Quick Start</a> ·
   <a href="#text-rope">Text Rope</a> ·
+  <a href="#sparse-sheet">Sparse Sheet</a> ·
   <a href="#generic-summary-tree">Summary Tree</a> ·
   <a href="#benchmarks">Benchmarks</a>
 </p>
 
 ---
 
-Denebola is a library for immutable, structurally shared sequences. It provides a generic summary B+ tree and a Unicode-aware text rope built on it. Every edit returns a new value while reusing untouched subtrees, so retaining a snapshot is an ordinary assignment.
+Denebola is a library for immutable, structurally shared data. It provides a generic summary B+ tree, a Unicode-aware text rope, bounded-memory file editing, and sparse two-dimensional sheets. Every edit returns a new value while reusing untouched subtrees, so retaining a snapshot is an ordinary assignment.
 
 ## Features
 
 - Persistent text editing with structural sharing
+- Persistent sparse 2D sheets with range summaries and batched cell updates
 - Bounded-memory, file-backed editing for multi-gigabyte text
 - UTF-8 byte, Unicode codepoint, UTF-16, and line-based indexing
 - Batched edits and explicit anchor transformation
@@ -86,7 +88,7 @@ text.materialize(0...1024)           # an ordinary editable Rope
 text.close
 ```
 
-`LazyRope` reads 1 MiB chunks by default and keeps eight chunks in an LRU cache. `byteslice`, line access, byte/codepoint positions, UTF-16 positions, and anchors follow `Rope` semantics. `edit`, `insert`, `delete`, and `replace` mutate the open view and store only replacement text in memory; call `materialize` when an immutable `Rope` snapshot is needed. A file changed, removed, or replaced after opening raises `Denebola::Error`. `to_s` and `materialize` without a range intentionally load the complete logical file.
+`LazyRope` reads 1 MiB chunks by default and keeps eight chunks in an LRU cache. `byteslice`, line access, byte/codepoint positions, UTF-16 positions, and anchors follow `Rope` semantics. `edit`, `insert`, `delete`, and `replace` mutate the open view; `apply_edits` returns a persistent view while storing only replacement text in memory. Views in that snapshot family share one backing-file lifetime, so closing any view closes the family. Call `materialize` for an independent `Rope` snapshot. A file changed, removed, or replaced after opening raises `Denebola::Error`. `to_s` and `materialize` without a range intentionally load the complete logical file.
 
 ## Text Rope
 
@@ -150,6 +152,33 @@ anchor.offset # => 5
 
 `:left` keeps an anchor before text inserted at its position; `:right` keeps it after. Anchors covered by a replacement collapse to the corresponding side of the replacement. Offsets after an edit move by its byte-length delta. Transformation returns a new anchor; it does not mutate the original or automatically observe a rope.
 
+## Sparse Sheet
+
+`Sheet` stores only populated cells in persistent B+ trees. Empty row and column runs are represented by gaps, so the primary storage can split and join axis ranges without shifting cell nodes. Structural edits currently rebuild the derived 2D summary index from populated cells. Every update returns a new snapshot; `snapshot` returns the same immutable value in O(1).
+
+```ruby
+sheet = Denebola::Sheet.new
+sheet = sheet.set(0, 0, 12).set(4, 2, 30)
+previous = sheet.snapshot
+
+sheet[4, 2]                                  # => 30
+sheet.summary(0, 0, 4, 2).sum               # => 42
+sheet.each_in(0, 0, 4, 2).to_a              # => [[Denebola::Point.new(0, 0), 12], [Denebola::Point.new(4, 2), 30]]
+sheet = sheet.insert_rows(2, 1).delete(0, 0)
+previous[0, 0]                               # => 12
+
+sheet = Denebola::Sheet.new.set_many([[0, 0, 12], [0, 1, 8], [1_000_000, 3, "far"]])
+sheet[1_000_000, 3]                          # => "far"
+```
+
+Coordinates are zero-based, and `each_in`/`summary` use inclusive bounds. `row_count` and `column_count` describe the current grid extent: setting a distant cell and inserting an axis extend it, clearing a cell preserves it, and deleting rows or columns shrinks it. `set(row, column, nil)` is equivalent to `delete`. Strings are copied and frozen; other values should be immutable to preserve snapshots. `summary` counts populated cells, sums Numeric values, reports comparable Numeric minimum/maximum, and counts values by Ruby class in `types`.
+
+`each_in` yields `(Denebola::Point, value)`, so it can directly back a cell-source callback that accepts `(reference, value)`.
+
+`set_many` accepts an enumerable of `[row, column, value]` edits, uses the last edit for duplicate coordinates, and returns one persistent snapshot. It bulk-builds the row tree after sorting the batch, avoiding a row-tree path rebuild for every cell; multi-column sheets also update the derived range index, while single-column sheets need no index. Untouched row objects and older snapshots remain reusable. Use `set` for isolated edits.
+
+Whole-row summaries use the outer row-tree summary without visiting rows or cells. Arbitrary rectangles use a persistent 2D range index: a partial-column query visits O(log rows × log columns) summary nodes and does not enumerate rows or cells. Single-column sheets need no 2D index because every valid column range is the full width. Wider sheets maintain the index, building it when first widened from one column; point edits copy affected paths, and maintaining exact numeric extrema after deletion adds a logarithmic value-index update. Structural row/column insertion and deletion still rebuild this auxiliary index from populated cells, even though the primary sheet trees retain sparse gaps.
+
 ## Generic Summary Tree
 
 Items expose `summary`. The summary class supplies `.zero` and `#+`, with associative addition and an identity. Items and their summaries must be immutable. A dimension is a summary attribute name, a callable, or an object with `from_summary(summary)`; its projection must be monotone along the sequence.
@@ -189,6 +218,14 @@ Text dimensions are available as `Denebola::Dimensions::BYTES`, `CHARACTERS`, `U
 bundle exec rake bench
 ```
 
+The sheet benchmark builds a sparse grid and reports build, snapshot, full-row summary, and partial-column summary times. `bench/sheet_range_index.rb` measures partial-column query scaling across sparse rows:
+
+```bash
+bundle exec ruby -Ilib bench/sheet_range_index.rb
+```
+
+Measured 2026-09-23 on arm64 macOS, Ruby 4.0.6 without YJIT: batches of 2,000 / 10,000 / 40,000 populated cells (1,000 / 5,000 / 20,000 occupied rows) built in 0.283 / 1.762 / 9.162 s. A one-column summary took 72.69 / 66.33 / 154.42 µs over 500 queries per size. Query time grows with tree depth rather than linearly with selected rows. This workload also shows the 2D index's material build/update cost; million-cell workloads have not yet been remeasured with the index enabled.
+
 The benchmark compares fanouts 8/16/32/64 and chunk sizes 256/512/1024/2048 before exercising a 1,000,000-line ASCII document (11,000,000 bytes). Timings are five-batch medians after warmup. The defaults are fanout **16** and chunk size **1024 bytes**: smaller chunks improve some edits but allocate more nodes, while these defaults meet the edit and retained-memory budgets together. Override them with `Rope.new(text, branching: 8, chunk_size: 512)`.
 
 Measured 2026-09-09 on arm64 macOS, Ruby 4.0.2 with YJIT:

data/lib/denebola/lazy_rope.rb

@@ -10,6 +10,20 @@ module Denebola
     TextPiece = Struct.new(:rope, keyword_init: true) do
       def bytesize = rope.bytesize
     end
+    class FileOwner
+      def initialize(file)
+        @file = file
+        @lock = Mutex.new
+      end
+
+      def closed? = @file.closed?
+
+      def close
+        @lock.synchronize { @file.close unless @file.closed? }
+        nil
+      end
+    end
+    private_constant :FileOwner
 
     attr_reader :chunk_size, :cached_bytes
 
@@ -25,6 +39,7 @@ module Denebola
       flags = File::RDONLY | File::BINARY
       flags |= File::SHARE_DELETE if defined?(File::SHARE_DELETE)
       @file = File.open(path, flags)
+      @file_owner = FileOwner.new(@file)
       @path = File.expand_path(path)
       @chunk_size = chunk_size
       @cache_chunks = cache_chunks
@@ -45,7 +60,7 @@ module Denebola
     end
 
     def lazy? = true
-    def closed? = @file.closed?
+    def closed? = @file_owner.closed?
 
     def bytesize
       ensure_unchanged!
@@ -94,6 +109,26 @@ module Denebola
       read_bytes(start, ending - start).force_encoding(Encoding::UTF_8).sub(/(?:\r\n|[\r\n\u2028\u2029])\z/, "")
     end
 
+    def line_end(row)
+      start = line_start(row)
+      index_until_line(row + 1)
+      ending = row + 1 < packed_line_count ? unpack_line_start(row + 1) : bytesize
+      tail = read_bytes([ending - 3, start].max, [ending - start, 3].min)
+      ending - (tail.end_with?("\r\n") ? 2 : tail.end_with?("\xE2\x80\xA8".b, "\xE2\x80\xA9".b) ? 3 : tail.end_with?("\r", "\n") ? 1 : 0)
+    end
+
+    def line_window(row, from: 0, max_bytes: 16_384)
+      raise TypeError, "from must be an Integer" unless from.is_a?(Integer)
+      raise ArgumentError, "max_bytes must be a nonnegative integer" unless max_bytes.is_a?(Integer) && max_bytes >= 0
+
+      start, ending = line_start(row), line_end(row)
+      offset = (start + from).clamp(start, ending)
+      offset -= 1 while offset > start && offset < ending && (read_bytes(offset, 1).getbyte(0) & 0xC0) == 0x80
+      value = read_bytes(offset, [max_bytes, ending - offset].min)
+      value = value.byteslice(0, complete_utf8_length(value)) unless value.empty?
+      [value.force_encoding(Encoding::UTF_8), offset - start]
+    end
+
     def byteslice(offset, length = nil)
       start, finish = slice_bounds(offset, length)
       Rope.new(read_bytes(start, finish - start).force_encoding(Encoding::UTF_8))
@@ -149,6 +184,34 @@ module Denebola
     def delete(range) = edit(range, "")
     def replace(range, text) = edit(range, text)
 
+    # Ranges address the original snapshot. The returned view has independent
+    # overlays, indexes, and cache. Snapshots share one backing-file lifetime:
+    # closing any snapshot closes the complete family.
+    def apply_edits(edits)
+      normalized = Edit.sort(edits.map do |range, text|
+        start, finish = byte_bounds(range)
+        validate_offset(start)
+        validate_offset(finish)
+        [start, finish, normalize_text(text)]
+      end)
+      previous = 0
+      normalized.each do |start, finish, _text|
+        raise ArgumentError, "overlapping edits" if start < previous
+        previous = finish
+      end
+      return self if normalized.empty?
+
+      updated = []
+      consumed = 0
+      normalized.each do |start, finish, text|
+        updated.concat(pieces_for(consumed, start))
+        updated << TextPiece.new(rope: Rope.new(text)).freeze unless text.empty?
+        consumed = finish
+      end
+      updated.concat(pieces_for(consumed, bytesize))
+      snapshot_with(coalesce(updated))
+    end
+
     def point_at(byte_offset)
       validate_offset(byte_offset)
       index_to([byte_offset + 1, bytesize].min)
@@ -236,8 +299,7 @@ module Denebola
     end
 
     def close
-      @file.close unless @file.closed?
-      nil
+      @file_owner.close
     end
 
     private
@@ -314,6 +376,17 @@ module Denebola
       @piece_ends = @pieces.map { |piece| total += piece.bytesize }
     end
 
+    def snapshot_with(pieces)
+      ensure_unchanged!
+      snapshot = dup
+      snapshot.instance_variable_set(:@cache, {})
+      snapshot.instance_variable_set(:@cached_bytes, 0)
+      snapshot.instance_variable_set(:@pieces, pieces.freeze)
+      snapshot.__send__(:rebuild_piece_ends)
+      snapshot.__send__(:reset_index)
+      snapshot
+    end
+
     def read_bytes(offset, count)
       ensure_unchanged!
       return "".b if count.zero?
@@ -562,7 +635,7 @@ module Denebola
     end
 
     def ensure_unchanged!
-      raise IOError, "closed file" if @file.closed?
+      raise IOError, "closed file" if closed?
       unchanged = file_stamp(@file.stat) == @stamp && file_stamp(File.stat(@path)) == @path_stamp
       raise Error, "file changed on disk; reopen it" unless unchanged
     rescue Errno::ENOENT