Guide API
Skip to main content

Module text

Module text 

Source
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§

StringList
A keyed lookup of strings (u16 key → String).
TextMetrics
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 offset j) into cells at index i, applying transform to the Style of each cell written. Returns (bytes_consumed, cells_advanced).
draw_str
Copy text into cells at indent/text_indent with a fixed style.
draw_str_ex
Copy text into cells starting at cell index indent, beginning from column text_indent of text, applying transform to the Style of 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, or None when text is empty.
prev
Byte length of the grapheme cluster ending at byte offset index in text (the cluster you would step back over from index). Returns 0 when index == 0.
scroll
Byte length of a leading substring of text that is count columns wide, together with that substring’s actual width.
width
Display width of text in columns.