Struct Buffer

pub struct Buffer {
    pub area: Rect,
    pub content: Vec<Cell>,
}

A buffer that maps to the desired content of the terminal after the draw call

No widget in the library interacts directly with the terminal. Instead each of them is required to draw their state to an intermediate buffer. It is basically a grid where each cell contains a grapheme, a foreground color and a background color. This grid will then be used to output the appropriate escape sequences and characters to draw the UI as the user has defined it.

Examples:

use ratatui::{
    buffer::{Buffer, Cell},
    layout::{Position, Rect},
    style::{Color, Style},
};

let mut buf = Buffer::empty(Rect {
    x: 0,
    y: 0,
    width: 10,
    height: 5,
});

// indexing using Position
buf[Position { x: 0, y: 0 }].set_symbol("A");
assert_eq!(buf[Position { x: 0, y: 0 }].symbol(), "A");

// indexing using (x, y) tuple (which is converted to Position)
buf[(0, 1)].set_symbol("B");
assert_eq!(buf[(0, 1)].symbol(), "x");

// getting an Option instead of panicking if the position is outside the buffer
let cell = buf.cell_mut(Position { x: 0, y: 2 })?;
cell.set_symbol("C");

let cell = buf.cell(Position { x: 0, y: 2 })?;
assert_eq!(cell.symbol(), "C");

buf.set_string(
    3,
    0,
    "string",
    Style::default().fg(Color::Red).bg(Color::White),
);
let cell = &buf[(5, 0)]; // cannot move out of buf, so we borrow it
assert_eq!(cell.symbol(), "r");
assert_eq!(cell.fg, Color::Red);
assert_eq!(cell.bg, Color::White);

Fields

area: Rect

The area represented by this buffer

content: Vec<Cell>

The content of the buffer. The length of this Vec should always be equal to area.width * area.height

Implementations

impl Buffer

pub fn empty(area: Rect) -> Self

Returns a Buffer with all cells set to the default one

pub fn filled(area: Rect, cell: Cell) -> Self

Returns a Buffer with all cells initialized with the attributes of the given Cell

pub fn with_lines<'a, Iter>(lines: Iter) -> Self

where Iter: IntoIterator, Iter::Item: Into<Line<'a>>,

Returns a Buffer containing the given lines

pub fn content(&self) -> &[Cell]

Returns the content of the buffer as a slice

pub const fn area(&self) -> &Rect

Returns the area covered by this buffer

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

👎Deprecated: Use Buffer[] or Buffer::cell instead

Returns a reference to the Cell at the given coordinates

Callers should use Buffer[] or Buffer::cell instead of this method.

Note: idiomatically methods named get usually return Option<&T>, but this method panics instead. This is kept for backwards compatibility. See cell for a safe alternative.

Panics

Panics if the index is out of bounds.

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

👎Deprecated: Use Buffer[] or Buffer::cell_mut instead

Returns a mutable reference to the Cell at the given coordinates.

Callers should use Buffer[] or Buffer::cell_mut instead of this method.

Note: idiomatically methods named get_mut usually return Option<&mut T>, but this method panics instead. This is kept for backwards compatibility. See cell_mut for a safe alternative.

Panics

Panics if the position is outside the Buffer’s area.

pub fn cell<P: Into<Position>>(&self, position: P) -> Option<&Cell>

Returns a reference to the Cell at the given position or None if the position is outside the Buffer’s area.

This method accepts any value that can be converted to Position (e.g. (x, y) or Position::new(x, y)).

For a method that panics when the position is outside the buffer instead of returning None, use Buffer[].

Examples

use ratatui::{
    buffer::{Buffer, Cell},
    layout::{Position, Rect},
};

let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));

assert_eq!(buffer.cell(Position::new(0, 0)), Some(&Cell::default()));
assert_eq!(buffer.cell(Position::new(10, 10)), None);
assert_eq!(buffer.cell((0, 0)), Some(&Cell::default()));
assert_eq!(buffer.cell((10, 10)), None);

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

Returns a mutable reference to the Cell at the given position or None if the position is outside the Buffer’s area.

This method accepts any value that can be converted to Position (e.g. (x, y) or Position::new(x, y)).

For a method that panics when the position is outside the buffer instead of returning None, use Buffer[].

Examples

use ratatui::{
    buffer::{Buffer, Cell},
    layout::{Position, Rect},
    style::{Color, Style},
};
let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));

if let Some(cell) = buffer.cell_mut(Position::new(0, 0)) {
    cell.set_symbol("A");
}
if let Some(cell) = buffer.cell_mut((0, 0)) {
    cell.set_style(Style::default().fg(Color::Red));
}

pub fn index_of(&self, x: u16, y: u16) -> usize

Returns the index in the Vec<Cell> for the given global (x, y) coordinates.

Global coordinates are offset by the Buffer’s area offset (x/y).

Examples

use ratatui::{buffer::Buffer, layout::Rect};

let buffer = Buffer::empty(Rect::new(200, 100, 10, 10));
// Global coordinates to the top corner of this buffer's area
assert_eq!(buffer.index_of(200, 100), 0);

Panics

Panics when given an coordinate that is outside of this Buffer’s area.

