Struct CellMatrix 

pub struct CellMatrix {
    pub chunks: Arc<[Arc<CellChunk>]>,
    pub chunk_size: u32,
    pub source_line_count: u32,
    pub visible_line_count: u32,
    pub version: MatrixVersion,
    pub wrap_width: u32,
}

The published cell matrix for a single buffer.

Immutable once built; cell-builder replaces the published Arc when versions change. Cheap to clone (Arc bump).

Fields

chunks: Arc<[Arc<CellChunk>]>

Chunks ordered by start_source_line. Whole-doc mode has exactly one chunk.

chunk_size: u32

Logical lines per chunk, or CHUNK_SIZE_WHOLE_DOC for whole-doc mode.

source_line_count: u32

Total logical lines in the source buffer (pre-fold).

visible_line_count: u32

Total matrix rows across all chunks (post-fold).

version: MatrixVersion

Component-wise maximum of all chunks’ captured versions.

wrap_width: u32

Soft-wrap (W.2, A2): the column width each source line is wrapped at when :set wrap is on, or 0 when wrapping is off (the historical default — every source line is exactly one display row). The cells worker stamps this from the pane’s viewport_width; consumers derive display geometry via Self::segment_count without the matrix storing per-line segment data. One CellRow per source line is preserved either way — see docs/dev/architecture/soft-wrap.md (A2).

Implementations

impl CellMatrix

pub fn empty() -> Self

Empty matrix: no chunks, no rows. The initial published value before the cell-builder finishes its first build.

pub fn chunked( chunks: impl Into<Arc<[Arc<CellChunk>]>>, chunk_size: u32, source_line_count: u32, version: MatrixVersion, ) -> Self

Construct a matrix in chunked mode. S2 is the production caller; chunk_size must be > 0. Use Self::whole_doc for the single-chunk mode.

version is the aggregate stamp the renderer can inspect to detect “is this matrix newer than the one I painted last frame?” Comparison is != (see MatrixVersion::differs_from) because some axes are hash-style and don’t admit ordering. Production builds pass the publisher’s current MatrixVersion snapshot; defaults to all-zero for empty / test cases.

pub fn whole_doc(chunk: Arc<CellChunk>, source_line_count: u32) -> Self

Construct a matrix in whole-doc mode (one chunk).

pub fn is_whole_doc(&self) -> bool

true when running in whole-doc mode (one chunk covering the entire document).

pub fn is_empty(&self) -> bool

true when no chunks/rows are present.

pub fn segment_count(&self, target: u32) -> u32

Soft-wrap (W.2, A2): how many display rows the source line target occupies. 1 when wrapping is off (wrap_width == 0) or the line is missing/folded; otherwise ⌈col_count / wrap_width⌉, floored at 1 (an empty line still occupies one display row).

This is the published geometry the host scroll model (bottom_anchored_scroll) and both renderers read to expand a source line into wrap segments — no per-line segment data is stored on the matrix.

pub fn row_at_source_line(&self, target: u32) -> Option<&CellRow>

S3.c.0 (2026-05-26): look up the row whose logical source line equals target. Returns None when the target line is folded (no visible row) or past the matrix’s coverage.

Walks chunks linearly; chunks are sorted by start_source_line. Most callers ask for visible lines (≤ viewport_height per frame); a typical 100K-line buffer at chunk_size = 128 has ~780 chunks, so the walk is sub-µs even without an outer binary search.

pub fn covered_start_line(&self) -> u32

H.3 (2026-06-04): first source line this matrix’s chunks were built to cover. 0 for whole-doc mode and full-coverage chunked mode; the window’s lower bound for a windowed large-file matrix. Derived from the first chunk’s start_source_line (exact — chunks are ordered).

pub fn covered_end_line(&self) -> u32

H.3: exclusive upper bound of the source-line range this matrix’s chunks were built to cover. source_line_count in whole-doc mode; otherwise the last chunk’s start_source_line + chunk_size, clamped to source_line_count. Robust against fold elision (a fully folded tail chunk still reports the source span it was built over) and against a window that ends mid-chunk_size (build_matrix aligns the window up to chunk_size, so the last chunk’s nominal end equals the window’s upper bound).

pub fn covers(&self, lo: u32, hi: u32) -> bool

H.3: does this matrix cover the entire source-line range [lo, hi)? The cells worker’s cache-hit gate uses this to keep a windowed large-file matrix from serving a viewport that has scrolled past its covered range — when it returns false, the worker rebuilds the window around the new scroll. An empty matrix (no chunks) covers nothing.

pub fn slice(&self, scroll: u32, height: u32) -> CellSlice<'_>

Borrow the visible rows starting at matrix-row index scroll, up to height rows. Returns a CellSlice that iterates &CellRow references without allocating.

If scroll + height exceeds visible_line_count, the slice is naturally truncated (no panic, no padding). The renderer must paint blank rows below the slice’s end when the viewport extends past EOF.

pub fn display_slice<'a>( &'a self, scroll: u32, height: u32, virtual_rows: &'a VirtualRowMatrix, ) -> DisplaySlice<'a>

D.0a: borrow height display rows starting at display row scroll, interleaving virtual rows from virtual_rows with the document rows in this matrix.

scroll and height are in display-row space — they count both document rows and virtual rows. Returns a DisplaySlice that iterates DisplayRowEntry::Document for document rows and DisplayRowEntry::Virtual for virtual rows in natural top-to-bottom order.

When virtual_rows.is_empty() the iterator degenerates to the same yield order as Self::slice; renderers can call display_slice unconditionally without paying for the interleaver when no provider has registered virtual rows.

See docs/dev/architecture/virtual-rows.md for the full ordering contract (Above-before-Cell-before-Below at each anchor line, folded-line anchors emit at the next visible line, past-EOF anchors emit at the end).

Trait Implementations

impl Clone for CellMatrix

fn clone(&self) -> CellMatrix

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CellMatrix

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CellMatrix

fn default() -> Self

Equivalent to Self::empty. Provided so containers like Arc<ArcSwap<CellMatrix>> derive Default without explicit-init plumbing at every call site.