denebola 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ddb3a396701e9479f38cc53d23f86e568e7d2e31b4a38576d6670dc8f5026c56
+  data.tar.gz: 718554282d9670f3c656e06b67f9219679be4ec626cad2c390f49d8ff720cd27
+SHA512:
+  metadata.gz: c4af8ed526cacc5ed81c91614349b79d985ee8851d7c5ee47e58cc7bea011aa6ce1f461c390a1ec5fdc5d731ae16a9ce5ad24e4291d8fe34c4e3926341e8f3a9
+  data.tar.gz: 4728022bcf1941df19c6cbb808ad8ece063582402d41d44f7a24be21924701e8b081edaef15999538c02c95de990327a297511b11a7aa184b81b0bfda3e3c609

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — 2026-09-10
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# Denebola
+
+Persistent summary B+ trees and Unicode text ropes, in pure Ruby. Ruby 3.1 or later; no runtime dependencies.
+
+Nodes, text chunks, and summaries are frozen. An edit shares untouched subtrees with the previous value. Keeping a snapshot is an ordinary assignment, so readers can keep analyzing old text while an editor creates a new version.
+
+This source is version 0.1.0, not yet published. Build it with `gem build denebola.gemspec`, or use `gem "denebola", path: "/path/to/denebola"` in a Gemfile.
+
+## Text editing
+
+```ruby
+require "denebola"
+
+rope = Denebola::Rope.new("hello\nworld")
+snapshot = rope
+rope = rope.insert(5, ", there")
+rope.line(0)                # => "hello, there"
+snapshot.to_s               # => "hello\nworld"
+rope.bytesize               # => 18
+rope.length                 # => 18 Unicode codepoints
+rope.line_count             # => 2
+rope.byteslice(0, 5).to_s    # => "hello"
+rope = rope.delete(0...5)
+rope = rope.replace(0...7, "goodbye")
+rope.each_chunk { |text| puts text }  # Frozen strings, without flattening
+```
+
+All `replace`, `apply_edits`, and `byteslice` ranges address **bytes in UTF-8**, and are checked for bounds and codepoint boundaries. Inclusive and exclusive Ruby ranges work; beginless/endless ranges are accepted. Invalid encodings, split codepoints, and overlapping batch edits raise exceptions. Input strings are copied or shared safely with Ruby's copy-on-write strings; later mutation of the source cannot alter a rope.
+
+`apply_edits([[range, text], ...])` applies nonoverlapping edits against one original snapshot, sorting them into source order. Adjacent ranges are allowed. Chunks preserve extended grapheme clusters when building or joining text; a single unusually long grapheme may exceed the configured chunk size. Explicit byte slices and edits may operate between codepoints inside a grapheme.
+
+```ruby
+rope = Denebola::Rope.new("hello\nworld")
+rope.apply_edits([[0...5, "Hi"], [6...11, "Ruby"]]).to_s # => "Hi\nRuby"
+```
+
+## Lines and positions
+
+LF, CRLF, CR, U+2028, and U+2029 are line breaks. `line(row)` omits its terminator. Rows are zero based; empty text and a final empty row after a terminator each count as a line.
+
+```ruby
+rope = Denebola::Rope.new("😀\n日本")
+rope.point_at(8)                              # => Point(row: 1, column: 1)
+rope.offset_at(Denebola::Point.new(1, 1))     # => 8
+rope.line_start(1)                            # => 5
+rope.utf16_offset_at(8)                       # => 4
+rope.offset_at_utf16(4)                       # => 8
+rope.utf16_point_at(4)                        # => Point(row: 0, column: 2)
+rope.offset_at_utf16_point(Denebola::Point.new(0, 2)) # => 4
+```
+
+`Point` accepts positional or keyword `row` and `column`. Unqualified offsets are UTF-8 byte offsets. Normal columns count Unicode codepoints, not screen cells or graphemes. The UTF-16 methods count code units and reject offsets inside a surrogate pair. `offset_at` and `offset_at_utf16_point` require a column within the line's content. A byte position between CR and LF normalizes to the following row, column zero; converting that point back returns the position after LF.
+
+`rope.summary` exposes `bytesize`, `length`, `utf16_length`, `break_count`, `longest_row` (earliest row with maximum width), `longest_row_length`, `first_line_length`, and `last_line_length`. `TextSummary.zero` is the identity and `summary + other_summary` combines concatenated text, including CRLF across a boundary.
+
+## Anchors
+
+Anchors transform explicitly using the same finite byte ranges as an edit, without retaining the entire edit history:
+
+```ruby
+rope = Denebola::Rope.new("hello")
+anchor = rope.anchor(2, bias: :right)
+edits = [[2...2, "XYZ"]]
+anchor = anchor.transform(edits)
+rope = rope.apply_edits(edits)
+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. Anchor transformation returns a new anchor; it does not mutate the original or automatically observe a rope.
+
+## Generic summary tree
+
+Items expose `summary`. The summary class supplies `.zero` and `#+`, with an associative addition and 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.
+
+```ruby
+Weight = Struct.new(:weight) do
+  def self.zero = new(0).freeze
+  def +(other) = self.class.new(weight + other.weight).freeze
+  def summary = self
+end
+
+tree = Denebola::Tree.new([Weight.new(2).freeze, Weight.new(3).freeze], summary: Weight)
+tree = tree.push(Weight.new(5).freeze)
+cursor = tree.cursor(:weight).seek(2)
+cursor.item.weight          # => 3
+cursor.summary.weight       # => 2: summary before the current item
+cursor.next.weight          # => 5
+cursor.prev.weight          # => 3
+cursor.seek(2, bias: :left).item.weight # => 2
+```
+
+`Tree.from(items, summary: ...)` and `Tree.new(items, summary: ...)` bulk-build an already ordered sequence. `append` joins another compatible tree or enumerable. `tree[index]`, `slice(index, count)`, and `split_at(index)` use item indexes; `replace_at(index, items)` replaces one item, or appends when `index == size`. Every update returns a new tree.
+
+`cursor.seek(value)` chooses the item whose ending dimension exceeds the target; `bias: :left` also includes equality. At the end, `item` is `nil`, `index == tree.size`, and `summary` is the whole summary. `cursor.read_until(value)` returns complete items up to the target boundary and advances the cursor; it does not split an item. `next` and `prev` return the newly selected item or `nil`.
+
+Text dimensions are also available as `Denebola::Dimensions::BYTES`, `CHARACTERS`, `UTF16`, and `LINE_BREAKS`. B+ nodes hold cumulative summaries and item counts; navigation uses binary search. Editing copies touched chunks and ancestor paths, and splitting/joining preserves occupancy and equal leaf depth. Returning a string or a long line necessarily costs at least its output size. `check_invariants!` checks occupancy, frozen nodes, depth, prefix counts, and summaries and is intended for tests.
+
+## Benchmarks and validation
+
+Run `bundle install`, then `bundle exec rake test`. The default suite includes 100,000 deterministic random Unicode edits compared with Ruby `String`, 5,000 summary monoid cases, immutable snapshots, split/join occupancy checks, all supported newline types, surrogate boundaries, and retained node counts after 10,000 edits. `bundle exec rake test:oracle` runs the property tests alone. `ruby tools/check_isolation.rb` checks runtime independence; `sig/denebola.rbs` describes the public API.
+
+`bundle exec rake bench` 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. Defaults are fanout **16**, chunk size **1024 bytes**: smaller chunks improve some edits but allocate more nodes; 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:
+
+| Operation | Measured | Design budget |
+|---|---:|---:|
+| Build 11 MB | 39.5 ms | 800 ms for 10 MB |
+| Insert one ASCII character | 12.3 µs | 50 µs |
+| Read a line | 1.38 µs | 5 µs |
+| Byte offset → Point | 1.92 µs | 10 µs |
+| Point → byte offset | 1.17 µs | 10 µs |
+| Slice 1 KB | 6.79 µs | 20 µs |
+| Retained Ruby object memory | 33.84 MiB | 40 MiB |
+
+Performance depends on document content, Ruby version, and hardware. Memory is measured with `ObjectSpace` after releasing the input and collecting garbage; it is not process RSS. `rake bench:assert` uses explicitly wider timing ceilings for shared CI hardware, while retaining the 40 MiB memory ceiling. CI tests Ruby 3.1, 3.2, 3.3, 3.4, and 4.0 on Linux, macOS, and Windows.
+
+## License
+
+[MIT](LICENSE.txt).

