Skip to main content

Crate cellwidth

Crate cellwidth 

Source
Expand description

Terminal display width that gets emoji, CJK and ANSI colour right.

"πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦".len() is 25. "πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦".chars().count() is 7. A terminal draws it in 2 columns. Every CLI table, progress bar, box border and status line needs that third number, and getting it wrong is why so much terminal output is subtly ragged.

use cellwidth::{width, cell, truncate};

assert_eq!(width("cafΓ©"), 4);            // combining accents don't count
assert_eq!(width("ζ—₯本θͺž"), 6);           // CJK is double-width
assert_eq!(width("πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦"), 2);              // one glyph, not seven
assert_eq!(width("\x1b[31mred\x1b[0m"), 3); // colour codes are free

// Cuts land on cluster boundaries, never mid-character.
assert_eq!(truncate("ζ—₯本θͺžγƒ†γ‚­γ‚Ήγƒˆ", 7), "ζ—₯本θͺž");

// And this is always exactly 10 columns wide, whatever you feed it.
assert_eq!(width(&cell("πŸ‡―πŸ‡΅ Tōkyō 東京", 10)), 10);

Β§What makes this correct

  • Widths come from the East Asian Width property of the Unicode Character Database, version UNICODE_VERSION, generated into plain sorted tables.
  • Text is segmented into extended grapheme clusters per UAX #29 – including emoji ZWJ sequences, regional indicator flags, skin tone modifiers and Indic conjuncts – so a β€œcharacter” means what a user thinks it means.
  • Variation selectors are honoured: ❀ is 1 column, ❀️ is 2.
  • ANSI escape sequences are parsed properly (CSI, OSC, DCS and the 8-bit C1 forms), counted as zero columns, and never cut in half.

Β§Choosing a policy

The free functions use Width::DEFAULT. Where the answer genuinely depends on the terminal – East Asian Ambiguous characters, tab stops, how old the emoji font is – build a Width instead:

use cellwidth::{Ambiguous, Width};

const CJK: Width = Width::DEFAULT.ambiguous(Ambiguous::Wide).tab_stop(4);
assert_eq!(CJK.of("Β°C"), 3);

Β§Coming from unicode-width or unicode-segmentation

The compat module has drop-in replacements for their traits, so a migration is an import change:

use cellwidth::compat::{UnicodeSegmentation, UnicodeWidthStr};

assert_eq!("πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦".width(), 2);
assert_eq!("πŸ‡―πŸ‡΅πŸ‡―πŸ‡΅".graphemes(true).count(), 2);

Β§No dependencies

None, and no build script: the Unicode tables are generated ahead of time by tools/gen_tables.py and committed. no_std is supported by disabling the std feature; measurement works with no allocator at all, and the alloc feature adds the functions that return owned strings.

ModulesΒ§

compat
Drop-in replacements for the traits of unicode-width and unicode-segmentation.

StructsΒ§

Graphemes
Iterator over the grapheme clusters of a string, yielded as subslices.
LineBreaks
Iterator over line break opportunities, as byte offsets into the string.
Pieces
Iterator splitting a string into text runs and escape sequences.
Table
A text table that lines up in a terminal.
Width
A measurement policy: how to turn text into a number of terminal columns.

EnumsΒ§

Align
Horizontal alignment within a column.
Ambiguous
How to count East Asian Ambiguous characters.
Border
The characters a table is drawn with.
Break
What kind of break opportunity this is.
Clusters
How much of a grapheme cluster counts towards the width.
Control
How to count C0/C1 control characters.
Piece
A run of the input that is either printable text or one escape sequence.
Sizing
How wide a column should be.

ConstantsΒ§

ELLIPSIS
The default ellipsis used by Width::cell: a single-column ….
UNICODE_VERSION
The Unicode version these tables were generated from.

FunctionsΒ§

cell
Fit s into exactly width columns, truncating with … or padding with spaces. The table-cell workhorse.
char_width
Columns a single char occupies, using Width::DEFAULT.
graphemes
Iterate the extended grapheme clusters of a string (UAX #29).
line_breaks
Iterate the places a line may be broken (UAX #14).
pad_end
Pad s with spaces on the right to at least width columns.
pad_start
Pad s with spaces on the left to at least width columns.
pieces
Split a string into printable text runs and escape sequences.
strip_ansi
Remove every escape sequence, leaving only printable text.
truncate
Longest prefix of s fitting in max columns, using Width::DEFAULT.
width
Columns a string occupies in a terminal, using Width::DEFAULT.
wrap
Break s into lines of at most width columns, at UAX #14 line break opportunities, using Width::DEFAULT.