Guide API
Skip to main content

tvision_rs/
text.rs

1//! Width-aware Unicode text: measuring, scrolling, and drawing strings by
2//! **display column** rather than byte or codepoint.
3//!
4//! The core unit is the **grapheme cluster**: one cluster is one cell (two for
5//! a double-width glyph), and a cluster's column width comes from its base
6//! char. Combining marks attach to their base inside the cluster, and ZWJ
7//! emoji sequences collapse into a single cell. All layout and cursor math here
8//! measures in display columns.
9//!
10//! ### Cell occupancy of a grapheme
11//! Driven by the base char's [`unicode_width`]:
12//! * control char (`width() == None`) → the replacement glyph `�`, 1 column;
13//! * zero-width (combining-only / ZWJ-only cluster) → 0 columns (occupies no cell);
14//! * width 1 → 1 column;
15//! * width ≥ 2 → a *wide* lead cell + a trailing continuation cell (2 columns).
16//!
17//! **Guide:** [Drawing & backends](../../../internals/drawing.html).
18//!
19//! # Turbo Vision heritage
20//!
21//! Faithful port of the `TText` primitives (`ttext.h`, `ttext.cpp`). The original
22//! hand-decoded UTF-8 with a DFA and iterated per codepoint, appending combining
23//! marks onto the previous cell at draw time. Because Rust strings are already
24//! valid UTF-8 and `unicode-segmentation` yields grapheme clusters directly, tvision-rs
25//! drops the DFA and the append-combining-mark machinery and works one grapheme at
26//! a time (deviation D13) — which also clusters ZWJ emoji into one cell, where the
27//! per-codepoint model split them.
28
29use crate::color::Style;
30use crate::screen::Cell;
31use std::collections::BTreeMap;
32use unicode_segmentation::UnicodeSegmentation;
33use unicode_width::UnicodeWidthChar;
34
35/// The replacement glyph drawn for an unprintable (control) character.
36const REPLACEMENT: &str = "\u{FFFD}";
37
38/// Width, in display columns, the first grapheme of `g` occupies. `g` must be a
39/// single grapheme cluster. Returns `None` only for the empty string.
40fn grapheme_columns(g: &str) -> usize {
41    match g.chars().next() {
42        None => 0,
43        // C0/C1 control chars have no width; drawn as `�` (1 column).
44        Some(c) => UnicodeWidthChar::width(c).unwrap_or(1),
45    }
46}
47
48/// Byte length and column width of the first grapheme in `text`, or `None` when
49/// `text` is empty.
50pub fn next(text: &str) -> Option<(usize, usize)> {
51    let g = text.graphemes(true).next()?;
52    Some((g.len(), grapheme_columns(g)))
53}
54
55/// Byte length of the grapheme cluster *ending* at byte offset `index` in
56/// `text` (the cluster you would step back over from `index`). Returns 0 when
57/// `index == 0`.
58///
59/// Stepping `cur_pos -= prev(text, cur_pos)` lands the cursor on the previous
60/// cluster boundary, never inside a multi-byte codepoint or a combining sequence.
61///
62/// `index` must be a `char` boundary into `text` (it always is: every call site
63/// maintains `cur_pos` on grapheme boundaries). Returns 0 for `index == 0`.
64pub fn prev(text: &str, index: usize) -> usize {
65    if index == 0 {
66        return 0;
67    }
68    // The last grapheme of the prefix `text[..index]` is the one ending at
69    // `index`; its byte length is how far back the cursor steps.
70    text[..index]
71        .graphemes(true)
72        .next_back()
73        .map(|g| g.len())
74        .unwrap_or(0)
75}
76
77/// Width, the character (grapheme) count, and the number of non-zero-width
78/// graphemes of `text`.
79#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
80pub struct TextMetrics {
81    pub width: usize,
82    /// Total grapheme clusters (counts *clusters*, not codepoints — the two differ
83    /// across combining sequences).
84    pub character_count: usize,
85    /// Graphemes that occupy at least one column.
86    pub grapheme_count: usize,
87}
88
89/// Display width of `text` in columns.
90pub fn width(text: &str) -> usize {
91    text.graphemes(true).map(grapheme_columns).sum()
92}
93
94/// Display width of a *control string* — a label whose `~` markers delimit the
95/// hotkey letter and occupy no columns themselves (`"~O~K"` is 2 wide).
96///
97/// This is the measure the widgets that draw control strings (buttons, menus,
98/// the status line) centre and size with, so anything laying out around such a
99/// label must use it rather than [`width`], which would count the `~` markers.
100pub fn cstrlen(text: &str) -> i32 {
101    text.chars()
102        .filter(|&c| c != '~')
103        .map(|c| unicode_width::UnicodeWidthChar::width(c).unwrap_or(1) as i32)
104        .sum()
105}
106
107/// Width + grapheme metrics of `text`.
108pub fn measure(text: &str) -> TextMetrics {
109    let mut m = TextMetrics::default();
110    for g in text.graphemes(true) {
111        let w = grapheme_columns(g);
112        m.width += w;
113        m.character_count += 1;
114        m.grapheme_count += (w > 0) as usize;
115    }
116    m
117}
118
119/// Byte length of a leading substring of `text` that is `count` columns wide,
120/// together with that substring's actual width.
121///
122/// If `text` is narrower than `count`, the whole string is returned. Negative
123/// `count` is treated as 0. When column `count` falls in the middle of a
124/// double-width grapheme, `include_incomplete` decides whether that grapheme is
125/// included.
126pub fn scroll(text: &str, count: i32, include_incomplete: bool) -> (usize, usize) {
127    if count <= 0 {
128        return (0, 0);
129    }
130    let count = count as usize;
131    let mut i = 0; // byte offset
132    let mut w = 0; // accumulated width
133    loop {
134        let (i2, w2) = (i, w);
135        match next(&text[i..]) {
136            None => break,
137            Some((len, gw)) => {
138                i += len;
139                w += gw;
140                if w == count {
141                    break;
142                }
143                if w > count {
144                    if !include_incomplete {
145                        i = i2;
146                        w = w2;
147                    }
148                    break;
149                }
150            }
151        }
152    }
153    (i, w)
154}
155
156/// Write a single grapheme from `text` (at byte offset `j`) into `cells` at index
157/// `i`. Returns `(bytes_consumed, cells_advanced)`.
158///
159/// `cells_advanced` is 0 when there is no room (the caller stops), 0 for a
160/// zero-width grapheme (consumed but draws nothing), 1 for a normal glyph, and 2
161/// for a wide glyph that had room for its trailing cell.
162fn draw_one_impl(cells: &mut [Cell], i: usize, text: &str, j: usize) -> (usize, usize) {
163    let Some((len, w)) = next(&text[j..]) else {
164        return (0, 0);
165    };
166    let g = &text[j..j + len];
167    if w == 0 {
168        // Zero-width cluster (lone combining mark / ZWJ): consume, draw nothing.
169        // (Combining marks attach to their base inside the grapheme already.)
170        return (len, 0);
171    }
172    if i >= cells.len() {
173        // No room — signal the caller to stop.
174        return (0, 0);
175    }
176    let is_control = g
177        .chars()
178        .next()
179        .is_some_and(|c| UnicodeWidthChar::width(c).is_none());
180    if is_control {
181        cells[i].set_str(REPLACEMENT, false);
182        return (len, 1);
183    }
184    if w > 1 {
185        let has_trail = i + 1 < cells.len();
186        cells[i].set_str(g, true);
187        if has_trail {
188            cells[i + 1].set_wide_trail();
189        }
190        (len, 1 + has_trail as usize)
191    } else {
192        cells[i].set_str(g, false);
193        (len, 1)
194    }
195}
196
197/// Apply `transform` to a cell's style in place.
198fn apply(cell: &mut Cell, transform: &mut impl FnMut(&mut Style)) {
199    let mut s = cell.style();
200    transform(&mut s);
201    cell.set_style(s);
202}
203
204/// Write a single grapheme from `text` (at byte offset `j`) into `cells` at index
205/// `i`, applying `transform` to the [`Style`] of each cell written. Returns
206/// `(bytes_consumed, cells_advanced)`.
207///
208/// A wide glyph applies `transform` to both its lead and trailing cell.
209/// `cells_advanced == 0` with `bytes_consumed == 0` means there was no room — the
210/// caller should stop.
211pub fn draw_one(
212    cells: &mut [Cell],
213    i: usize,
214    text: &str,
215    j: usize,
216    mut transform: impl FnMut(&mut Style),
217) -> (usize, usize) {
218    let (len, advanced) = draw_one_impl(cells, i, text, j);
219    if advanced >= 1 {
220        apply(&mut cells[i], &mut transform);
221    }
222    if advanced > 1 {
223        apply(&mut cells[i + 1], &mut transform);
224    }
225    (len, advanced)
226}
227
228/// Copy `text` into `cells` starting at cell index `indent`, beginning from
229/// column `text_indent` of `text`, applying `transform` to the [`Style`] of each
230/// cell written. Returns the number of cells filled.
231///
232/// When `text_indent` lands in the middle of a double-width grapheme, a single
233/// space is emitted in its place.
234pub fn draw_str_ex(
235    cells: &mut [Cell],
236    indent: usize,
237    text: &str,
238    text_indent: i32,
239    mut transform: impl FnMut(&mut Style),
240) -> usize {
241    let mut i = indent;
242    let mut j = 0; // byte offset into text
243
244    if text_indent > 0 {
245        let (skipped_bytes, lead_width) = scroll(text, text_indent, true);
246        j = skipped_bytes;
247        if lead_width > text_indent as usize && i < cells.len() {
248            // Skipped past the middle of a wide glyph — pad with a space.
249            cells[i].set_char(' ');
250            apply(&mut cells[i], &mut transform);
251            i += 1;
252        }
253    }
254
255    loop {
256        let (len, advanced) = draw_one(cells, i, text, j, &mut transform);
257        i += advanced;
258        j += len;
259        if len == 0 {
260            break;
261        }
262    }
263    i - indent
264}
265
266/// Copy `text` into `cells` at `indent`/`text_indent` with a fixed `style`.
267pub fn draw_str(
268    cells: &mut [Cell],
269    indent: usize,
270    text: &str,
271    text_indent: i32,
272    style: Style,
273) -> usize {
274    draw_str_ex(cells, indent, text, text_indent, |s| *s = style)
275}
276
277// ---------------------------------------------------------------------------
278// StringList
279// ---------------------------------------------------------------------------
280
281/// A keyed lookup of strings (`u16` key → `String`).
282///
283/// Backed by a `BTreeMap<u16, String>`, so iteration is in ascending key order.
284/// A missing key returns `None` (callers that want an empty-string fallback can
285/// use `.unwrap_or("")`).
286///
287/// # Turbo Vision heritage
288///
289/// Ports `TStringList` / `TStrListMaker` (`tstrlist.cpp`). The original classes
290/// exist entirely to serialize a compressed keyed-string table to/from a
291/// resource (`.res`) stream; tvision-rs drops that streaming/persistence machinery
292/// (`TStrIndexRec`, the run-length index, the byte-length-prefixed blob, and
293/// `build`/`read`/`write`) and keeps only the observable contract — a keyed
294/// lookup of strings (deviation D12). The maker/list split, which existed only
295/// for the write-vs-read streaming asymmetry, collapses into one type.
296pub struct StringList {
297    map: BTreeMap<u16, String>,
298}
299
300impl StringList {
301    /// Create an empty `StringList`.
302    pub fn new() -> Self {
303        StringList {
304            map: BTreeMap::new(),
305        }
306    }
307
308    /// Associate `value` with `key`, overwriting any previous entry for that key.
309    ///
310    /// Use this to build a `StringList` at startup (the equivalent of
311    /// `TStrListMaker::Put` from Turbo Vision). Keys are arbitrary `u16` values;
312    /// iteration and lookup are in ascending key order.
313    ///
314    /// ```
315    /// use tvision_rs::text::StringList;
316    ///
317    /// let mut list = StringList::new();
318    /// list.insert(10, "Open");
319    /// list.insert(20, "Save");
320    /// list.insert(10, "Open…"); // overwrite key 10
321    /// assert_eq!(list.get(10), Some("Open…"));
322    /// assert_eq!(list.len(), 2);
323    /// ```
324    pub fn insert(&mut self, key: u16, value: impl Into<String>) {
325        self.map.insert(key, value.into());
326    }
327
328    /// Look up the string stored under `key`, returning a borrowed slice, or
329    /// `None` when no entry exists for that key.
330    ///
331    /// Use this to display or process a string identified by a numeric key — for
332    /// example, to retrieve a help message at runtime:
333    ///
334    /// ```
335    /// use tvision_rs::text::StringList;
336    ///
337    /// let mut list = StringList::new();
338    /// list.insert(1, "File not found");
339    /// assert_eq!(list.get(1), Some("File not found"));
340    /// assert_eq!(list.get(99), None);
341    ///
342    /// // Callers that need an empty-string fallback for missing keys:
343    /// let msg = list.get(99).unwrap_or("");
344    /// assert_eq!(msg, "");
345    /// ```
346    pub fn get(&self, key: u16) -> Option<&str> {
347        self.map.get(&key).map(String::as_str)
348    }
349
350    /// Number of entries in this `StringList`.
351    pub fn len(&self) -> usize {
352        self.map.len()
353    }
354
355    /// `true` when the `StringList` contains no entries.
356    pub fn is_empty(&self) -> bool {
357        self.map.is_empty()
358    }
359}
360
361impl Default for StringList {
362    fn default() -> Self {
363        StringList::new()
364    }
365}
366
367impl<S: Into<String>> FromIterator<(u16, S)> for StringList {
368    fn from_iter<I: IntoIterator<Item = (u16, S)>>(iter: I) -> Self {
369        let mut list = StringList::new();
370        for (key, value) in iter {
371            list.insert(key, value);
372        }
373        list
374    }
375}
376
377#[cfg(test)]
378mod tests {
379    use super::*;
380    use crate::color::Color;
381
382    fn render(cells: &[Cell]) -> String {
383        cells.iter().map(|c| c.symbol()).collect()
384    }
385
386    #[test]
387    fn width_ascii_and_wide() {
388        assert_eq!(width("hello"), 5);
389        assert_eq!(width(""), 0);
390        assert_eq!(width("中文"), 4); // two double-width ideographs
391        assert_eq!(width("a中b"), 4); // 1 + 2 + 1
392    }
393
394    #[test]
395    fn width_combining_clusters_as_one() {
396        // "e" + combining acute = one grapheme, width 1.
397        assert_eq!(width("e\u{0301}"), 1);
398        // Precomposed é is also width 1.
399        assert_eq!(width("é"), 1);
400    }
401
402    #[test]
403    fn measure_counts() {
404        let m = measure("a中");
405        assert_eq!(m.width, 3);
406        assert_eq!(m.character_count, 2);
407        assert_eq!(m.grapheme_count, 2);
408
409        // A combining mark clusters with its base: one grapheme, width 1.
410        let m2 = measure("e\u{0301}");
411        assert_eq!(m2.character_count, 1);
412        assert_eq!(m2.width, 1);
413    }
414
415    #[test]
416    fn prev_steps_back_one_grapheme() {
417        // ASCII: each step is one byte.
418        assert_eq!(prev("abc", 3), 1);
419        assert_eq!(prev("abc", 1), 1);
420        assert_eq!(prev("abc", 0), 0);
421        // Multi-byte: "ä" is 2 bytes in UTF-8; stepping back from the end of
422        // "aä" (3 bytes) returns 2 (the whole grapheme), never 1.
423        assert_eq!("aä".len(), 3);
424        assert_eq!(prev("aä", 3), 2);
425        assert_eq!(prev("aä", 1), 1);
426        // A combining sequence "e\u{0301}" (3 bytes) is one grapheme.
427        let s = "xe\u{0301}";
428        assert_eq!(prev(s, s.len()), "e\u{0301}".len());
429        // An emoji ZWJ cluster steps back as a single unit.
430        let fam = "👨\u{200d}👩\u{200d}👧";
431        let s2 = format!("a{fam}");
432        assert_eq!(prev(&s2, s2.len()), fam.len());
433    }
434
435    #[test]
436    fn scroll_basic() {
437        // First 3 columns of "abcdef" -> 3 bytes, width 3.
438        assert_eq!(scroll("abcdef", 3, true), (3, 3));
439        // Wider than the string -> whole string.
440        assert_eq!(scroll("abc", 10, true), (3, 3));
441        // Non-positive count -> empty.
442        assert_eq!(scroll("abc", 0, true), (0, 0));
443        assert_eq!(scroll("abc", -5, true), (0, 0));
444    }
445
446    #[test]
447    fn scroll_straddles_wide_glyph() {
448        // "中" is 2 columns. Asking for 1 column lands mid-glyph.
449        // include_incomplete = true -> include the glyph (2 bytes? no, 3 bytes UTF-8).
450        let (bytes_incl, w_incl) = scroll("中x", 1, true);
451        assert_eq!((bytes_incl, w_incl), ("中".len(), 2));
452        // include_incomplete = false -> exclude it (stop before).
453        let (bytes_excl, w_excl) = scroll("中x", 1, false);
454        assert_eq!((bytes_excl, w_excl), (0, 0));
455    }
456
457    #[test]
458    fn draw_str_ascii() {
459        let mut cells = vec![Cell::default(); 10];
460        let style = Style::new(Color::Bios(0xF), Color::Bios(0x1));
461        let n = draw_str(&mut cells, 0, "hi", 0, style);
462        assert_eq!(n, 2);
463        assert_eq!(cells[0].symbol(), "h");
464        assert_eq!(cells[0].style(), style);
465        assert_eq!(cells[1].symbol(), "i");
466        // untouched cells remain blank
467        assert_eq!(cells[2].symbol(), " ");
468    }
469
470    #[test]
471    fn draw_str_wide_glyph_sets_trail() {
472        let mut cells = vec![Cell::default(); 10];
473        let n = draw_str(&mut cells, 0, "中", 0, Style::default());
474        assert_eq!(n, 2); // lead + trail
475        assert!(cells[0].is_wide());
476        assert_eq!(cells[0].symbol(), "中");
477        assert!(cells[1].is_wide_trail());
478        assert_eq!(cells[1].symbol(), "");
479    }
480
481    #[test]
482    fn draw_str_indent_into_cells() {
483        let mut cells = vec![Cell::default(); 10];
484        draw_str(&mut cells, 3, "ab", 0, Style::default());
485        assert_eq!(cells[2].symbol(), " ");
486        assert_eq!(cells[3].symbol(), "a");
487        assert_eq!(cells[4].symbol(), "b");
488    }
489
490    #[test]
491    fn draw_str_text_indent_skips_columns() {
492        let mut cells = vec![Cell::default(); 10];
493        let n = draw_str(&mut cells, 0, "abcdef", 2, Style::default());
494        assert_eq!(n, 4);
495        assert_eq!(render(&cells[..4]), "cdef");
496    }
497
498    #[test]
499    fn draw_str_text_indent_mid_wide_glyph_pads_space() {
500        // "中" occupies columns 0..2. Starting at column 1 splits it -> a space.
501        let mut cells = vec![Cell::default(); 10];
502        let n = draw_str(&mut cells, 0, "中x", 1, Style::default());
503        assert_eq!(cells[0].symbol(), " "); // padding for the split wide glyph
504        assert_eq!(cells[1].symbol(), "x");
505        assert_eq!(n, 2);
506    }
507
508    #[test]
509    fn draw_str_truncates_at_cell_boundary() {
510        let mut cells = vec![Cell::default(); 3];
511        let n = draw_str(&mut cells, 0, "abcdef", 0, Style::default());
512        assert_eq!(n, 3);
513        assert_eq!(render(&cells), "abc");
514    }
515
516    #[test]
517    fn draw_str_wide_glyph_truncated_when_no_room_for_trail() {
518        // Only one cell free, but a wide glyph needs two: lead is written,
519        // trail is truncated, count is 1.
520        let mut cells = vec![Cell::default(); 1];
521        let n = draw_str(&mut cells, 0, "中", 0, Style::default());
522        assert_eq!(n, 1);
523        assert!(cells[0].is_wide());
524    }
525
526    #[test]
527    fn draw_str_control_char_becomes_replacement() {
528        let mut cells = vec![Cell::default(); 5];
529        let n = draw_str(&mut cells, 0, "a\u{0007}b", 0, Style::default()); // BEL
530        assert_eq!(n, 3);
531        assert_eq!(cells[0].symbol(), "a");
532        assert_eq!(cells[1].symbol(), REPLACEMENT);
533        assert_eq!(cells[2].symbol(), "b");
534    }
535
536    #[test]
537    fn draw_str_ex_transform_sees_each_cell() {
538        let mut cells = vec![Cell::default(); 5];
539        let mut count = 0;
540        draw_str_ex(&mut cells, 0, "中a", 0, |s| {
541            count += 1;
542            s.modifiers.bold = true;
543        });
544        // lead + trail + 'a' = 3 transform calls
545        assert_eq!(count, 3);
546        assert!(cells[0].style().modifiers.bold);
547        assert!(cells[1].style().modifiers.bold); // trail too
548        assert!(cells[2].style().modifiers.bold);
549    }
550
551    // --- StringList tests ---
552
553    #[test]
554    fn string_list_insert_and_get_round_trip() {
555        let mut sl = StringList::new();
556        sl.insert(10, "hello");
557        sl.insert(20, "world");
558        assert_eq!(sl.get(10), Some("hello"));
559        assert_eq!(sl.get(20), Some("world"));
560    }
561
562    #[test]
563    fn string_list_missing_key_returns_none() {
564        let sl = StringList::new();
565        assert_eq!(sl.get(42), None);
566    }
567
568    #[test]
569    fn string_list_overwrite_keeps_latest_value() {
570        let mut sl = StringList::new();
571        sl.insert(5, "first");
572        sl.insert(5, "second");
573        assert_eq!(sl.get(5), Some("second"));
574        assert_eq!(sl.len(), 1);
575    }
576
577    #[test]
578    fn string_list_ordered_iteration() {
579        let mut sl = StringList::new();
580        // Insert out of order.
581        sl.insert(30, "c");
582        sl.insert(10, "a");
583        sl.insert(20, "b");
584        // BTreeMap guarantees ascending key order.
585        let pairs: Vec<(&u16, &String)> = sl.map.iter().collect();
586        assert_eq!(*pairs[0].0, 10);
587        assert_eq!(*pairs[1].0, 20);
588        assert_eq!(*pairs[2].0, 30);
589    }
590
591    #[test]
592    fn string_list_len_and_is_empty() {
593        let mut sl = StringList::new();
594        assert!(sl.is_empty());
595        assert_eq!(sl.len(), 0);
596        sl.insert(1, "x");
597        assert!(!sl.is_empty());
598        assert_eq!(sl.len(), 1);
599        sl.insert(2, "y");
600        assert_eq!(sl.len(), 2);
601    }
602
603    #[test]
604    fn string_list_from_iterator() {
605        let entries: Vec<(u16, &str)> = vec![(1, "one"), (2, "two"), (3, "three")];
606        let sl: StringList = entries.into_iter().collect();
607        assert_eq!(sl.len(), 3);
608        assert_eq!(sl.get(1), Some("one"));
609        assert_eq!(sl.get(2), Some("two"));
610        assert_eq!(sl.get(3), Some("three"));
611        assert_eq!(sl.get(4), None);
612    }
613
614    #[test]
615    fn string_list_from_iterator_owned_strings() {
616        let entries: Vec<(u16, String)> = vec![
617            (100, "hundred".to_string()),
618            (200, "two hundred".to_string()),
619        ];
620        let sl: StringList = entries.into_iter().collect();
621        assert_eq!(sl.get(100), Some("hundred"));
622        assert_eq!(sl.get(200), Some("two hundred"));
623    }
624
625    #[test]
626    fn string_list_default_is_empty() {
627        let sl = StringList::default();
628        assert!(sl.is_empty());
629    }
630}