pub trait Surface: Bounded {
// Required method
fn cell(&self, pos: Position) -> Option<&Cell>;
// Provided method
fn draw<T: SurfaceMut + ?Sized>(&self, target: &mut T, at: Position) { ... }
}Expand description
A rectangular cell grid that can be read.
Surface adds immutable cell access to Bounded. It is the trait to
use for render sources, snapshots, and helpers that only need to inspect
cells or copy them into another surface.
The provided Surface::draw method is intentionally conservative
about wide cells: it avoids producing orphan continuation columns and
blanks wide primaries that would be split by source or destination
bounds.
Required Methods§
Sourcefn cell(&self, pos: Position) -> Option<&Cell>
fn cell(&self, pos: Position) -> Option<&Cell>
Read the cell at a position.
§Parameters
pos: coordinate in this surface’s coordinate space.
§Returns
Some(&Cell) when pos is readable, or None when it is outside
Bounded::bounds or otherwise unavailable.
§Panics
Implementations should not panic for out-of-bounds positions.
§Usage notes
A returned cell may be a wide primary or a continuation placeholder.
Callers that walk rows should advance by cell.width().max(1) for
primary cells and handle continuations explicitly.
Provided Methods§
Sourcefn draw<T: SurfaceMut + ?Sized>(&self, target: &mut T, at: 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.
§Parameters
target: writable destination surface.at: destination coordinate for the source bounds’ top-left corner.
§Behavior
The default walks the source row by row and emits one
SurfaceMut::set_cell call per source cell. Wide-cell
semantics are preserved:
- Wide-primary cells advance the column cursor by their full
widthso the source’s continuation cells are not written over independently. - If the source has been sliced through the middle of a wide
grapheme (a leading continuation with no primary in view, or
a trailing primary with no room for its continuation), the
default substitutes a blank rather than emitting an orphan
half. The same blank substitution applies when a wide primary
would land at the right edge of
targetwith no room for its continuation.
Implementations may override for a faster path (e.g. bulk line copies), but must preserve the wide-cell invariants above.
§Panics
The default implementation does not panic unless the destination’s
SurfaceMut::set_cell implementation panics.
§Usage notes
Destination clipping is delegated to target. Cells whose
destination coordinate lies outside the target bounds are passed to
set_cell, which is expected to ignore them.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.