Struct Buffer 

pub struct Buffer { /* private fields */ }

Off-screen storage for a rectangular grid of terminal cells.

A Buffer owns width * height Cell values in row-major order. Row y lives at cells[y * width..(y + 1) * width], and column x within that row is addressed by Position::new through the Surface and SurfaceMut APIs.

Use a buffer when rendering into memory before presenting the result to another surface, when composing with Windows, or when tests need a deterministic cell grid. Writes outside the buffer bounds are ignored; reads outside the bounds return None.

Wide cells are stored as a primary Cell followed by one continuation cell. Prefer Buffer::set or SurfaceMut::set_cell for writes so that continuation slots are kept consistent.

Implementations

impl Buffer

pub fn insert_lines(&mut self, y: u16, n: u16, bounds_bottom: u16, fill: &Cell)

Insert rows within a bounded vertical region.

Existing rows in [y, bounds_bottom) are pushed downward by n. Rows pushed past bounds_bottom are discarded, and the newly opened rows starting at y are filled with fill.

Parameters

• y: zero-based row where insertion begins.
• n: number of rows to insert.
• bounds_bottom: exclusive lower row bound for the affected region; clamped to the buffer height.
• fill: cell used to fill inserted rows.

Returns

Nothing.

Panics

Never panics.

Usage notes

Calls with y >= bounds_bottom are no-ops. Whole rows are swapped in row-major storage, so wide-cell pairs inside moved rows remain structurally unchanged.

pub fn delete_lines(&mut self, y: u16, n: u16, bounds_bottom: u16, fill: &Cell)

Delete rows within a bounded vertical region.

Existing rows below the deleted range are pulled upward within [y, bounds_bottom). The freed rows at the bottom of the region are filled with fill.

Parameters

• y: zero-based first row to delete.
• n: number of rows to delete.
• bounds_bottom: exclusive lower row bound for the affected region; clamped to the buffer height.
• fill: cell used to fill freed bottom rows.

Returns

Nothing.

Panics

Never panics.

Usage notes

Calls with y >= bounds_bottom are no-ops. Deleting more rows than remain in the region is equivalent to deleting through bounds_bottom.

pub fn insert_cells( &mut self, pos: impl Into<Position>, n: u16, bounds_right: u16, fill: &Cell, )

Insert cells within one row.

Cells in [pos.x, bounds_right) on pos.y are pushed right by n. Cells pushed past bounds_right are discarded, and the newly opened slots starting at pos.x are filled with fill.

Parameters

• pos: row and starting column for insertion.
• n: number of cells to insert.
• bounds_right: exclusive right column bound for the affected row region; clamped to the buffer width.
• fill: cell used to fill newly opened slots.

Returns

Nothing.

Panics

Never panics.

Usage notes

Calls with n == 0, an out-of-bounds row, or pos.x >= bounds_right are no-ops. Width-1 fills are written directly into the freed span. Wide fills are routed through Buffer::set so primary and continuation columns are placed consistently.

pub fn delete_cells( &mut self, pos: impl Into<Position>, n: u16, bounds_right: u16, fill: &Cell, )

Delete cells within one row.

Cells in [pos.x + n, bounds_right) on pos.y are pulled left by n. The freed slots at the right edge of the affected region are filled with fill.

Parameters

• pos: row and starting column for deletion.
• n: number of cells to delete.
• bounds_right: exclusive right column bound for the affected row region; clamped to the buffer width.
• fill: cell used to fill freed right-edge slots.

Returns

Nothing.

Panics

Never panics.

Usage notes

Calls with n == 0, an out-of-bounds row, or pos.x >= bounds_right are no-ops. Width-1 fills are written directly into the freed span. Wide fills are routed through Buffer::set so primary and continuation columns are placed consistently.

impl Buffer

pub fn new(width: u16, height: u16) -> Self

Create a new blank buffer.

The returned buffer has width * height cells, all initialized to Cell::BLANK. width and height are measured in terminal cell columns and rows, not bytes or grapheme clusters.

Parameters

• width: number of columns in each row.
• height: number of rows.

Returns

A row-major Buffer with bounds Rect::new(0, 0, width, height).

Panics

Panics if width * height cannot be allocated.

Usage notes

Zero-sized dimensions are valid. Accessors will then return empty rows or None according to the resulting bounds.

pub fn width(&self) -> u16

Return the buffer width in terminal cell columns.

Returns

The number of columns in each row.

Panics

Never panics.

Usage notes

This is the inherent accessor for the stored width. The Bounded implementation reports the same value through Bounded::width.

pub fn height(&self) -> u16

Return the buffer height in terminal cell rows.

Returns

The number of rows in the buffer.

Panics

Never panics.

Usage notes

This is the inherent accessor for the stored height. The Bounded implementation reports the same value through Bounded::height.

pub fn line(&self, y: u16) -> Option<&[Cell]>

Borrow one row as a contiguous slice.

Parameters

• y: zero-based row index in buffer coordinates.

Returns

Some(&[Cell]) with length Buffer::width when y is inside the buffer, or None when y >= height.

Panics

Never panics.

Usage notes

The returned slice may contain continuation cells that belong to wide primaries earlier in the same row. Do not assume every slice element starts an independent grapheme.

pub fn line_mut(&mut self, y: u16) -> Option<&mut [Cell]>

Mutably borrow one row as a contiguous slice.

Parameters

• y: zero-based row index in buffer coordinates.

