pub struct Cell {
pub style: Style,
/* private fields */
}Expand description
A single terminal-grid cell.
Cell is the value stored in buffers and surfaces. It contains the
grapheme content for a column, the style applied to that content, and the
number of columns the content occupies.
Use Cell::new for construction and Cell::BLANK for an empty
styled-as-default space. Continuations are normally produced by the
surface write path rather than by application code.
Fields§
§style: StyleVisual style: colors, attributes, underline, and any attached
hyperlink. The link inside style is reference-counted so a
run of identically-linked cells shares a single allocation
without per-cell deep clones.
Implementations§
Source§impl Cell
impl Cell
Sourcepub const BLANK: Cell
pub const BLANK: Cell
A blank one-column cell with default style.
The blank cell stores a single space (" "), uses Style::EMPTY,
and has width 1.
§Returns
This is a constant value, so use it directly wherever a default blank cell is needed.
§Panics
Never panics.
§Usage notes
Clearing and newly allocated buffers use BLANK. Clone it when an
owned value is required.
Sourcepub const CONTINUATION: Cell
pub const CONTINUATION: Cell
A continuation placeholder with default style.
The placeholder stores no content, uses Style::EMPTY, and has
width 0. Cell::is_continuation reports true for it.
§Returns
This is a constant value, so use it directly wherever a continuation is needed.
§Panics
Never panics.
§Usage notes
A wide cell is followed by width - 1 of these, one
for every column the cell owns beyond its first. The surface write
path lays them down; application code needs them only when it builds
a row by hand.
Under background color erase a continuation carries the style of the cell that owns it, so clone the constant and give it that style rather than leaving it default.
Sourcepub fn new(content: impl Into<CompactString>, width: u8) -> Self
pub fn new(content: impl Into<CompactString>, width: u8) -> Self
Create a cell holding content across width terminal columns.
§Parameters
content: grapheme content to store in the cell.width: number of terminal columns the content occupies. Width0makes a continuation placeholder whatever the content, so useCell::CONTINUATIONwhen that is what you mean.
§Returns
A cell with the given content and width, and the default style.
§Panics
Never panics.
§Usage notes
This constructor does not validate that width matches the display
width of content; the caller chooses the measurement policy. Use
WidthMode::grapheme_width
to measure, so the stored width matches what the terminal advances.
When a cell wider than one column is written through the
buffer/surface write path, the width - 1 slots to its right are
filled with continuation placeholders automatically. If there is no
room for them at the row’s right edge,
Buffer::set stores a blank instead of
part of a grapheme.
Sourcepub fn is_wide(&self) -> bool
pub fn is_wide(&self) -> bool
Test whether this cell occupies more than one column.
§Returns
true when Cell::width is 2 or more.
§Panics
Never panics.
§Usage notes
Width alone decides the answer, because width alone decides how many columns the cell takes. A cell that stores no content still owns the columns its width names, and the blank drawn in its place covers all of them.
In a well-formed surface, such a cell is followed immediately by
width - 1 continuation placeholders.
Sourcepub fn is_continuation(&self) -> bool
pub fn is_continuation(&self) -> bool
Test whether this is a continuation placeholder.
§Returns
true when Cell::width is 0.
§Panics
Never panics.
§Usage notes
Width alone decides, as it does for Cell::is_wide: a cell that
claims no column has none to draw in, so whatever it stores is never
reached. Width 0, 1, and 2 or more partition every cell into a
continuation, a narrow cell, and a wide one.
Sourcepub fn is_blank(&self) -> bool
pub fn is_blank(&self) -> bool
Test whether this cell is a single blank column.
§Returns
true when the cell claims one column and draws a space in it, which
is the shape of Cell::BLANK.
§Panics
Never panics.
§Usage notes
Style is not considered. A styled space is still blank, because this method answers what the cell occupies rather than how it is painted.
Width is considered, so the answer stays about one column. A
continuation claims none, and a cell claiming several stands for a
span rather than a single blank; each is something other than a blank
column, and each reports false.
A cell that claims its one column while storing nothing draws a space
there, the same as Cell::BLANK, and answers the same way. The
question is what reaches the column, so two cells that put the same
thing in it give one answer.
Sourcepub fn width(&self) -> u8
pub fn width(&self) -> u8
Column footprint of this cell on the grid.
§Returns
The number of terminal columns owned by this cell: 0 for a
continuation placeholder, otherwise the width passed to
Cell::new.
§Panics
Never panics.
§Usage notes
Row walkers generally advance by cell.width().max(1) after handling
continuations, so they make progress even when encountering a
continuation placeholder.
Sourcepub fn style(self, style: impl Into<Style>) -> Self
pub fn style(self, style: impl Into<Style>) -> Self
Return this cell with a replacement style.
§Parameters
style: style to store on the returned cell.
§Returns
self with its style field replaced by style.
§Panics
Never panics.
§Usage notes
This builder-style method preserves content and width. Styling a continuation is possible, but continuations do not render independent content.