Struct Grid 

pub struct Grid {
    width: u16,
    height: u16,
    layers: Vec<Option<LayerBuf>>,
}

The main grid container for the terminal.

Holds up to 256 layers (0–255). Layer 0 is always allocated; higher layers are allocated on first write. Single-layer games pay no overhead — layers 1+ remain None until used.

Note: This uses alloc::vec::Vec, requiring an allocator in no_std environments. For strictly static, no-alloc environments, a static-sized grid type may be added in the future.

Fields

width: u16

height: u16

layers: Vec<Option<LayerBuf>>

Indexed by layer ID (0–255). Index 0 is always Some. Unwritten layers are None — no allocation until first write.

Implementations

impl Grid

fn layer(&self, id: u8) -> Option<&LayerBuf>

Borrow a specific layer, or None if unallocated.

fn layer_or_alloc(&mut self, id: u8) -> &mut LayerBuf

Borrow a specific layer mutably, allocating it if necessary.

fn layer0(&self) -> &LayerBuf

Borrow layer 0 (always allocated).

fn layer0_mut(&mut self) -> &mut LayerBuf

Borrow layer 0 mutably (always allocated).

impl Grid

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

Creates a new grid of the given dimensions.

Layer 0 is allocated immediately. Layers 1–255 are None until first write via put_tile.

pub const fn width(&self) -> u16

Returns the width of the grid.

pub const fn height(&self) -> u16

Returns the height of the grid.

pub fn put(&mut self, x: u16, y: u16, tile: Tile)

Sets the tile at the given coordinates on layer 0.

Panics

Panics if the coordinates are out of bounds.

pub fn get(&self, x: u16, y: u16) -> &Tile

Gets the tile at the given coordinates on layer 0.

Panics

Panics if the coordinates are out of bounds.

pub fn checked_put(&mut self, x: u16, y: u16, tile: Tile) -> Option<()>

Tries to set the tile at the given coordinates on layer 0.

Returns None if the coordinates are out of bounds.

pub fn checked_get(&self, x: u16, y: u16) -> Option<&Tile>

Tries to get the tile at the given coordinates on layer 0.

Returns None if the coordinates are out of bounds.

pub fn checked_get_mut(&mut self, x: u16, y: u16) -> Option<&mut Tile>

Tries to get a mutable reference to the tile at the given coordinates on layer 0.

Returns None if the coordinates are out of bounds.

pub fn cells(&self, layer: u8) -> Option<Cells<'_>>

Iterates all tiles on layer with their (x, y) coordinates.

Returns None if the layer is unallocated.

pub fn cells_mut(&mut self, layer: u8) -> CellsMut<'_>

Iterates all tiles on layer mutably with their (x, y) coordinates.

If the layer has not been written to yet, it is allocated first.

pub fn clear(&mut self, layer: u8)

Clears a specific layer, resetting all tiles to the default.

Does nothing if the layer is unallocated.

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

Resize the grid to width × height tiles.

Content within the overlapping region is preserved on all allocated layers. New cells are initialised to the default tile. Shrinking discards tiles outside the new bounds.

pub fn write_grapheme(&mut self, x: u16, y: u16, grapheme: &str, style: Style)

Write a grapheme cluster at (x, y) on layer 0, enforcing wide- character invariants.

This is the canonical way to place content into the grid when the egc feature is enabled. It:

• Clears any wide character whose primary or spacer cell would be overwritten.
• Sets TileFlags::WIDE_CHAR on the primary cell and places a TileFlags::WIDE_CHAR_SPACER in the adjacent cell for 2-column characters.
• Stores multi-codepoint EGCs (combining marks, ZWJ sequences) in Tile::extra, capped at 8 codepoints total.

Does nothing if (x, y) is out of bounds, if the grapheme has zero display width, or if a 2-column wide character would overflow the grid (the last column needs both its own cell and a spacer).

Panics

Panics if the grapheme’s display width exceeds u16::MAX. In practice this cannot happen: the maximum Unicode grapheme width is 2.

Only present when the egc feature is enabled.

fn clear_overlap(&mut self, x: u16, y: u16, width: u16)

Clears wide-character cells that would be partially overwritten by a write starting at (x, y) spanning width columns.

Operates on layer 0.

impl Grid

pub fn put_tile(&mut self, layer: u8, x: u16, y: u16, tile: Tile) -> Option<()>

Write a tile to layer at (x, y).

Allocates the layer if it has not been written to yet. Returns None if (x, y) is out of bounds.

To read back, use get_tile.

pub fn get_tile(&self, layer: u8, x: u16, y: u16) -> Option<&Tile>

Read a tile on layer at (x, y), or None if the layer is unallocated or the coordinates are out of bounds.

pub fn layers(&self) -> impl Iterator<Item = (u8, Pos, &Tile)> + '_

Yield (layer_id, Pos, &Tile) for every allocated cell across all layers, in layer-major (0 → 255) then row-major order.

Unallocated layers are skipped. This is used by backends that need the full frame on every draw (see crate::Backend::needs_full_frame).

pub fn clear_all(&mut self)

Clear every allocated layer.

pub fn diff<'a>( &'a self, other: &'a Self, ) -> impl Iterator<Item = (u8, Pos, &'a Tile)> + 'a

Yield (layer_id, Pos, &Tile) for every changed position across all layers, in layer-major (0 → 255) then row-major order.

Three cases per layer:

• Layer absent in self: nothing yielded.
• Layer in self, absent in other (newly allocated): all width × height tiles yielded.
• Layer in both: only positions where the Tile differs are yielded.

Trait Implementations

impl Debug for Grid

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

Formats the value using the given formatter.

impl Display for Grid

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

Formats the value using the given formatter.

impl Index<Pos<u16>> for Grid

type Output = Tile

The returned type after indexing.

fn index(&self, pos: Pos) -> &Tile

Performs the indexing (container[index]) operation.

impl IndexMut<Pos<u16>> for Grid

fn index_mut(&mut self, pos: Pos) -> &mut Tile

Performs the mutable indexing (container[index]) operation.