data/lib/denebola/anchor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Denebola
+  # A position transformed explicitly by edits against its current snapshot.
+  class Anchor
+    attr_reader :offset, :bias
+    def initialize(offset, bias: :right)
+      raise ArgumentError, "offset must be nonnegative" unless offset.is_a?(Integer) && offset >= 0
+      raise ArgumentError, "bias must be :left or :right" unless %i[left right].include?(bias)
+      @offset, @bias = offset, bias
+      freeze
+    end
+
+    def transform(edits)
+      delta = 0
+      previous = 0
+      transformed = nil
+      edits.sort_by { |range, _| range.begin }.each do |range, text|
+        start = range.begin
+        finish = range.end + (range.exclude_end? ? 0 : 1)
+        raise ArgumentError, "invalid or overlapping edits" unless start.is_a?(Integer) && start >= previous && finish >= start
+        previous = finish
+        if offset < start
+          transformed ||= offset + delta
+        elsif offset <= finish
+          transformed ||= start + delta + (bias == :right ? text.bytesize : 0)
+        end
+        delta += text.bytesize - (finish - start)
+      end
+      self.class.new(transformed || offset + delta, bias: bias)
+    end
+  end
+end

data/lib/denebola/cursor.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Denebola
+  class Cursor
+    attr_reader :tree, :dimension, :index, :item, :summary
+
+    def initialize(tree, dimension)
+      @tree, @dimension = tree, dimension
+      @index = 0
+      @item = tree[0]
+      @summary = tree.prefix_summary(0)
+    end
+
+    def seek(value, bias: :right)
+      @index, @item, @summary = tree.locate(value, dimension, bias: bias)
+      self
+    end
+
+    def next
+      return nil if index >= tree.size
+      @summary += @item.summary
+      @index += 1
+      @item = tree[index]
+    end
+
+    def prev
+      return nil if index.zero?
+      @index -= 1
+      @summary = tree.prefix_summary(index)
+      @item = tree[index]
+    end
+
+    # Returns complete items from the cursor up to the target dimension boundary.
+    def read_until(value, bias: :right)
+      finish, = tree.locate(value, dimension, bias: bias)
+      raise RangeError, "target is before cursor" if finish < index
+      result = tree.slice(index, finish - index)
+      seek(value, bias: bias)
+      result
+    end
+  end
+end

data/lib/denebola/dimensions.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Denebola
+  module Dimensions
+    BYTES = ->(summary) { summary.bytesize }
+    CHARACTERS = ->(summary) { summary.length }
+    UTF16 = ->(summary) { summary.utf16_length }
+    LINE_BREAKS = ->(summary) { summary.break_count }
+  end
+end

data/lib/denebola/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Denebola
+  class Error < StandardError; end
+end

data/lib/denebola/point.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Denebola
+  class Point
+    attr_reader :row, :column
+    def initialize(row = 0, column = 0, **keywords)
+      @row, @column = keywords.fetch(:row, row), keywords.fetch(:column, column)
+      unless @row.is_a?(Integer) && @column.is_a?(Integer) && @row >= 0 && @column >= 0
+        raise ArgumentError, "row and column must be nonnegative integers"
+      end
+      freeze
+    end
+    def ==(other) = other.is_a?(Point) && row == other.row && column == other.column
+    alias eql? ==
+    def hash = [row, column].hash
+    def to_a = [row, column]
+    def inspect = "#<Denebola::Point row=#{row} column=#{column}>"
+  end
+end

