cellwidth 1.0.1

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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
<p align="center">
  <a href="https://singhpratech.github.io/cellwidth/">
    <img src="docs/og.png" alt="cellwidth — terminal display width that gets emoji, CJK and ANSI colour right" width="820">
  </a>
</p>

# cellwidth

[![CI](https://github.com/singhpratech/cellwidth/actions/workflows/ci.yml/badge.svg)](https://github.com/singhpratech/cellwidth/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/cellwidth.svg)](https://crates.io/crates/cellwidth)
[![docs.rs](https://img.shields.io/docsrs/cellwidth)](https://docs.rs/cellwidth)
[![downloads](https://img.shields.io/crates/d/cellwidth.svg)](https://crates.io/crates/cellwidth)
[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://github.com/singhpratech/cellwidth/blob/main/Cargo.toml)
[![no_std](https://img.shields.io/badge/no__std-yes-brightgreen.svg)](https://github.com/singhpratech/cellwidth#feature-flags)
[![MSRV](https://img.shields.io/badge/MSRV-1.75-blue.svg)](https://github.com/singhpratech/cellwidth)
[![license](https://img.shields.io/crates/l/cellwidth.svg)](#license)

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

```rust
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

```sh
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:

```rust
// 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:

```rust
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:

```rust
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:

```rust
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:

```rust
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

```rust
use cellwidth::Width;

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

```
|              東京 deploy               |
```

### Counting what a user calls a character

```rust
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:

```rust
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:

```rust
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:

```sh
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

```rust
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

```sh
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.