Struct ClusterMap 

pub struct ClusterMap { /* private fields */ }

Bidirectional mapping between source byte offsets and visual cell columns.

Built from text (optionally with shaped glyph data) and provides O(log n) lookups in both directions via binary search over the sorted cluster array.

Construction

• from_text — build from plain text (uses grapheme cluster widths, suitable for terminal/monospace rendering).
• from_shaped_run — build from a shaped glyph run (uses glyph cluster byte offsets and advances, suitable for proportional/shaped rendering).

Implementations

impl ClusterMap

pub fn from_text(text: &str) -> Self

Build a cluster map from plain text using grapheme cluster boundaries.

Each grapheme cluster maps to 1 or 2 cells based on display_width. This is the appropriate constructor for terminal/monospace rendering.

pub fn from_shaped_run(text: &str, run: &ShapedRun) -> Self

Build a cluster map from a shaped glyph run.

Uses glyph cluster byte offsets from the ShapedRun to determine cluster boundaries, with advances determining cell widths.

For terminal rendering (NoopShaper), each glyph maps to one grapheme cluster. For proportional rendering, multiple glyphs may share a cluster (ligatures) or one glyph may span multiple characters.

pub fn byte_to_cell(&self, byte_offset: usize) -> usize

Map a byte offset to its visual cell column.

If the byte offset falls mid-cluster, it snaps to the cluster’s start cell. Returns total_cells for offsets at or past the end.

pub fn byte_to_entry(&self, byte_offset: usize) -> Option<&ClusterEntry>

Map a byte offset to the containing ClusterEntry.

Returns None for empty maps or offsets past the end.

pub fn byte_range_to_cell_range( &self, byte_start: usize, byte_end: usize, ) -> (usize, usize)

Map a byte range to a visual cell range.

Returns (cell_start, cell_end) covering all clusters that overlap the given byte range.

pub fn cell_to_byte(&self, cell_col: usize) -> usize

Map a visual cell column to a source byte offset.

Continuation cells (cells within a wide character) map back to the cluster’s start byte. Returns total_bytes for cells at or past the total width.

pub fn cell_to_entry(&self, cell_col: usize) -> Option<&ClusterEntry>

Map a visual cell column to the containing ClusterEntry.

Returns None for empty maps or cells past the total width.

pub fn cell_range_to_byte_range( &self, cell_start: usize, cell_end: usize, ) -> (usize, usize)

Map a visual cell range to a source byte range.

Returns (byte_start, byte_end) covering all clusters that overlap the given cell range. Continuation cells are resolved to their owning cluster.

pub fn grapheme_to_cell(&self, grapheme_index: usize) -> usize

Map a grapheme index to a visual cell column.

pub fn cell_to_grapheme(&self, cell_col: usize) -> usize

Map a visual cell column to a grapheme index.

pub fn grapheme_to_byte(&self, grapheme_index: usize) -> usize

Map a grapheme index to a byte offset.

pub fn byte_to_grapheme(&self, byte_offset: usize) -> usize

Map a byte offset to a grapheme index.

pub fn total_cells(&self) -> usize

Total visual width in cells.

pub fn total_bytes(&self) -> usize

Total byte length of the source text.

pub fn cluster_count(&self) -> usize

Number of grapheme clusters.

pub fn is_empty(&self) -> bool

Whether the map is empty.

pub fn entries(&self) -> &[ClusterEntry]

Iterate over all cluster entries.

pub fn get(&self, grapheme_index: usize) -> Option<&ClusterEntry>

Get the cluster entry at a grapheme index.

pub fn extract_text_for_cells<'a>( &self, source: &'a str, cell_start: usize, cell_end: usize, ) -> &'a str

Extract text from the source string for a cell range.

Returns the substring covering all clusters that overlap the given visual cell range.

Trait Implementations

impl Clone for ClusterMap

fn clone(&self) -> ClusterMap

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClusterMap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.