data/lib/denebola/rope.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module Denebola
+  class Rope
+    DEFAULT_CHUNK_SIZE = 1024
+    LINE_BREAK = /\r\n|[\r\n\u2028\u2029]/
+
+    class Chunk
+      attr_reader :text, :summary, :line_ends
+      def initialize(text)
+        @text = text.frozen? ? text : text.dup.freeze
+        @line_ends = []
+        @summary = TextSummary.from_text(text, line_ends: @line_ends)
+        @line_ends.freeze
+        freeze
+      end
+    end
+
+    attr_reader :tree, :chunk_size
+    protected :tree
+
+    def initialize(text = "", chunk_size: DEFAULT_CHUNK_SIZE, branching: Tree::DEFAULT_BRANCHING, tree: nil)
+      raise ArgumentError, "chunk_size must be an integer >= 4" unless chunk_size.is_a?(Integer) && chunk_size >= 4
+      @chunk_size = chunk_size
+      @tree = tree || Tree.new(chunks(normalize_text(text)), summary: TextSummary, branching: branching)
+      freeze
+    end
+
+    def summary = tree.summary
+    def bytesize = summary.bytesize
+    def length = summary.length
+    alias size length
+    def utf16_length = summary.utf16_length
+    def line_count = summary.break_count + 1
+    def empty? = bytesize.zero?
+
+    def each_chunk
+      return enum_for(__method__) unless block_given?
+      tree.each { |chunk| yield chunk.text }
+      self
+    end
+
+    def to_s
+      text = String.new(capacity: bytesize, encoding: Encoding::UTF_8)
+      each_chunk { |chunk| text << chunk }
+      text
+    end
+
+    def insert(offset, text) = replace(offset...offset, text)
+    def delete(range) = replace(range, "")
+
+    def replace(range, text)
+      start, finish = byte_bounds(range)
+      replacement = normalize_text(text)
+      first_index, first, prefix = locate_byte_offset(start)
+      last_index, last, suffix = locate_byte_offset(finish)
+      if first_index.positive? && start == prefix.bytesize
+        first_index -= 1
+        first = tree[first_index]
+        prefix = tree.prefix_summary(first_index)
+      end
+      local_start = start - prefix.bytesize
+      local_finish = finish - suffix.bytesize
+      first ||= Chunk.new("")
+      last ||= Chunk.new("")
+      combined = first.text.byteslice(0, local_start) + replacement + last.text.byteslice(local_finish, last.text.bytesize - local_finish)
+      values = chunks(combined)
+      if first_index == last_index
+        updated = tree.replace_at(first_index, values)
+      else
+        tail = last_index < tree.size ? last_index + 1 : tree.size
+        updated = tree.slice(0, first_index).append(values).append(tree.slice(tail, tree.size - tail))
+      end
+      with_tree(updated)
+    end
+
+    # Ranges refer to the original snapshot. Adjacent edits are allowed; overlaps are rejected.
+    def apply_edits(edits)
+      normalized = edits.map { |range, text| [*byte_bounds(range), normalize_text(text)] }.sort_by { |start, finish, _| [start, finish] }
+      previous = 0
+      normalized.each do |start, finish, _|
+        raise ArgumentError, "overlapping edits" if start < previous
+        previous = finish
+      end
+      return self if normalized.empty?
+      return replace(normalized[0][0]...normalized[0][1], normalized[0][2]) if normalized.length == 1
+      # Split the remaining tree in order, so already consumed subtrees are never revisited.
+      result = Tree.new(summary: TextSummary, branching: tree.branching)
+      remaining = self
+      consumed = 0
+      normalized.each do |start, finish, text|
+        left, rest = remaining.split_at(start - consumed)
+        _, remaining = rest.split_at(finish - start)
+        result = join_trees(result, left.tree)
+        result = join_trees(result, Tree.new(chunks(text), summary: TextSummary, branching: tree.branching))
+        consumed = finish
+      end
+      with_tree(join_trees(result, remaining.tree))
+    end
+
+    def byteslice(offset, length = nil)
+      start, finish = offset.is_a?(Range) ? byte_bounds(offset) : byte_bounds(offset...(offset + (length || bytesize - offset)))
+      return self if start.zero? && finish == bytesize
+      first_index, first, prefix = locate_byte_offset(start)
+      last_index, last, suffix = locate_byte_offset(finish)
+      return with_tree(Tree.new(summary: TextSummary, branching: tree.branching)) if finish == start
+      local_start = start - prefix.bytesize
+      if first_index == last_index
+        return with_tree(Tree.new([Chunk.new(first.text.byteslice(local_start, finish - start))], summary: TextSummary, branching: tree.branching))
+      end
+      middle_start = first_index + (local_start.positive? ? 1 : 0)
+      result = tree.slice(middle_start, last_index - middle_start)
+      if local_start.positive?
+        head = Chunk.new(first.text.byteslice(local_start, first.text.bytesize - local_start))
+        result = Tree.new([head], summary: TextSummary, branching: tree.branching).append(result)
+      end
+      local_finish = finish - suffix.bytesize
+      result = result.push(Chunk.new(last.text.byteslice(0, local_finish))) if local_finish.positive?
+      with_tree(result)
+    end
+
+    def split_at(offset)
+      index, chunk, prefix = locate_byte_offset(offset)
+      return [self, with_tree(Tree.new(summary: TextSummary, branching: tree.branching))] unless chunk
+      left, right = tree.split_at(index)
+      local = offset - prefix.bytesize
+      if local.positive?
+        left = left.push(Chunk.new(chunk.text.byteslice(0, local)))
+        right = right.replace_at(0, [Chunk.new(chunk.text.byteslice(local, chunk.text.bytesize - local))])
+      end
+      [with_tree(left), with_tree(right)]
+    end
+
+    def line(row)
+      _, chunk, prefix, local = line_location(row)
+      return "" unless chunk
+      next_end = chunk.line_ends.bsearch { |ending| ending > local }
+      if next_end && !(chunk.text.getbyte(next_end - 1) == 13 && next_end == chunk.text.bytesize)
+        return chunk.text.byteslice(local, next_end - local).sub(/(?:\r\n|[\r\n\u2028\u2029])\z/, "")
+      end
+      start = prefix.bytesize + local
+      finish = row + 1 < line_count ? line_start(row + 1) : bytesize
+      text = read_bytes(start, finish - start)
+      text.sub(/(?:\r\n|[\r\n\u2028\u2029])\z/, "")
+    end
+
+    def line_start(row)
+      _, _, prefix, local = line_location(row)
+      prefix.bytesize + local
+    end
+
+    private def line_location(row)
+      raise RangeError, "line out of bounds" unless row.is_a?(Integer) && row.between?(0, line_count - 1)
+      return [0, tree[0], TextSummary.zero, 0] if row.zero?
+      index, chunk, prefix = tree.locate(row, :break_count, bias: :left)
+      local_row = row - prefix.break_count - 1
+      local_row += 1 if prefix.ends_with_cr? && chunk.summary.starts_with_lf?
+      local = chunk.line_ends.fetch(local_row)
+      if local == chunk.text.bytesize
+        previous = chunk.text.getbyte(local - 1)
+        prefix += chunk.summary
+        index += 1
+        chunk = tree[index]
+        local = previous == 13 && chunk&.text&.start_with?("\n") ? 1 : 0
+      end
+      [index, chunk, prefix, local]
+    end
+
+    # Columns count Unicode codepoints, not bytes, graphemes, or UTF-16 code units.
+    def point_at(byte_offset)
+      total = summary_before(byte_offset)
+      Point.new(total.break_count, total.last_line_length)
+    end
+
+    def offset_at(point)
+      _, chunk, prefix, local = line_location(point.row)
+      start = prefix.bytesize + local
+      ending = chunk&.line_ends&.bsearch { |finish| finish > local }
+      text = ending ? chunk.text.byteslice(local, ending - local).sub(/(?:\r\n|[\r\n\u2028\u2029])\z/, "") : line(point.row)
+      raise RangeError, "column out of bounds" unless point.column.between?(0, text.length)
+      start + text[0, point.column].bytesize
+    end
+
+    def utf16_offset_at(byte_offset) = summary_before(byte_offset).utf16_length
+
+    def offset_at_utf16(utf16_offset)
+      raise RangeError, "UTF-16 offset out of bounds" unless utf16_offset.is_a?(Integer) && utf16_offset.between?(0, utf16_length)
+      _, chunk, prefix = tree.locate(utf16_offset, :utf16_length)
+      return bytesize unless chunk
+      units = prefix.utf16_length
+      bytes = prefix.bytesize
+      chunk.text.each_codepoint do |codepoint|
+        return bytes if units == utf16_offset
+        units += codepoint > 0xffff ? 2 : 1
+        bytes += codepoint.chr(Encoding::UTF_8).bytesize
+        raise RangeError, "UTF-16 offset splits a surrogate pair" if units > utf16_offset
+      end
+      bytes
+    end
+
+    def utf16_point_at(byte_offset)
+      point = point_at(byte_offset)
+      column = utf16_offset_at(byte_offset) - utf16_offset_at(line_start(point.row))
+      Point.new(point.row, [column, 0].max)
+    end
+
+    def offset_at_utf16_point(point)
+      start = line_start(point.row)
+      offset = offset_at_utf16(utf16_offset_at(start) + point.column)
+      raise RangeError, "column out of bounds" if offset > start + line(point.row).bytesize
+      offset
+    end
+
+    def anchor(byte_offset, bias: :right)
+      locate_byte_offset(byte_offset)
+      Anchor.new(byte_offset, bias: bias)
+    end
+
+    def check_invariants!
+      tree.check_invariants!
+      each_chunk { |text| raise "invalid UTF-8 chunk" unless text.valid_encoding? && text.frozen? }
+      raise "incorrect text summary" unless summary == TextSummary.from_text(to_s)
+      true
+    end
+
+    private
+
+    def with_tree(tree) = self.class.new(chunk_size: chunk_size, tree: tree)
+
+    def join_trees(left, right)
+      return right if left.empty?
+      return left if right.empty?
+      boundary = chunks(left[left.size - 1].text + right[0].text)
+      left.slice(0, left.size - 1).append(boundary).append(right.slice(1, right.size - 1))
+    end
+
+    def normalize_text(text)
+      raise TypeError, "text must be a String" unless text.is_a?(String)
+      string = text.encoding == Encoding::UTF_8 ? text : text.encode(Encoding::UTF_8)
+      raise ArgumentError, "text must be valid UTF-8" unless string.valid_encoding?
+      string
+    end
+
+    def chunks(text)
+      return [] if text.empty?
+      return [Chunk.new(text)] if text.bytesize <= chunk_size
+      result = []
+      if text.ascii_only?
+        offset = 0
+        while offset < text.bytesize
+          length = [chunk_size, text.bytesize - offset].min
+          length -= 1 if text.getbyte(offset + length - 1) == 13 && text.getbyte(offset + length) == 10
+          result << Chunk.new(text.byteslice(offset, length))
+          offset += length
+        end
+      else
+        buffer = +""
+        text.each_grapheme_cluster do |grapheme|
+          if !buffer.empty? && buffer.bytesize + grapheme.bytesize > chunk_size
+            result << Chunk.new(buffer)
+            buffer = +""
+          end
+          buffer << grapheme
+        end
+        result << Chunk.new(buffer) unless buffer.empty?
+      end
+      result
+    end
+
+    def byte_bounds(range)
+      raise TypeError, "expected a Range of byte offsets" unless range.is_a?(Range)
+      start = range.begin || 0
+      finish = range.end.nil? ? bytesize : range.end + (range.exclude_end? ? 0 : 1)
+      unless start.is_a?(Integer) && finish.is_a?(Integer) && start >= 0 && finish >= start && finish <= bytesize
+        raise RangeError, "byte range out of bounds"
+      end
+      [start, finish]
+    end
+
+    def locate_byte_offset(offset)
+      raise RangeError, "byte offset out of bounds" unless offset.is_a?(Integer) && offset.between?(0, bytesize)
+      result = tree.locate(offset, :bytesize)
+      chunk = result[1]
+      byte = chunk&.text&.getbyte(offset - result[2].bytesize)
+      raise RangeError, "byte offset splits a UTF-8 character" if byte && (byte & 0xc0) == 0x80
+      result
+    end
+
+    def summary_before(offset)
+      _, chunk, prefix = locate_byte_offset(offset)
+      chunk ? prefix + TextSummary.from_text(chunk.text.byteslice(0, offset - prefix.bytesize)) : prefix
+    end
+
+    def read_bytes(offset, length)
+      return "" if length.zero?
+      index, chunk, prefix = locate_byte_offset(offset)
+      local = offset - prefix.bytesize
+      return chunk.text.byteslice(local, length) if local + length <= chunk.text.bytesize
+      text = String.new(capacity: length, encoding: Encoding::UTF_8)
+      while chunk && text.bytesize < length
+        text << chunk.text.byteslice(local, [length - text.bytesize, chunk.text.bytesize - local].min)
+        local = 0
+        index += 1
+        chunk = tree[index]
+      end
+      text
+    end
+  end
+end