use ratatui::{buffer::Buffer, layout::Rect};

let buffer = Buffer::empty(Rect::new(200, 100, 10, 10));
// Top coordinate is outside of the buffer in global coordinate space, as the Buffer's area
// starts at (200, 100).
buffer.index_of(0, 0); // Panics

pub fn pos_of(&self, i: usize) -> (u16, u16)

Returns the (global) coordinates of a cell given its index

Global coordinates are offset by the Buffer’s area offset (x/y).

Examples

use ratatui::{buffer::Buffer, layout::Rect};

let rect = Rect::new(200, 100, 10, 10);
let buffer = Buffer::empty(rect);
assert_eq!(buffer.pos_of(0), (200, 100));
assert_eq!(buffer.pos_of(14), (204, 101));

Panics

Panics when given an index that is outside the Buffer’s content.

use ratatui::{buffer::Buffer, layout::Rect};

let rect = Rect::new(0, 0, 10, 10); // 100 cells in total
let buffer = Buffer::empty(rect);
// Index 100 is the 101th cell, which lies outside of the area of this Buffer.
buffer.pos_of(100); // Panics

pub fn set_string<T, S>(&mut self, x: u16, y: u16, string: T, style: S)

where T: AsRef<str>, S: Into<Style>,

Print a string, starting at the position (x, y)

pub fn set_stringn<T, S>( &mut self, x: u16, y: u16, string: T, max_width: usize, style: S, ) -> (u16, u16)

where T: AsRef<str>, S: Into<Style>,

Print at most the first n characters of a string if enough space is available until the end of the line. Skips zero-width graphemes and control characters.

Use Buffer::set_string when the maximum amount of characters can be printed.

pub fn set_line( &mut self, x: u16, y: u16, line: &Line<'_>, max_width: u16, ) -> (u16, u16)

Print a line, starting at the position (x, y)

pub fn set_span( &mut self, x: u16, y: u16, span: &Span<'_>, max_width: u16, ) -> (u16, u16)

Print a span, starting at the position (x, y)

pub fn set_style<S: Into<Style>>(&mut self, area: Rect, style: S)

Set the style of all cells in the given area.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

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

Resize the buffer so that the mapped area matches the given area and that the buffer length is equal to area.width * area.height

pub fn reset(&mut self)

Reset all cells in the buffer

pub fn merge(&mut self, other: &Self)

Merge an other buffer into this one

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

Builds a minimal sequence of coordinates and Cells necessary to update the UI from self to other.

We’re assuming that buffers are well-formed, that is no double-width cell is followed by a non-blank cell.

Multi-width characters handling:

(Index:) `01`
Prev:    `コ`
Next:    `aa`
Updates: `0: a, 1: a'

(Index:) `01`
Prev:    `a `
Next:    `コ`
Updates: `0: コ` (double width symbol at index 0 - skip index 1)

(Index:) `012`
Prev:    `aaa`
Next:    `aコ`
Updates: `0: a, 1: コ` (double width symbol at index 1 - skip index 2)

Trait Implementations

impl Clone for Buffer

fn clone(&self) -> Buffer

Returns a copy 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

Writes a debug representation of the buffer to the given formatter.

The format is like a pretty printed struct, with the following fields:

• area: displayed as Rect { x: 1, y: 2, width: 3, height: 4 }
• content: displayed as a list of strings representing the content of the buffer
• styles: displayed as a list of: { x: 1, y: 2, fg: Color::Red, bg: Color::Blue, modifier: Modifier::BOLD } only showing a value when there is a change in style.

impl Default for Buffer

fn default() -> Buffer

Returns the “default value” for a type.

impl Hash for Buffer

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<P: Into<Position>> Index<P> for Buffer

fn index(&self, position: P) -> &Self::Output

Returns a reference to the Cell at the given position.

This method accepts any value that can be converted to Position (e.g. (x, y) or Position::new(x, y)).

Panics

May panic if the given position is outside the buffer’s area. For a method that returns None instead of panicking, use Buffer::cell.

Examples

use ratatui::{
    buffer::{Buffer, Cell},
    layout::{Position, Rect},
};

let buf = Buffer::empty(Rect::new(0, 0, 10, 10));
let cell = &buf[(0, 0)];
let cell = &buf[Position::new(0, 0)];

type Output = Cell

The returned type after indexing.

impl<P: Into<Position>> IndexMut<P> for Buffer

fn index_mut(&mut self, position: P) -> &mut Self::Output

Returns a mutable reference to the Cell at the given position.

This method accepts any value that can be converted to Position (e.g. (x, y) or Position::new(x, y)).

Panics

May panic if the given position is outside the buffer’s area. For a method that returns None instead of panicking, use Buffer::cell_mut.

Examples

use ratatui::{
    buffer::{Buffer, Cell},
    layout::{Position, Rect},
};

let mut buf = Buffer::empty(Rect::new(0, 0, 10, 10));
buf[(0, 0)].set_symbol("A");
buf[Position::new(0, 0)].set_symbol("B");

impl PartialEq for Buffer

fn eq(&self, other: &Buffer) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Buffer

impl StructuralPartialEq for Buffer