cellwidth 1.0.0

Terminal display width that gets emoji, CJK and ANSI colour right. Measure, truncate, pad and wrap text so columns actually line up. No dependencies, no_std.
Documentation
  • Coverage
  • 100%
    59 out of 59 items documented11 out of 25 items with examples
  • Size
  • Source code size: 1.8 MB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 3.9 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 3s Average build duration of successful builds.
  • all releases: 3s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • singhpratech/cellwidth
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • singhpratech

cellwidth

CI crates.io docs.rs downloads dependencies no_std MSRV license

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

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

assert_eq!(truncate("日本語テキスト", 7), "日本語");  // never splits a character
assert_eq!(width(&cell("🇯🇵 Tōkyō 東京", 10)), 10);  // exactly 10 columns. always.

No dependencies. No build script. no_std. MSRV 1.75.

The problem

"👨‍👩‍👧‍👦".len() is 25. "👨‍👩‍👧‍👦".chars().count() is 7. A terminal draws it in 2 columns.

Every CLI table, progress bar, box border, status line and log formatter needs that third number. Reach for len() or chars().count() and your output goes ragged the first time a user has an umlaut in their name, a Japanese hostname, or an emoji in a commit message — and it stays broken, because the failure only shows up on other people's data.

$ cargo run --example table
┌────────────────────┬────────────────────────┬────────────┐
│ host               │ label                  │ status     │
├────────────────────┼────────────────────────┼────────────┤
│ nagoya-prod-01     │ 日本語ログ出力         │ healthy    │
│ crew-alpha         │ 👨‍👩‍👧‍👦 shared account      │ healthy    │
│ tokyo-cdn          │ 🇯🇵 Tōkyō 東京 edge     │ offline    │
│ long-name-that-wi… │ café au lait           │ degraded   │
└────────────────────┴────────────────────────┴────────────┘

What it does