data/lib/denebola/text_summary.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Denebola
+  # The number of line breaks is additive, except CR + LF is one break.
+  class TextSummary
+    FIELDS = %i[bytesize length utf16_length break_count longest_row longest_row_length
+                first_line_length last_line_length starts_with_lf? ends_with_cr?].freeze
+    attr_reader :bytesize, :length, :utf16_length, :break_count, :longest_row,
+                :longest_row_length, :first_line_length, :last_line_length
+
+    def initialize(bytesize: 0, length: 0, utf16_length: 0, break_count: 0,
+                   longest_row: 0, longest_row_length: 0, first_line_length: 0,
+                   last_line_length: 0, starts_with_lf: false, ends_with_cr: false)
+      @bytesize, @length, @utf16_length, @break_count = bytesize, length, utf16_length, break_count
+      @longest_row, @longest_row_length = longest_row, longest_row_length
+      @first_line_length, @last_line_length = first_line_length, last_line_length
+      @starts_with_lf, @ends_with_cr = starts_with_lf, ends_with_cr
+      freeze
+    end
+
+    ZERO = new
+    def self.zero = ZERO
+
+    def self.from_text(text, line_ends: nil)
+      if text.ascii_only? && !text.include?("\r")
+        start = lines = first = longest = longest_row = 0
+        while (ending = text.index("\n", start))
+          width = ending - start
+          first = width if lines.zero?
+          longest, longest_row = width, lines if width > longest
+          lines += 1
+          start = ending + 1
+          line_ends << start if line_ends
+        end
+        last = text.bytesize - start
+        first = last if lines.zero?
+        longest, longest_row = last, lines if last > longest
+        return new(bytesize: text.bytesize, length: text.bytesize, utf16_length: text.bytesize,
+                   break_count: lines, longest_row: longest_row, longest_row_length: longest,
+                   first_line_length: first, last_line_length: last, starts_with_lf: text.start_with?("\n"))
+      end
+      rows = text.split(/\r\n|[\r\n\u2028\u2029]/, -1)
+      rows = [""] if rows.empty?
+      lengths = rows.map(&:length)
+      longest = lengths.max
+      chars = text.length
+      supplementary = text.ascii_only? ? 0 : text.scan(/[\u{10000}-\u{10ffff}]/).length
+      if line_ends
+        offset = 0
+        text.split(/(\r\n|[\r\n\u2028\u2029])/, -1).each_with_index do |part, index|
+          offset += part.bytesize
+          line_ends << offset if index.odd?
+        end
+      end
+      new(bytesize: text.bytesize, length: chars, utf16_length: chars + supplementary,
+          break_count: rows.length - 1, longest_row: lengths.index(longest), longest_row_length: longest,
+          first_line_length: lengths.first, last_line_length: lengths.last,
+          starts_with_lf: text.start_with?("\n"), ends_with_cr: text.end_with?("\r"))
+    end
+
+    def +(other)
+      return other if bytesize.zero?
+      return self if other.bytesize.zero?
+      overlap = ends_with_cr? && other.starts_with_lf? ? 1 : 0
+      bridge = last_line_length + other.first_line_length
+      row = longest_row
+      width = longest_row_length
+      if bridge > width
+        row, width = break_count, bridge
+      end
+      if other.longest_row_length > width
+        row, width = break_count - overlap + other.longest_row, other.longest_row_length
+      end
+      self.class.new(bytesize: bytesize + other.bytesize, length: length + other.length,
+                     utf16_length: utf16_length + other.utf16_length,
+                     break_count: break_count + other.break_count - overlap,
+                     longest_row: row, longest_row_length: width,
+                     first_line_length: break_count.zero? ? first_line_length + other.first_line_length : first_line_length,
+                     last_line_length: other.break_count.zero? ? last_line_length + other.last_line_length : other.last_line_length,
+                     starts_with_lf: starts_with_lf?, ends_with_cr: other.ends_with_cr?)
+    end
+
+    def ==(other) = other.is_a?(TextSummary) && FIELDS.all? { |field| public_send(field) == other.public_send(field) }
+    alias eql? ==
+    def hash = FIELDS.map { |field| public_send(field) }.hash
+
+    def starts_with_lf? = @starts_with_lf
+    def ends_with_cr? = @ends_with_cr
+
+    def project_combined(dimension, other)
+      case dimension
+      when :bytesize then bytesize + other.bytesize
+      when :length then length + other.length
+      when :utf16_length then utf16_length + other.utf16_length
+      when :break_count then break_count + other.break_count - (ends_with_cr? && other.starts_with_lf? ? 1 : 0)
+      else (self + other).public_send(dimension)
+      end
+    end
+  end
+end

