Module cluster_map 

Bidirectional cluster↔cell mapping for shaped text.

This module defines the ClusterMap — a precomputed index that maps between source byte offsets, grapheme indices, and visual cell columns in both directions. It enables correct cursor movement, selection, copy extraction, and search highlighting over shaped text.

Invariants

The cluster map guarantees:

1. Round-trip preservation: byte → cell → byte returns the original cluster start (never a mid-cluster position).
2. Monotonicity: visual cell offsets increase with byte offsets.
3. Boundary alignment: lookups always snap to grapheme cluster boundaries — never splitting a grapheme or shaped glyph cluster.
4. Continuation cell handling: wide characters that span 2+ cells map back to the same source byte offset.
5. Completeness: every source byte offset and every visual cell column has a defined mapping.

Example

use ftui_text::cluster_map::ClusterMap;

// Build a cluster map from plain text
let map = ClusterMap::from_text("Hello 世界!");

// Forward: byte offset → visual cell column
assert_eq!(map.byte_to_cell(0), 0);  // 'H' at cell 0
assert_eq!(map.byte_to_cell(6), 6);  // '世' at cell 6
assert_eq!(map.byte_to_cell(9), 8);  // '界' at cell 8

// Reverse: visual cell column → byte offset
assert_eq!(map.cell_to_byte(0), 0);  // cell 0 → 'H'
assert_eq!(map.cell_to_byte(6), 6);  // cell 6 → '世'
assert_eq!(map.cell_to_byte(7), 6);  // cell 7 → '世' (continuation)

// Selection: cell range → byte range
let (start, end) = map.cell_range_to_byte_range(6, 10);
assert_eq!(start, 6);   // '世'
assert_eq!(end, 12);    // end of '界'

Structs

ClusterEntry

A single entry in the cluster map, representing one grapheme cluster.

ClusterMap

Bidirectional mapping between source byte offsets and visual cell columns.