feat(buffer): deprecate Cell::symbol field

Signed-off-by: rhysd <lin90162@yahoo.co.jp>

src/backend/crossterm.rs

@@ -161,7 +161,7 @@ where
                 underline_color = cell.underline_color;
             }
 
-            queue!(self.writer, Print(&cell.symbol))?;
+            queue!(self.writer, Print(cell.symbol()))?;
         }
 
         #[cfg(feature = "underline-color")]

src/backend/termion.rs

@@ -179,7 +179,7 @@ where
                 write!(string, "{}", Bg(cell.bg)).unwrap();
                 bg = cell.bg;
             }
-            string.push_str(&cell.symbol);
+            string.push_str(cell.symbol());
         }
         write!(
             self.writer,

src/backend/termwiz.rs

@@ -176,7 +176,7 @@ impl Backend for TermwizBackend {
                     },
                 )));
 
-            self.buffered_terminal.add_change(&cell.symbol);
+            self.buffered_terminal.add_change(cell.symbol());
         }
         Ok(())
     }

src/backend/test.rs

@@ -56,11 +56,11 @@ fn buffer_view(buffer: &Buffer) -> String {
         view.push('"');
         for (x, c) in cells.iter().enumerate() {
             if skip == 0 {
-                view.push_str(&c.symbol);
+                view.push_str(c.symbol());
             } else {
-                overwritten.push((x, &c.symbol));
+                overwritten.push((x, c.symbol()));
             }
-            skip = std::cmp::max(skip, c.symbol.width()).saturating_sub(1);
+            skip = std::cmp::max(skip, c.symbol().width()).saturating_sub(1);
         }
         view.push('"');
         if !overwritten.is_empty() {

src/buffer.rs

@@ -16,6 +16,10 @@ use crate::{
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Cell {
+    #[deprecated(
+        since = "0.24.1",
+        note = "This field will be hidden at next major version. Use `Cell::symbol` method to get the value. Use `Cell::set_symbol` to update the field. Use `Cell::default` to create `Cell` instance"
+    )]
     pub symbol: String,
     pub fg: Color,
     pub bg: Color,
@@ -25,7 +29,12 @@ pub struct Cell {
     pub skip: bool,
 }
 
+#[allow(deprecated)] // For Cell::symbol
 impl Cell {
+    pub fn symbol(&self) -> &str {
+        self.symbol.as_str()
+    }
+
     pub fn set_symbol(&mut self, symbol: &str) -> &mut Cell {
         self.symbol.clear();
         self.symbol.push_str(symbol);
@@ -106,6 +115,7 @@ impl Cell {
 
 impl Default for Cell {
     fn default() -> Cell {
+        #[allow(deprecated)] // For Cell::symbol
         Cell {
             symbol: " ".into(),
             fg: Color::Reset,
@@ -132,7 +142,7 @@ impl Default for Cell {
 ///
 /// let mut buf = Buffer::empty(Rect{x: 0, y: 0, width: 10, height: 5});
 /// buf.get_mut(0, 2).set_symbol("x");
-/// assert_eq!(buf.get(0, 2).symbol, "x");
+/// assert_eq!(buf.get(0, 2).symbol(), "x");
 /// buf.set_string(3, 0, "string", Style::default().fg(Color::Red).bg(Color::White));
 /// assert_eq!(buf.get(5, 0), &Cell{
 ///     symbol: String::from("r"),
@@ -144,7 +154,7 @@ impl Default for Cell {
 ///     skip: false
 /// });
 /// buf.get_mut(5, 0).set_char('x');
-/// assert_eq!(buf.get(5, 0).symbol, "x");
+/// assert_eq!(buf.get(5, 0).symbol(), "x");
 /// ```
 #[derive(Default, Clone, Eq, PartialEq, Hash)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
@@ -471,9 +481,9 @@ impl Buffer {
                 updates.push((x, y, &next_buffer[i]));
             }
 
-            to_skip = current.symbol.width().saturating_sub(1);
+            to_skip = current.symbol().width().saturating_sub(1);
 
-            let affected_width = std::cmp::max(current.symbol.width(), previous.symbol.width());
+            let affected_width = std::cmp::max(current.symbol().width(), previous.symbol().width());
             invalidated = std::cmp::max(affected_width, invalidated).saturating_sub(1);
         }
         updates
@@ -555,11 +565,11 @@ impl Debug for Buffer {
             f.write_str("        \"")?;
             for (x, c) in line.iter().enumerate() {
                 if skip == 0 {
-                    f.write_str(&c.symbol)?;
+                    f.write_str(c.symbol())?;
                 } else {
-                    overwritten.push((x, &c.symbol));
+                    overwritten.push((x, c.symbol()));
                 }
-                skip = std::cmp::max(skip, c.symbol.width()).saturating_sub(1);
+                skip = std::cmp::max(skip, c.symbol().width()).saturating_sub(1);
                 #[cfg(feature = "underline-color")]
                 {
                     let style = (c.fg, c.bg, c.underline_color, c.modifier);
@@ -1043,4 +1053,14 @@ mod tests {
         buf.set_string(0, 1, "bar", Style::new().blue());
         assert_eq!(buf, Buffer::with_lines(vec!["foo".red(), "bar".blue()]));
     }
+
+    #[test]
+    fn cell_symbol_field() {
+        let mut cell = Cell::default();
+        assert_eq!(cell.symbol(), " ");
+        cell.set_symbol("あ"); // Multi-byte character
+        assert_eq!(cell.symbol(), "あ");
+        cell.set_symbol("👨‍👩‍👧‍👦"); // Multiple code units combined with ZWJ
+        assert_eq!(cell.symbol(), "👨‍👩‍👧‍👦");
+    }
 }

src/widgets/canvas/line.rs

@@ -128,7 +128,7 @@ mod tests {
 
         let mut expected = Buffer::with_lines(expected_lines);
         for cell in expected.content.iter_mut() {
-            if cell.symbol == "•" {
+            if cell.symbol() == "•" {
                 cell.set_style(Style::new().red());
             }
         }

tests/terminal.rs

@@ -25,9 +25,9 @@ fn swap_buffer_clears_prev_buffer() {
     terminal
         .current_buffer_mut()
         .set_string(0, 0, "Hello", ratatui::style::Style::reset());
-    assert_eq!(terminal.current_buffer_mut().content()[0].symbol, "H");
+    assert_eq!(terminal.current_buffer_mut().content()[0].symbol(), "H");
     terminal.swap_buffers();
-    assert_eq!(terminal.current_buffer_mut().content()[0].symbol, " ");
+    assert_eq!(terminal.current_buffer_mut().content()[0].symbol(), " ");
 }
 
 #[test]
@@ -38,14 +38,14 @@ fn terminal_draw_returns_the_completed_frame() -> Result<(), Box<dyn Error>> {
         let paragraph = Paragraph::new("Test");
         f.render_widget(paragraph, f.size());
     })?;
-    assert_eq!(frame.buffer.get(0, 0).symbol, "T");
+    assert_eq!(frame.buffer.get(0, 0).symbol(), "T");
     assert_eq!(frame.area, Rect::new(0, 0, 10, 10));
     terminal.backend_mut().resize(8, 8);
     let frame = terminal.draw(|f| {
         let paragraph = Paragraph::new("test");
         f.render_widget(paragraph, f.size());
     })?;
-    assert_eq!(frame.buffer.get(0, 0).symbol, "t");
+    assert_eq!(frame.buffer.get(0, 0).symbol(), "t");
     assert_eq!(frame.area, Rect::new(0, 0, 8, 8));
     Ok(())
 }