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-widthandunicode-segmentation.
StructsΒ§
- Graphemes
- Iterator over the grapheme clusters of a string, yielded as subslices.
- Line
Breaks - 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
sinto exactlywidthcolumns, truncating withβ¦or padding with spaces. The table-cell workhorse. - char_
width - Columns a single
charoccupies, usingWidth::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
swith spaces on the right to at leastwidthcolumns. - pad_
start - Pad
swith spaces on the left to at leastwidthcolumns. - 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
sfitting inmaxcolumns, usingWidth::DEFAULT. - width
- Columns a string occupies in a terminal, using
Width::DEFAULT. - wrap
- Break
sinto lines of at mostwidthcolumns, at UAX #14 line break opportunities, usingWidth::DEFAULT.