Expand description
Width-aware Unicode text: measuring, scrolling, and drawing strings by display column rather than byte or codepoint.
The core unit is the grapheme cluster: one cluster is one cell (two for a double-width glyph), and a cluster’s column width comes from its base char. Combining marks attach to their base inside the cluster, and ZWJ emoji sequences collapse into a single cell. All layout and cursor math here measures in display columns.
§Cell occupancy of a grapheme
Driven by the base char’s [unicode_width]:
- control char (
width() == None) → the replacement glyph�, 1 column; - zero-width (combining-only / ZWJ-only cluster) → 0 columns (occupies no cell);
- width 1 → 1 column;
- width ≥ 2 → a wide lead cell + a trailing continuation cell (2 columns).
Guide: Drawing & backends.
§Turbo Vision heritage
Faithful port of the TText primitives (ttext.h, ttext.cpp). The original
hand-decoded UTF-8 with a DFA and iterated per codepoint, appending combining
marks onto the previous cell at draw time. Because Rust strings are already
valid UTF-8 and unicode-segmentation yields grapheme clusters directly, tvision-rs
drops the DFA and the append-combining-mark machinery and works one grapheme at
a time (deviation D13) — which also clusters ZWJ emoji into one cell, where the
per-codepoint model split them.
Structs§
- String
List - A keyed lookup of strings (
u16key →String). - Text
Metrics - Width, the character (grapheme) count, and the number of non-zero-width
graphemes of
text.
Functions§
- cstrlen
- Display width of a control string — a label whose
~markers delimit the hotkey letter and occupy no columns themselves ("~O~K"is 2 wide). - draw_
one - Write a single grapheme from
text(at byte offsetj) intocellsat indexi, applyingtransformto theStyleof each cell written. Returns(bytes_consumed, cells_advanced). - draw_
str - Copy
textintocellsatindent/text_indentwith a fixedstyle. - draw_
str_ ex - Copy
textintocellsstarting at cell indexindent, beginning from columntext_indentoftext, applyingtransformto theStyleof each cell written. Returns the number of cells filled. - measure
- Width + grapheme metrics of
text. - next
- Byte length and column width of the first grapheme in
text, orNonewhentextis empty. - prev
- Byte length of the grapheme cluster ending at byte offset
indexintext(the cluster you would step back over fromindex). Returns 0 whenindex == 0. - scroll
- Byte length of a leading substring of
textthat iscountcolumns wide, together with that substring’s actual width. - width
- Display width of
textin columns.