Module text 

Text measurement and string painting for terminal-cell surfaces.

This module is the text layer for SurfaceMut: it segments UTF-8 strings into grapheme clusters, measures their terminal display width, and writes cells into any mutable surface implementation. Painting is literal by default; the optional Painter interprets inline SGR and OSC 8 escapes as styling.

Width measurement and grapheme handling

Terminal layout is expressed in cells, not bytes or scalar values. The width API therefore separates segmentation from measurement:

• grapheme_cells always walks a string as extended grapheme clusters.
• WidthMode::Wc measures each cluster by its first code point.
• WidthMode::Grapheme measures the whole cluster with grapheme_width, including variation selectors, regional indicators, zero-width joiners, and pictographic presentation.
• char_width measures a single code point and is useful for code that already has its own segmentation.

bytes/scalars             grapheme cluster              terminal cells
┌───────────────┐         ┌───────────────┐             ┌────┬────┐
│ "e" + U+0301  │ ──────▶ │ "e\u{0301}"   │ ─ width 1 ▶ │ é  │    │
└───────────────┘         └───────────────┘             └────┴────┘

┌───────────────┐         ┌───────────────┐             ┌────┬────┐
│ "中"          │ ──────▶ │ "中"          │ ─ width 2 ▶ │ 中 │ ▶  │
└───────────────┘         └───────────────┘             └────┴────┘

A width of 0 is not written as a standalone cell. While painting, a zero-width cluster is appended to the previous pending cluster so combining marks and similar suffixes stay attached to the base cell.

East-Asian-Width policy

The eaw_wide boolean is the East-Asian Ambiguous policy. When it is true, code points whose East-Asian-Width property is Ambiguous are measured as two cells; when it is false, they are measured as one. This is intentionally independent from WidthMode so callers can choose the terminal’s ambiguous-width policy without changing grapheme segmentation.

Painting and wrapping

Painter binds a target SurfaceMut, a WidthMode, and an eaw_wide policy. It paints styled strings into the target, honoring inline SGR (CSI … m) attributes and OSC 8 hyperlinks. WrapMode controls only what happens when a non-zero-width cluster would cross the right edge of the clipping rectangle: truncate or continue at the next row.

The TextSurface trait

TextSurface is the ergonomic extension trait for drawing text onto any surface. A surface supplies its WidthMode and East-Asian-Width policy; the trait then provides TextSurface::set_str, TextSurface::set_str_wrap, TextSurface::set_str_rect, TextSurface::set_str_rect_wrap, and TextSurface::str_width. This keeps higher-level widgets generic over &mut impl TextSurface instead of depending on a concrete buffer type.

Feature backends

The default unicode-rs feature uses compact built-in tables for code-point width plus a conservative pictographic/default-ignorable subset. Enabling the icu feature uses property data with broader Unicode coverage. The public API is identical for both backends; select the backend that matches your binary-size and Unicode-coverage needs.

Structs

Painter

Paint styled strings into a TextSurface.

SurfaceDisplay

A Display adapter over a Surface, returned by Encode::display and Encode::display_with.

Enums

WidthMode

How grapheme clusters are measured for terminal-cell layout.

WrapMode

Behavior when a cluster would extend past the right edge of the clip rectangle.

Traits

Encode

Serialize a Surface into escape sequences and text.

TextSurface

A SurfaceMut with a text-measurement policy and string-painting helpers.

Functions

char_width

Display width, in terminal cells, of a single code point.

grapheme_cells

Iterate s as (grapheme_cluster, width) pairs.

grapheme_width

Display width, in terminal cells, of one extended grapheme cluster.