width(s) columns s occupies
truncate(s, n) longest prefix fitting n columns — borrowed, no allocation
cell(s, n) exactly n columns: truncate with … or pad with spaces
pad_start / pad_end / center align to a column count
wrap(s, n) break into lines of at most n columns, at UAX #14 opportunities
line_breaks(s) where a line may be broken (UAX #14)
Table a grid that lines up: sizing, alignment, borders, wrapping cells
graphemes(s) iterate user-perceived characters (UAX #29)
strip_ansi(s) / pieces(s) separate text from escape sequences
compat::* drop-in traits for code written against unicode-width or unicode-segmentation

Every operation works in whole grapheme clusters and whole escape sequences, so a cut never produces half a character or half a colour code.

Install

cargo add cellwidth

That is the whole dependency graph. cargo tree prints one node.

Without this crate, the same job usually takes four: unicode-width for widths, unicode-segmentation for clusters, strip-ansi-escapes for colour, textwrap for wrapping — plus the glue between them, which is where the bugs live, because width and segmentation are different questions and those two crates do not talk to each other.

Migrating from unicode-width or unicode-segmentation

The compat module has traits with the same names and method signatures as theirs, so switching is an import change:

// use unicode_width::UnicodeWidthStr;
// use unicode_segmentation::UnicodeSegmentation;
use cellwidth::compat::{UnicodeSegmentation, UnicodeWidthStr};

assert_eq!("日本語".width(), 6);
assert_eq!("°C".width_cjk(), 3);
assert_eq!("a👍🏽🇯🇵".graphemes(true).count(), 3);

The method names are the same; the answers are cellwidth's. Every figure below is measured by oracles/tests/differential.rs, which fails if either crate changes:

input unicode-width 0.2.2 cellwidth why
"\x1b[31mred\x1b[0m" 12 3 escape sequences occupy no columns
"क्षि" 3 1 an Indic conjunct is one glyph
"a\tb" 3 9 a tab advances to the next stop
"👨‍👩‍👧‍👦" 2 2 both handle ZWJ sequences

UnicodeWidthChar keeps unicode-width's convention of None for control characters — the two crates return None for exactly the same set — and UnicodeSegmentation::graphemes(s, false) implements legacy grapheme clusters (no GB9a/GB9b/GB9c), checked against unicode-segmentation on 9,282,875 strings in both modes. Word and sentence segmentation are not provided.

Use cases

Every output below is copied from a real run, not typed by hand.

Columns that line up

The original problem. A width-aware Table keeps every row the same number of cells no matter what the data holds:

use cellwidth::{Align, Border, Sizing, Table};

let out = Table::new()
    .column("host")
    .column_with("label", Align::Left, Sizing::Max(22))
    .column_aligned("rps", Align::Right)
    .row(["tokyo-cdn", "🇯🇵 Tōkyō 東京 edge", "17,900"])
    .row(["crew-alpha", "👨‍👩‍👧‍👦 shared account", "3"])
    .border(Border::Ascii)
    .render(Some(60));
+------------+--------------------+--------+
| host       | label              |    rps |
+------------+--------------------+--------+
| tokyo-cdn  | 🇯🇵 Tōkyō 東京 edge | 17,900 |
| crew-alpha | 👨‍👩‍👧‍👦 shared account  |      3 |
+------------+--------------------+--------+

A flag, a ZWJ family, CJK and a macron in the same column — and all six lines measure 44 columns exactly. That invariant is what the fuzzer asserts.

Status lines and progress bars that don't smear

Redrawing with \r only works if every frame is the same width. One frame narrower than the last and the tail of the previous frame stays on screen. cell guarantees the width:

use cellwidth::cell;

for (name, pct) in [("building 日本語", 40), ("linking 👨‍👩‍👧‍👦", 95)] {
    print!("\r{} {pct:>3}%", cell(name, 20));
}
|building 日本語     |  40%
|linking 👨‍👩‍👧‍👦          |  95%

Both left fields are 20 columns, though one is 14 chars and the other 8.

Truncating a coloured log line

truncate counts only what is drawn, and never cuts inside an escape sequence or a character:

use cellwidth::truncate;

let line = "\x1b[33mWARN\x1b[0m 東京 node unreachable";
assert_eq!(truncate(line, 12), "\x1b[33mWARN\x1b[0m 東京 no");

The colour codes cost 0 columns, 東京 costs 4, and the result is 12 visible columns — it will not split 京 in half or strand a half-written \x1b[.

Wrapping messages to the terminal

wrap breaks at real UAX #14 opportunities, so it works in scripts that have no spaces at all:

use cellwidth::wrap;

let msg = "認証に失敗しました: the token for 👨‍👩‍👧‍👦 crew-alpha expired";
for line in wrap(msg, 28) {
    println!("{line}");
}
認証に失敗しました: the
token for 👨‍👩‍👧‍👦 crew-alpha
expired

The Japanese clause breaks between characters (no spaces exist to break on), the English breaks at spaces, and the emoji family is never split.

Centring a banner

use cellwidth::Width;

let banner = Width::DEFAULT.center(" 東京 deploy ", 40);
|              東京 deploy               |

Counting what a user calls a character

use cellwidth::graphemes;

let g: Vec<&str> = graphemes("👨‍👩‍👧‍👦é日").collect();
assert_eq!(g.len(), 3);   // not 8 chars, not 18 bytes

Useful for cursor movement, backspace handling and character limits in a text input, where deleting one char would dismantle an emoji into its parts.

Where this shows up

Anything that draws a fixed grid into a terminal: CLI tables and reports, TUI list and column views, progress bars and spinners, log formatters and column-aligned output, box-drawn banners, help and error text wrapped to $COLUMNS, and text inputs that need cursor and delete to move by characters rather than bytes.

no_std means it also works in a serial console or an embedded shell with no allocator, where width, truncate, graphemes and pieces still function.

Why the numbers are right

  • Widths come from the East Asian Width property of the Unicode Character Database 17.0.0, generated into a two-level lookup table.
  • Segmentation implements UAX #29 extended grapheme clusters, and passes all 766 cases of the official GraphemeBreakTest.txt — including emoji ZWJ sequences, regional-indicator flags, skin tone modifiers, Hangul syllables and Indic conjuncts (GB9c).
  • Variation selectors are honoured: ❤ is 1 column, ❤️ is 2.
  • Escape sequences are parsed as sequences (CSI, OSC, DCS, the nF forms and the 8-bit C1 equivalents), not pattern-matched. OSC 8 hyperlinks measure their label, not their URL.
  • Line breaking implements UAX #14 and passes all 19,338 cases of Unicode's LineBreakTest.txt.
  • Every code point was diffed against glibc's wcwidth. The 178 remaining disagreements are deliberate and pinned in tests/width.rs.
  • Segmentation is checked against unicode-segmentation across 9,282,875 generated strings, in both extended and legacy cluster modes, with exact agreement, and widths against unicode-width across all 1,112,064 code points, where every divergence is sorted into a bucket with a written reason.
  • 33.7 million fuzz executions across six targets, no crashes.

Eight real defects were found this way, none of them by re-reading the code. Each has a regression test naming the oracle that caught it.

Policy, where there is no single right answer

Some questions genuinely cannot be answered from the text alone. Those are configuration, not guesswork:

use cellwidth::{Ambiguous, Control, Width};

const CJK: Width = Width::DEFAULT
    .ambiguous(Ambiguous::Wide)   // ± ° § are 2 columns in CJK fonts
    .tab_stop(4)
    .control(Control::Caret);     // count control chars as ^C

assert_eq!(Width::DEFAULT.of("±"), 1);
assert_eq!(CJK.of("±"), 2);

The free functions use Width::DEFAULT, which is right for a Western locale on a modern terminal.

Which terminal are you targeting?

Terminals genuinely disagree about emoji and combining marks, so this was measured rather than guessed. probe/ prints a string into a live terminal, asks where the cursor ended up with CSI 6n, and writes down the answer. Four terminals, 32 cases, recorded in tests/data/terminals/:

ZWJ family 👨‍👩‍👧‍👦 ❤ + VS16 skin tone Bengali কা
kitty 0.48 2 2 2 1
WezTerm 20240203 2 1 2 1
VTE 0.76 (GNOME Terminal, Tilix, Terminator) 8 1 4 2
Alacritty 0.17 8 1 4 1

They fall into two camps, so there are two presets:

Width::DEFAULT   // == Width::MODERN. Every grapheme cluster is one glyph.
Width::LEGACY    // Every code point counts on its own, as wcwidth does.

Width::DEFAULT reproduces kitty exactly, on all 32 cases. Width::LEGACY scores higher across the four terminals as a group (99/128 against 94/128), because two of the four are in that camp — if you know your users are on GNOME Terminal or Alacritty, use it.

Everyday text measures the same under both. The choice only matters for emoji sequences and combining marks.

If you want the terminal to answer for itself, cargo run -p cellwidth-probe --bin detect does the same query at runtime and names the preset to use; it is about forty lines you can copy into your own startup path.

Reproduce the whole matrix with probe/drivers/run_all.sh. Terminals run headlessly under Xvfb, so it works over ssh.

Performance

One table lookup per code point; no allocation on the measuring path. Measured head-to-head against the incumbent crates, best of seven rounds of 100,000 calls, on the same inputs (cargo run --release --manifest-path oracles/Cargo.toml --example bench):

input bytes cellwidth::width Width::LEGACY unicode-width answers
ascii 69 49 ns 46 ns 54 ns 69 / 69 / 69
cjk 114 413 ns 118 ns 85 ns 76 / 76 / 76
emoji 126 644 ns 131 ns 132 ns 77 / 84 / 77
ansi 80 129 ns 129 ns 62 ns 42 / 42 / 80
table row 64 263 ns 84 ns 59 ns 38 / 40 / 47

Read the answers column before the timings. unicode-width does not segment into clusters and does not parse escape sequences, so on emoji and ANSI input it does strictly less work and returns a number a terminal will not honour. Width::LEGACY is the like-for-like per-code-point model, and runs at the same speed. The default cluster-aware model costs 3–5× on non-ASCII text; that is the price of the right answer, and it is still sub-microsecond for a table row.

Grapheme iteration is about twice as fast as unicode-segmentation:

input clusters cellwidth::graphemes unicode-segmentation
ascii 69 382 ns 698 ns
cjk 38 233 ns 519 ns
emoji 68 466 ns 943 ns
ansi 80 477 ns 833 ns
table row 41 247 ns 472 ns

Limitations, honestly

  • Terminals disagree with each other. Where they do, this crate follows the current UCD and the most common modern rendering. Width exists so you can choose differently.
  • Complex Indic and Arabic shaping is measured per spacing character. A terminal that shapes क्षि into fewer cells will disagree; there is no property in Unicode that predicts this.
  • Tabs make width position-dependent. width assumes column 0; use Width::of_at when a string starts somewhere else. A table cell cannot know where it will be drawn, so Table expands tabs to spaces.

Feature flags

Feature Default Effect
std yes implies alloc
alloc via std cell, pad_*, wrap, strip_ansi and the other owned-string APIs

With neither, width, truncate, graphemes and pieces still work with no allocator at all.

Regenerating the Unicode tables

src/tables.rs is generated and committed, which is why there is no build script and no dependency on a Unicode crate. To move to a new Unicode release:

mkdir ucd && cd ucd
base=https://www.unicode.org/Public/UCD/latest/ucd
curl -O $base/EastAsianWidth.txt -O $base/UnicodeData.txt \
     -O $base/DerivedCoreProperties.txt \
     -O $base/auxiliary/GraphemeBreakProperty.txt \
     -O $base/emoji/emoji-data.txt
curl -o ../tests/data/GraphemeBreakTest.txt $base/auxiliary/GraphemeBreakTest.txt
cd .. && python3 tools/gen_tables.py ucd > src/tables.rs && cargo test

Tables

use cellwidth::{Align, Border, Sizing, Table};

let out = Table::new()
    .column("host")
    .column_with("label", Align::Left, Sizing::Max(22))
    .column_aligned("rps", Align::Right)
    .row(["tokyo-cdn", "🇯🇵 Tōkyō 東京 edge", "17,900"])
    .row(["crew-alpha", "👨‍👩‍👧‍👦 shared account", "3"])
    .border(Border::Ascii)
    .render(Some(60));   // squeezed to 60 columns: cells wrap, nothing is lost

Column sizing is Auto, Fixed(n) or Max(n); borders are Light, Heavy, Ascii, Markdown or None. Every line of the output is the same number of terminal columns wide — that is what the fuzzer checks, whatever the cells hold.

Testing

cargo test                                     # the crate's own suite, offline
cargo test --manifest-path oracles/Cargo.toml  # differential vs other crates
cargo run --release --manifest-path oracles/Cargo.toml --example bench  # head-to-head
cargo +nightly miri test -p cellwidth          # 50 tests under the interpreter
cargo llvm-cov -p cellwidth --all-features \
  --ignore-filename-regex 'tables\.rs' --fail-under-lines 100
cd fuzz && cargo +nightly fuzz run cell
Tests 101 standalone, 107 with oracles
Conformance 766 UAX #29 + 19,338 UAX #14 + 3,944 emoji sequences
Line coverage 100% (1,239 / 1,239), gated in CI
Function coverage 100% (110 / 110), gated in CI
Region coverage 99.95% — a merge artifact, see CONTRIBUTING
Fuzzing 6 targets, 0 crashes
Miri clean

The oracle crates live in a separate package (oracles/) so this crate has no dependencies and no dev-dependencies. cargo tree --edges normal,dev lists nothing but cellwidth, its Cargo.lock contains exactly one entry, and CI runs cargo test --offline --locked to keep that true.

CI runs thirteen jobs on every push: the suite on stable, beta and nightly; all three feature combinations; a bare-metal thumbv7em-none-eabi build to prove no_std; MSRV 1.75; the differential oracles; fmt, clippy and rustdoc with warnings denied; Miri; coverage gated at 100% lines; a 60-second fuzz smoke run per target; cargo-semver-checks against the base branch; and a publish dry run. A weekly job fails when Unicode publishes a version newer than the tables.

License

MIT or Apache-2.0, at your option.