Struct Buffer 

pub struct Buffer {
    pub area: Rect,
    pub content: Vec<Cell>,
    /* private fields */
}

A 2D grid of Cells backing the terminal display.

Two buffers are kept (current + previous); only the diff is flushed to the terminal, giving immediate-mode ergonomics with retained-mode efficiency.

The buffer also maintains a clip stack. Push a Rect with Buffer::push_clip to restrict writes to that region, and pop it with Buffer::pop_clip when done.

Fields

area: Rect

The area this buffer covers, in terminal coordinates.

content: Vec<Cell>

Flat row-major storage of all cells. Length equals area.width * area.height.

Implementations

impl Buffer

pub fn empty(area: Rect) -> Self

Create a buffer filled with blank cells covering area.

pub fn raw_sequence(&mut self, x: u32, y: u32, seq: String)

Store a raw escape sequence to be written at position (x, y) during flush.

Used for Sixel images and other passthrough sequences. Respects the clip stack: sequences fully outside the current clip are skipped.

pub fn push_clip(&mut self, rect: Rect)

Push a clipping rectangle onto the clip stack.

Subsequent writes are restricted to the intersection of all active clip regions. Nested calls intersect with the current clip, so the effective clip can only shrink, never grow.

pub fn pop_clip(&mut self)

Pop the most recently pushed clipping rectangle.

After this call, writes are clipped to the previous region (or unclipped if the stack is now empty).

pub fn in_bounds(&self, x: u32, y: u32) -> bool

Returns true if (x, y) is within the buffer’s area.

pub fn get(&self, x: u32, y: u32) -> &Cell

Return a reference to the cell at (x, y).

Panics if (x, y) is out of bounds. Use Buffer::try_get when the coordinates may come from untrusted input.

pub fn get_mut(&mut self, x: u32, y: u32) -> &mut Cell

Return a mutable reference to the cell at (x, y).

Panics if (x, y) is out of bounds. Use Buffer::try_get_mut when the coordinates may come from untrusted input.

pub fn try_get(&self, x: u32, y: u32) -> Option<&Cell>

Return a reference to the cell at (x, y), or None if out of bounds.

Non-panicking counterpart to Buffer::get. Prefer this inside draw() closures when coordinates are computed from mouse input, scroll offsets, or other sources that could land outside the buffer.

pub fn try_get_mut(&mut self, x: u32, y: u32) -> Option<&mut Cell>

Return a mutable reference to the cell at (x, y), or None if out of bounds.

Non-panicking counterpart to Buffer::get_mut.

pub fn set_string(&mut self, x: u32, y: u32, s: &str, style: Style)

Write a string into the buffer starting at (x, y).

Respects cell boundaries and Unicode character widths. Wide characters (e.g., CJK) occupy two columns; the trailing cell is blanked. Writes that fall outside the current clip region are skipped but still advance the cursor position.

pub fn set_string_linked( &mut self, x: u32, y: u32, s: &str, style: Style, url: &str, )

Write a hyperlinked string into the buffer starting at (x, y).

Like Buffer::set_string but attaches an OSC 8 hyperlink URL to each cell. The terminal renders these cells as clickable links.

pub fn set_char(&mut self, x: u32, y: u32, ch: char, style: Style)

Write a single character at (x, y) with the given style.

No-ops if (x, y) is out of bounds or outside the current clip region.

pub fn diff<'a>(&'a self, other: &'a Buffer) -> Vec<(u32, u32, &'a Cell)>

Compute the diff between self (current) and other (previous).

Returns (x, y, cell) tuples for every cell that changed. Useful for custom backends or tests that need to inspect changed cells directly.

Allocation

Allocates a new Vec on every call. For high-frequency use (per-frame diffing in a render loop), prefer the internal flush_buffer_diff path used by crate::run, which streams updates directly to the backend without an intermediate Vec. Calling diff() on every frame in a 60 fps loop adds one heap allocation (sized to the changed-cell count) per frame.

Benchmarks

benches/benchmarks.rs exercises this path in bench_buffer_diff.

pub fn reset(&mut self)

Reset every cell to a blank space with default style, and clear the clip stack.

pub fn reset_with_bg(&mut self, bg: Color)

Reset every cell and apply a background color to all cells.

pub fn resize(&mut self, area: Rect)

Resize the buffer to fit a new area, resetting all cells.

If the new area is larger, new cells are initialized to blank. All existing content is discarded.