Returns

Some(&mut [Cell]) with length Buffer::width when y is inside the buffer, or None when y >= height.

Panics

Never panics.

Usage notes

Direct slice mutation bypasses the wide-cell accounting performed by Buffer::set. It is appropriate for whole-row helpers that manage continuations themselves; prefer Buffer::set for ordinary writes.

pub fn cell_mut(&mut self, pos: Position) -> Option<&mut Cell>

Borrow one cell mutably.

Parameters

• pos: zero-based cell coordinate in buffer coordinates.

Returns

Some(&mut Cell) for an in-bounds position, or None when pos lies outside the buffer.

Panics

Never panics.

Usage notes

Mutating a cell through this handle does not update neighboring continuation cells. Do not change a cell from narrow to wide, wide to narrow, or continuation to primary through this handle; use Buffer::set or SurfaceMut::set_cell when the cell width may change.

pub fn set(&mut self, pos: impl Into<Position>, cell: &Cell)

Set a cell at a position while preserving wide-cell invariants.

Parameters

• pos: zero-based destination coordinate. Any type convertible into Position is accepted.
• cell: cell to clone into the destination.

Behavior

In-bounds narrow writes replace exactly one column, blanking any stale wide-cell halves they overwrite. In-bounds wide writes place cell at pos and write continuation placeholders into the columns it covers. If a wide cell would extend past the right edge of the row, the destination column is set to Cell::BLANK instead.

Out-of-bounds writes are ignored.

Panics

Never panics.

Usage notes

This is the implementation behind SurfaceMut::set_cell for Buffer. Use it instead of Buffer::cell_mut whenever the write might affect the width or role of neighboring cells.

pub fn resize(&mut self, width: u16, height: u16)

Resize the buffer, preserving the top-left intersection.

Parameters

• width: new row width in terminal cell columns.
• height: new height in terminal cell rows.

Behavior

Cells inside the intersection of the old and new bounds keep their row and column. Newly exposed cells are filled with Cell::BLANK, and cells outside the new bounds are discarded.

Panics

Panics if the resized backing store cannot be allocated.

Usage notes

Resizing copies cells structurally and does not reflow wide cells. If the new right edge cuts through a wide grapheme, the copied continuation or primary remains as stored until later writes or draws normalize the affected edge.

Trait Implementations

impl Bounded for Buffer

fn bounds(&self) -> Rect

Return the valid region in this value’s own coordinate space.

fn width(&self) -> u16

Return the width of Self::bounds in terminal cell columns.

fn height(&self) -> u16

Return the height of Self::bounds in terminal cell rows.

fn contains(&self, pos: Position) -> bool

Test whether a position lies inside Self::bounds.

impl Clone for Buffer

fn clone(&self) -> Buffer

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Buffer

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

Formats the value using the given formatter.

impl Surface for Buffer

fn cell(&self, pos: Position) -> Option<&Cell>

Read the cell at a position.

fn draw<T: SurfaceMut + ?Sized>(&self, target: &mut T, at: Position)

Copy self’s cells into target, mapping the top-left of self.bounds() to at in target coordinates.

impl SurfaceMut for Buffer

fn fill_rect(&mut self, rect: Rect, cell: &Cell)

Fill the clipped intersection of rect with cell. For width-1 fills this collapses the trait default’s per-cell set_cell loop into one slice::fill per row, with explicit wide-cell edge-straddle cleanup at the left and right boundaries so any wide cell crossing the fill region leaves no orphan primary or continuation behind. Wide fills (cell.width() > 1) stay on the stepped set_cell path so primary/continuation pairing and the trailing-partial-slot blank are placed by the same wide-cell handling that set already implements.

fn set_cell(&mut self, pos: Position, cell: &Cell)

Place cell at pos. Implementations are responsible for wide-cell semantics (continuation markers, blanking covered cells) and any dirty tracking they care to do. Taking &Cell lets implementations skip the clone when the destination already matches.

fn cell_mut(&mut self, pos: Position) -> Option<&mut Cell>

Mutable handle to the cell at pos. Returns None for out-of-bounds positions.

fn insert_lines(&mut self, y: u16, n: u16, bounds_bottom: u16, fill: &Cell)

Insert n blank rows at y, pushing existing rows down within [y, bounds_bottom). Rows pushed past bounds_bottom are lost. Freed top rows are filled with fill.

fn delete_lines(&mut self, y: u16, n: u16, bounds_bottom: u16, fill: &Cell)

Delete n rows at y, pulling existing rows up within [y, bounds_bottom). The bottom n rows of the window are filled with fill.

fn insert_cells( &mut self, pos: Position, n: u16, bounds_right: u16, fill: &Cell, )

Insert n blank cells at pos, pushing cells in [pos.x, bounds_right) right within row pos.y. Cells pushed past bounds_right are lost. The freed slots [pos.x, pos.x + n) are filled with fill.

fn delete_cells( &mut self, pos: Position, n: u16, bounds_right: u16, fill: &Cell, )

Delete n cells at pos, pulling cells in [pos.x + n, bounds_right) left within row pos.y. The freed slots [bounds_right - n, bounds_right) are filled with fill.

fn fill(&mut self, cell: &Cell)

Fill the entire surface bounds with cell.

fn clear(&mut self)

Clear the entire surface bounds to Cell::BLANK.

fn clear_rect(&mut self, rect: Rect)

Clear a rectangle to Cell::BLANK.