data/lib/denebola/tree.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Denebola
+  # An immutable, ordered B+ tree. Items expose #summary; summaries expose .zero and #+.
+  class Tree
+    include Enumerable
+    DEFAULT_BRANCHING = 16
+
+    class Node
+      attr_reader :entries, :summary, :prefixes, :counts, :height, :count
+
+      def initialize(entries, height, zero)
+        @entries = entries.freeze
+        @height = height
+        total = zero
+        count = 0
+        @prefixes = entries.map { |entry| total += entry.summary }.freeze
+        @counts = entries.map { |entry| count += height.zero? ? 1 : entry.count }.freeze
+        @summary = total
+        @count = count
+        freeze
+      end
+
+      def each(&block)
+        if height.zero?
+          entries.each(&block)
+        else
+          entries.each { |child| child.each(&block) }
+        end
+      end
+    end
+
+    attr_reader :root, :summary_class, :branching
+    protected :root, :summary_class
+
+    def initialize(items = [], summary:, branching: DEFAULT_BRANCHING, root: nil)
+      raise ArgumentError, "branching must be an even integer >= 4" unless branching.is_a?(Integer) && branching >= 4 && branching.even?
+      @summary_class = summary
+      @branching = branching
+      @zero = summary.zero
+      @root = root || build(items.to_a)
+      freeze
+    end
+
+    def self.from(items, **options) = new(items, **options)
+    def summary = root ? root.summary : @zero
+    def size = root ? root.count : 0
+    alias length size
+    def empty? = root.nil?
+
+    def each(&block)
+      return enum_for(__method__) unless block
+      root&.each(&block)
+      self
+    end
+
+    def [](index)
+      return nil unless index.is_a?(Integer) && index >= 0 && index < size
+      node = root
+      until node.height.zero?
+        child = node.counts.bsearch_index { |count| count > index }
+        index -= child.zero? ? 0 : node.counts[child - 1]
+        node = node.entries[child]
+      end
+      node.entries[index]
+    end
+
+    def push(item) = replace_at(size, [item])
+
+    def append(other)
+      other = self.class.new(other, summary: summary_class, branching: branching) unless other.is_a?(Tree)
+      raise ArgumentError, "incompatible trees" unless summary_class == other.summary_class && branching == other.branching
+      with_root(join_roots(root, other.root))
+    end
+
+    # Replace a single item, or insert at the end, copying only its ancestor path.
+    def replace_at(index, items)
+      raise RangeError, "item index out of bounds" unless index.is_a?(Integer) && index.between?(0, size)
+      values = items.to_a
+      return slice(0, index).append(values).append(slice(index + 1, size - index - 1)) if values.empty? && index < size
+      return self if values.empty?
+      if values.length > branching
+        finish = [index + 1, size].min
+        return slice(0, index).append(values).append(slice(finish, size - finish))
+      end
+      nodes = replace_node(root, index, values)
+      with_root(nodes.length == 1 ? nodes.first : node(nodes, nodes.first.height + 1))
+    end
+
+    def split_at(index)
+      validate_range(index, 0)
+      left, right = split_node(root, index)
+      [with_root(left), with_root(right)]
+    end
+
+    def slice(index, length = size - index)
+      validate_range(index, length)
+      return self if index.zero? && length == size
+      with_root(slice_node(root, index, length))
+    end
+
+    def cursor(dimension) = Cursor.new(self, dimension)
+
+    # [item index, item, cumulative summary before the item].
+    def locate(value, dimension, bias: :right)
+      raise ArgumentError, "bias must be :left or :right" unless %i[left right].include?(bias)
+      prefix = @zero
+      index = 0
+      current = root
+      while current
+        slot = current.prefixes.bsearch_index do |entry_summary|
+          measure = if prefix.respond_to?(:project_combined) && dimension.is_a?(Symbol)
+            prefix.project_combined(dimension, entry_summary)
+          else
+            project(dimension, prefix + entry_summary)
+          end
+          bias == :left ? measure >= value : measure > value
+        end
+        return [size, nil, summary] unless slot
+        prefix += current.prefixes[slot - 1] if slot.positive?
+        index += current.counts[slot - 1] if slot.positive?
+        return [index, current.entries[slot], prefix] if current.height.zero?
+        current = current.entries[slot]
+      end
+      [0, nil, @zero]
+    end
+
+    def prefix_summary(index)
+      validate_range(index, 0)
+      return summary if index == size
+      prefix = @zero
+      current = root
+      while current
+        slot = current.counts.bsearch_index { |count| count > index }
+        if slot.positive?
+          prefix += current.prefixes[slot - 1]
+          index -= current.counts[slot - 1]
+        end
+        break if current.height.zero?
+        current = current.entries[slot]
+      end
+      prefix
+    end
+
+    # Raises on an invalid occupancy, depth, count, or cached summary.
+    def check_invariants!
+      check_node(root, true) if root
+      true
+    end
+
+    private
+
+    def project(dimension, summary)
+      return summary.public_send(dimension) if dimension.is_a?(Symbol) || dimension.is_a?(String)
+      return dimension.from_summary(summary) if dimension.respond_to?(:from_summary)
+      dimension.call(summary)
+    end
+
+    def validate_range(index, length)
+      raise RangeError, "item range out of bounds" unless index.is_a?(Integer) && length.is_a?(Integer) && index >= 0 && length >= 0 && index + length <= size
+    end
+
+    def with_root(root) = self.class.new(summary: summary_class, branching: branching, root: root)
+    def node(entries, height) = Node.new(entries, height, @zero)
+
+    def pack(entries, height)
+      return [] if entries.empty?
+      count = (entries.length + branching - 1) / branching
+      width, extra = entries.length.divmod(count)
+      offset = 0
+      Array.new(count) do |i|
+        length = width + (i < extra ? 1 : 0)
+        result = node(entries.slice(offset, length), height)
+        offset += length
+        result
+      end
+    end
+
+    def build(items)
+      level = pack(items, 0)
+      height = 1
+      while level.length > 1
+        level = pack(level, height)
+        height += 1
+      end
+      level.first
+    end
+
+    def replace_node(current, index, values)
+      return pack(values, 0) unless current
+      entries = current.entries.dup
+      if current.height.zero?
+        entries[index, index == current.count ? 0 : 1] = values
+      else
+        slot = current.counts.bsearch_index { |count| count > index } || entries.length - 1
+        offset = slot.zero? ? 0 : current.counts[slot - 1]
+        entries[slot, 1] = replace_node(entries[slot], index - offset, values)
+      end
+      pack(entries, current.height)
+    end
+
+    def join_roots(left, right)
+      return right unless left
+      return left unless right
+      nodes = join_nodes(left, right)
+      nodes.length == 1 ? nodes.first : node(nodes, nodes.first.height + 1)
+    end
+
+    def join_nodes(left, right)
+      if left.height == right.height
+        pack(left.entries + right.entries, left.height)
+      elsif left.height > right.height
+        pack(left.entries[0...-1] + join_nodes(left.entries.last, right), left.height)
+      else
+        pack(join_nodes(left, right.entries.first) + right.entries.drop(1), right.height)
+      end
+    end
+
+    def split_node(current, index)
+      return [nil, current] if index.zero?
+      return [current, nil] if !current || index == current.count
+      return [node(current.entries.take(index), 0), node(current.entries.drop(index), 0)] if current.height.zero?
+      slot = current.counts.bsearch_index { |count| count >= index }
+      offset = slot.zero? ? 0 : current.counts[slot - 1]
+      left, right = split_node(current.entries[slot], index - offset)
+      before = current.entries.take(slot)
+      after = current.entries.drop(slot + 1)
+      prefix = before.empty? ? nil : (before.length == 1 ? before.first : node(before, current.height))
+      suffix = after.empty? ? nil : (after.length == 1 ? after.first : node(after, current.height))
+      [join_roots(prefix, left), join_roots(right, suffix)]
+    end
+
+    def slice_node(current, index, length)
+      return nil if length.zero?
+      return current if index.zero? && length == current.count
+      return node(current.entries.slice(index, length), 0) if current.height.zero?
+      slot = current.counts.bsearch_index { |count| count > index }
+      offset = slot.zero? ? 0 : current.counts[slot - 1]
+      result = nil
+      while length.positive?
+        child = current.entries[slot]
+        local = index - offset
+        count = [length, child.count - local].min
+        result = join_roots(result, slice_node(child, local, count))
+        length -= count
+        index += count
+        offset += child.count
+        slot += 1
+      end
+      result
+    end
+
+    def check_node(current, root)
+      minimum = root ? (current.height.zero? ? 1 : 2) : branching / 2
+      raise "invalid node occupancy" unless current.entries.length.between?(minimum, branching)
+      raise "mutable node" unless current.frozen? && current.entries.frozen?
+      actual = @zero
+      count = 0
+      current.entries.each_with_index do |entry, index|
+        if current.height.positive?
+          raise "unequal leaf depth" unless entry.height == current.height - 1
+          check_node(entry, false)
+        end
+        actual += entry.summary
+        count += current.height.zero? ? 1 : entry.count
+        raise "invalid prefix" unless actual == current.prefixes[index] && count == current.counts[index]
+      end
+      raise "invalid summary" unless actual == current.summary && count == current.count
+    end
+  end
+end

