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}