Trait Query 

pub trait Query: Send {
    // Required methods
    fn line_count(&self) -> u32;
    fn line(&self, idx: u32) -> String;
    fn len_bytes(&self) -> usize;
    fn slice(&self, range: Range<Pos>) -> Cow<'_, str>;

    // Provided methods
    fn dirty_gen(&self) -> u64 { ... }
    fn byte_of_row(&self, row: usize) -> usize { ... }
    fn content_joined(&self) -> Arc<String> { ... }
    fn line_bytes(&self, row: usize) -> usize { ... }
    fn rope(&self) -> Rope { ... }
}

Read-only query sub-trait of Buffer.

Required Methods

fn line_count(&self) -> u32

Number of logical lines (excluding the implicit trailing line).

fn line(&self, idx: u32) -> String

Return an owned copy of line idx (0-based). Implementations should panic on out-of-bounds rather than silently return empty.

fn len_bytes(&self) -> usize

Total buffer length in bytes.

fn slice(&self, range: Range<Pos>) -> Cow<'_, str>

Slice for the half-open range. May allocate (rope joins) or borrow (contiguous storage). Returns std::borrow::Cow<'_, str> so contiguous backends can avoid the allocation.

Provided Methods

fn dirty_gen(&self) -> u64

Monotonic mutation generation counter. Increments on every content-changing call (insert / delete / replace / fold-touch edit / set_content). Read-only ops (cursor moves, queries, view changes) leave it untouched.

Engine consumers cache per-row data (search-match positions, syntax spans, wrap layout) keyed off this counter — when it advances, the cache is invalidated.

Implementations may return any monotonically non-decreasing value (zero is fine for non-canonical impls that don’t have a caching story); the contract is “if dirty_gen changed, the content may have changed.”

fn byte_of_row(&self, row: usize) -> usize

Byte offset of the first byte of row within the buffer’s canonical lines().join("\n") rendering. Out-of-range rows clamp to len_bytes().

Default implementation walks every prior row’s byte length and adds a separator byte per row gap. Backends with a faster path (rope position-of-line) should override.

Pre-0.1.0 default-impl addition — does not extend the sealed surface for downstream impls.

fn content_joined(&self) -> Arc<String>

Return the canonical lines().join("\n") rendering of the document as an Arc<String>. Multiple per-tick consumers (syntax pipeline, LSP notify, git signature, dirty hash) need this; the Buffer impl caches against dirty_gen so they share one allocation per generation.

Default impl walks line(r) for every row — slow but correct. Backends with cheaper paths (rope contiguous view) should override.

fn line_bytes(&self, row: usize) -> usize

Byte length of row. Out-of-range rows return 0.

Default impl pays a full line(row) clone just to read its length. Backends with row-indexed storage (canonical hjkl_buffer::Buffer) should override to read the byte length under one lock with no allocation — Editor::restore_text calls this on every undo/redo to recompute the inverse ContentEdit.

fn rope(&self) -> Rope

Return a cheaply-cloned rope snapshot of the buffer. O(1) for the canonical hjkl_buffer::Buffer (Arc-backed B-tree clone). Used by the syntax pipeline’s parse_initial_rope / parse_incremental_rope to stream bytes into tree-sitter without materializing a contiguous String.

Default impl builds a rope from content_joined() — correct but O(N). Backends that own a rope internally should override.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl Query for Buffer

fn line_count(&self) -> u32

fn line(&self, idx: u32) -> String

fn len_bytes(&self) -> usize

fn dirty_gen(&self) -> u64

fn content_joined(&self) -> Arc<String>

fn line_bytes(&self, row: usize) -> usize

fn rope(&self) -> Rope

fn slice(&self, range: Range<Pos>) -> Cow<'_, str>

Implementors