data/lib/denebola/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Denebola
+  VERSION = "0.1.0"
+end

data/lib/denebola.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "denebola/version"
+require_relative "denebola/error"
+require_relative "denebola/tree"
+require_relative "denebola/cursor"
+require_relative "denebola/text_summary"
+require_relative "denebola/point"
+require_relative "denebola/dimensions"
+require_relative "denebola/rope"
+require_relative "denebola/anchor"

data/sig/denebola.rbs

@@ -0,0 +1,155 @@
+module Denebola
+  VERSION: String
+  class Error < StandardError
+  end
+
+  interface _Summary
+    def +: (_Summary) -> _Summary
+  end
+
+  interface _Item
+    def summary: () -> _Summary
+  end
+
+  interface _Dimension
+    def from_summary: (_Summary) -> Numeric
+  end
+
+  type dimension = Symbol | String | _Dimension | ^(_Summary) -> Numeric
+
+  class Tree
+    include Enumerable[_Item]
+    DEFAULT_BRANCHING: Integer
+    attr_reader branching: Integer
+    def initialize: (?Enumerable[_Item] items, summary: untyped, ?branching: Integer, ?root: Node?) -> void
+    def self.from: (Enumerable[_Item], **untyped) -> Tree
+    def summary: () -> _Summary
+    def size: () -> Integer
+    alias length size
+    def empty?: () -> bool
+    def each: () { (_Item) -> void } -> self
+            | () -> Enumerator[_Item, self]
+    def []: (Integer) -> _Item?
+    def push: (_Item) -> Tree
+    def append: (Tree | Enumerable[_Item]) -> Tree
+    def replace_at: (Integer, Enumerable[_Item]) -> Tree
+    def split_at: (Integer) -> [Tree, Tree]
+    def slice: (Integer, ?Integer) -> Tree
+    def cursor: (dimension) -> Cursor
+    def locate: (Numeric, dimension, ?bias: :left | :right) -> [Integer, _Item?, _Summary]
+    def prefix_summary: (Integer) -> _Summary
+    def check_invariants!: () -> true
+
+    class Node
+      attr_reader entries: Array[Node | _Item]
+      attr_reader summary: _Summary
+      attr_reader prefixes: Array[_Summary]
+      attr_reader counts: Array[Integer]
+      attr_reader height: Integer
+      attr_reader count: Integer
+      def initialize: (Array[Node | _Item], Integer, _Summary) -> void
+      def each: () { (_Item) -> void } -> void
+    end
+  end
+
+  class Cursor
+    attr_reader tree: Tree
+    attr_reader dimension: dimension
+    attr_reader index: Integer
+    attr_reader item: _Item?
+    attr_reader summary: _Summary
+    def initialize: (Tree, dimension) -> void
+    def seek: (Numeric, ?bias: :left | :right) -> self
+    def next: () -> _Item?
+    def prev: () -> _Item?
+    def read_until: (Numeric, ?bias: :left | :right) -> Tree
+  end
+
+  class TextSummary
+    FIELDS: Array[Symbol]
+    ZERO: TextSummary
+    attr_reader bytesize: Integer
+    attr_reader length: Integer
+    attr_reader utf16_length: Integer
+    attr_reader break_count: Integer
+    attr_reader longest_row: Integer
+    attr_reader longest_row_length: Integer
+    attr_reader first_line_length: Integer
+    attr_reader last_line_length: Integer
+    def initialize: (**untyped) -> void
+    def self.zero: () -> TextSummary
+    def self.from_text: (String, ?line_ends: Array[Integer]?) -> TextSummary
+    def +: (TextSummary) -> TextSummary
+    def ==: (untyped) -> bool
+    alias eql? ==
+    def hash: () -> Integer
+    def starts_with_lf?: () -> bool
+    def ends_with_cr?: () -> bool
+    def project_combined: (Symbol, TextSummary) -> untyped
+  end
+
+  class Point
+    attr_reader row: Integer
+    attr_reader column: Integer
+    def initialize: (?Integer, ?Integer, ?row: Integer, ?column: Integer) -> void
+    def ==: (untyped) -> bool
+    alias eql? ==
+    def hash: () -> Integer
+    def to_a: () -> [Integer, Integer]
+    def inspect: () -> String
+  end
+
+  module Dimensions
+    BYTES: ^(TextSummary) -> Integer
+    CHARACTERS: ^(TextSummary) -> Integer
+    UTF16: ^(TextSummary) -> Integer
+    LINE_BREAKS: ^(TextSummary) -> Integer
+  end
+
+  class Rope
+    DEFAULT_CHUNK_SIZE: Integer
+    LINE_BREAK: Regexp
+    attr_reader chunk_size: Integer
+    def initialize: (?String, ?chunk_size: Integer, ?branching: Integer, ?tree: Tree?) -> void
+    def summary: () -> TextSummary
+    def bytesize: () -> Integer
+    def length: () -> Integer
+    alias size length
+    def utf16_length: () -> Integer
+    def line_count: () -> Integer
+    def empty?: () -> bool
+    def each_chunk: () { (String) -> void } -> self
+                  | () -> Enumerator[String, self]
+    def to_s: () -> String
+    def insert: (Integer, String) -> Rope
+    def delete: (Range[Integer?]) -> Rope
+    def replace: (Range[Integer?], String) -> Rope
+    def apply_edits: (Array[[Range[Integer?], String]]) -> Rope
+    def byteslice: (Integer | Range[Integer?], ?Integer?) -> Rope
+    def split_at: (Integer) -> [Rope, Rope]
+    def line: (Integer) -> String
+    def line_start: (Integer) -> Integer
+    def point_at: (Integer) -> Point
+    def offset_at: (Point) -> Integer
+    def utf16_offset_at: (Integer) -> Integer
+    def offset_at_utf16: (Integer) -> Integer
+    def utf16_point_at: (Integer) -> Point
+    def offset_at_utf16_point: (Point) -> Integer
+    def anchor: (Integer, ?bias: :left | :right) -> Anchor
+    def check_invariants!: () -> true
+
+    class Chunk
+      attr_reader text: String
+      attr_reader summary: TextSummary
+      attr_reader line_ends: Array[Integer]
+      def initialize: (String) -> void
+    end
+  end
+
+  class Anchor
+    attr_reader offset: Integer
+    attr_reader bias: :left | :right
+    def initialize: (Integer, ?bias: :left | :right) -> void
+    def transform: (Array[[Range[Integer], String]]) -> Anchor
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: denebola
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Immutable, structurally shared trees with summary dimensions, UTF-8 text
+  editing, line and UTF-16 indexing, and anchors.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/denebola.rb
+- lib/denebola/anchor.rb
+- lib/denebola/cursor.rb
+- lib/denebola/dimensions.rb
+- lib/denebola/error.rb
+- lib/denebola/point.rb
+- lib/denebola/rope.rb
+- lib/denebola/text_summary.rb
+- lib/denebola/tree.rb
+- lib/denebola/version.rb
+- sig/denebola.rbs
+homepage: https://github.com/noxdea/denebola
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/noxdea/denebola
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Persistent summary B+ trees and Unicode text ropes in pure Ruby
+test_files: []