console-table 0.1.4

Console table rendering with Unicode/CJK-aware alignment, truncation, and ANSI color support
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
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
# console-table


[![Crates.io](https://img.shields.io/crates/v/console-table.svg)](https://crates.io/crates/console-table)
[![Docs.rs](https://docs.rs/console-table/badge.svg)](https://docs.rs/console-table)
[![License](https://img.shields.io/crates/l/console-table.svg)](#license)

A small, dependency-light Rust library for rendering aligned console tables.

It is Unicode-aware (CJK characters count as 2 columns), handles
ambiguous-width characters like `Φ` predictably, supports optional per-cell
truncation, ANSI foreground colors, and two border styles.

---

## Table of contents


- [Features]#features
- [Installation]#installation
- [Quick start]#quick-start
- [Ambiguous-width characters]#ambiguous-width-characters
- [Before and after]#before-and-after
- [API overview]#api-overview
- [Design notes]#design-notes
- [Windows note]#windows-note
- [FAQ]#faq
- [License]#license

---

## Features


- **Unicode / CJK-aware alignment** — uses [`unicode-width`] so that Chinese,
  Japanese, Korean, fullwidth, and zero-width characters are measured by their
  real terminal display width, not by `char` count.
- **Predictable ambiguous-width handling** — characters like `Φ`, `±`, `Ⅱ`, `①`
  have Unicode `East_Asian_Width=Ambiguous` and render as 1 or 2 columns
  depending on the terminal. By default they are counted as **2 columns**,
  which matches CJK terminals. See
  [Ambiguous-width characters]#ambiguous-width-characters to override.
- **Two border styles** — `Style::Simple` (header separator only) and
  `Style::Boxed` (full box drawing).
- **Per-column alignment** — `Align::Left`, `Align::Right`, or `Align::Auto`
  (numbers right-aligned, everything else left-aligned).
- **Truncation** — cap any data cell at `max_cell_width`; overflow becomes
  ASCII `...`. Headers are never truncated.
- **ANSI colors** — optional `header_color` and `body_color` from a small
  built-in palette.
- **ANSI-safe width math** — existing ANSI sequences inside cell text are
  stripped before width is measured, so colored input does not break layout.
- **Only one dependency** — `unicode-width`.

[`unicode-width`]: https://crates.io/crates/unicode-width

---

## Installation


Add this to your `Cargo.toml`:

```toml
[dependencies]
console-table = "0.2"
Quick start
rust
use console_table::{Align, Color, Style, Table};

fn main() {
    let rows = vec![
        vec!["#".into(), "source".into(), "latency".into()],
        vec!["1".into(), "rsproxy (ByteDance)".into(), "57 ms".into()],
        vec!["2".into(), "tuna (Tsinghua)".into(), "16 ms".into()],
        vec!["8".into(), "cqu (Chongqing)".into(), "failed".into()],
    ];

    let table = Table::new(rows)
        .style(Style::Boxed)
        .aligns(vec![Align::Right, Align::Left, Align::Auto])
        .max_cell_width(40)
        .header_color(Color::BrightCyan)
        .body_color(Color::White);

    println!("{}", table.render());
}
Output (colors not shown):

text
┌──────┬─────────────────────┬──────────┐
│ #    │ source              │ latency  │
├──────┼─────────────────────┼──────────┤
│    1 │ rsproxy (ByteDance) │   57 ms  │
│    2 │ tuna (Tsinghua)     │   16 ms  │
│    8 │ cqu (Chongqing)     │ failed   │
└──────┴─────────────────────┴──────────┘
Ambiguous-width characters
Some characters have Unicode East_Asian_Width=Ambiguous. The most common one
in engineering data is Φ (U+03A6, Greek capital Phi), but the category also
includes ±, ×, ÷, ≤, Ⅱ, ① and others.

There is no single correct width for these characters. Terminals render
them as either 1 or 2 columns, depending on the terminal software, the font,
and user settings — not on the operating system language. For example:

Terminal	Φ renders as
Traditional CJK console (e.g. Windows cmd.exe with a CJK font)	2 columns
Windows Terminal (default narrow)	1 column
Windows Terminal (wide setting)	2 columns
VS Code integrated terminal	1 column
iTerm2 on macOS	1 column
Because this crate targets CJK output by default, ambiguous characters are
counted as 2 columns by default (AmbiguousWidth::Wide). This is a fixed
default, not a guess. If your terminal renders Φ as 1 column, override it:

rust
use console_table::{AmbiguousWidth, Table};

// Your terminal renders Φ as 1 column:
let table = Table::new(rows).cjk_context(false);
// equivalently:
let table = Table::new(rows).ambiguous_width(AmbiguousWidth::Narrow);
The three modes
Mode	Φ counted as	When to use
AmbiguousWidth::Wide (default)	2 columns	CJK terminals, Windows cmd.exe with a CJK font, most Chinese/Japanese/Korean consoles
AmbiguousWidth::Narrow	1 column	Western terminals, Windows Terminal default, VS Code, iTerm2
AmbiguousWidth::Auto	guessed from LANG/LC_ALL/LC_CTYPE	You want locale-based guessing; not reliable, see below
Why Auto is not the default
Auto inspects LANG, LC_ALL, and LC_CTYPE for a CJK locale prefix
(zh, ja, ko). But the environment locale does not determine how the
terminal renders ambiguous characters. A common case:

LANG=en_US.UTF-8 (English environment), but the terminal still renders Φ
as 2 columns because the user is on a CJK console with a CJK font.

In this case Auto guesses Narrow (1 column) and the table misaligns,
while the fixed default Wide (2 columns) stays aligned.

Because Auto can silently produce wrong output, the default is Wide.
If you have verified that Auto matches your deployment, opt in explicitly:

rust
use console_table::{AmbiguousWidth, Table};

let table = Table::new(rows).ambiguous_width(AmbiguousWidth::Auto);
If you don't know which mode your terminal needs
Render a small table with Φ under both modes and see which one aligns:

rust
use console_table::{Style, Table};

let rows = vec![
    vec!["名称".into(), "规格".into(), "材料".into()],
    vec!["电杆".into(), "Φ170".into(), "".into()],
    vec!["横担".into(), "03D103-133".into(), "2II2".into()],
];

println!("--- Wide ---");
println!(
    "{}",
    Table::new(rows.clone()).style(Style::Boxed).cjk_context(true).render()
);

println!("--- Narrow ---");
println!(
    "{}",
    Table::new(rows).style(Style::Boxed).cjk_context(false).render()
);
Whichever section has all │ aligned is the mode your terminal needs.

Compile-time note
The free functions display_width and truncate_visible use the same default
(Wide). If you need an explicit mode outside of Table, use the _with
variants:

rust
use console_table::{display_width, truncate_visible};

display_width("Φ170");                    // 5  (Φ = 2)
truncate_visible("Φ170CD1XYZ", 6);        // "Φ1..."  (Φ = 2)
For an explicit mode, the _with functions take the ambiguous width directly:

rust
use console_table::{display_width_with, truncate_visible_with};

display_width_with("Φ170", 1);            // 4  (Φ = 1, Narrow)
truncate_visible_with("Φ170CD1XYZ", 6, 1); // "Φ17..."
Note: display_width_with and truncate_visible_with are public but
lower-level. Most callers should prefer the Table builder.

Before and after
The same CJK data, rendered three ways. The first two use plain format! and
break or bloat on Chinese text; the third uses console-table and stays
aligned with almost no boilerplate.

The runnable version of all three is in
examples/compare.rs.

rust
let headers = ["序号", "镜像源", "平均延迟", "可用", "serde最新版"];
let data = [
    ["1", "rsproxy (字节跳动)", "57 ms", "是", "1.0.229"],
    ["2", "tuna (清华)", "16 ms", "是", "1.0.229"],
    ["8", "cqu (重大)", "失败", "否", "-"],
];
Before — manual format!
The common first attempt. {:<20} pads by char count, so Chinese characters
(which occupy 2 terminal columns each) collapse the columns.

rust
fn manual_align(headers: &[&str; 5], data: &[[&str; 5]; 3]) {
    println!(
        "{:<4} {:<20} {:<10} {:<6} {:<12}",
        headers[0], headers[1], headers[2], headers[3], headers[4]
    );
    println!("{}", "-".repeat(60));
    for row in data {
        println!(
            "{:<4} {:<20} {:<10} {:<6} {:<12}",
            row[0], row[1], row[2], row[3], row[4]
        );
    }
}
Output:

text
序号 镜像源               平均延迟   可用 serde最新版
------------------------------------------------------------
1    rsproxy (字节跳动)   57 ms      是   1.0.229
2    tuna (清华)          16 ms      是   1.0.229
8    cqu (重大)           失败       否   -
Columns drift because "镜像源" is 3 chars but 6 columns wide.

Before — manual width handling
To fix it by hand, you need your own display-width function, a fixed width
table, and manual padding. It works, but it is a lot of boilerplate, and every
new column means editing several places.

rust
fn display_width(s: &str) -> usize {
    s.chars()
        .map(|c| {
            let cp = c as u32;
            if (0x1100..=0x115F).contains(&cp)
                || (0x2E80..=0xA4CF).contains(&cp)
                || (0xAC00..=0xD7A3).contains(&cp)
                || (0xF900..=0xFAFF).contains(&cp)
                || (0xFE30..=0xFE4F).contains(&cp)
                || (0xFF00..=0xFF60).contains(&cp)
                || (0xFFE0..=0xFFE6).contains(&cp)
            {
                2
            } else {
                1
            }
        })
        .sum()
}

fn manual_align_cjk_aware(headers: &[&str; 5], data: &[[&str; 5]; 3]) {
    let widths = [4usize, 22, 12, 8, 14];

    let fmt_row = |cells: &[&str]| {
        let mut out = String::new();
        for (i, cell) in cells.iter().enumerate() {
            let w = display_width(cell);
            out.push_str(cell);
            if w < widths[i] {
                out.push_str(&" ".repeat(widths[i] - w));
            }
            out.push_str("  ");
        }
        out
    };

    println!("{}", fmt_row(headers));
    println!("{}", "-".repeat(70));
    for row in data {
        println!("{}", fmt_row(row));
    }
}
Output:

text
序号    镜像源                    平均延迟      可用    serde最新版
----------------------------------------------------------------------
1       rsproxy (字节跳动)        57 ms         是      1.0.229
2       tuna (清华)               16 ms         是      1.0.229
8       cqu (重大)                失败          否      -
Aligned, but no borders, no per-column alignment, no truncation, no colors.

After — console-table
rust
use console_table::{Align, Color, Style, Table};

let rows = vec![
    vec!["序号".into(), "镜像源".into(), "平均延迟".into(), "可用".into(), "serde最新版".into()],
    vec!["1".into(), "rsproxy (字节跳动)".into(), "57 ms".into(), "是".into(), "1.0.229".into()],
    vec!["2".into(), "tuna (清华)".into(), "16 ms".into(), "是".into(), "1.0.229".into()],
    vec!["8".into(), "cqu (重大)".into(), "失败".into(), "否".into(), "-".into()],
];

let table = Table::new(rows)
    .style(Style::Boxed)
    .aligns(vec![
        Align::Right, // 序号
        Align::Left,  // 镜像源
        Align::Auto,  // 平均延迟:数字右对齐,"失败" 左对齐
        Align::Left,  // 可用
        Align::Left,  // serde最新版
    ])
    .header_color(Color::BrightCyan)
    .body_color(Color::White);

println!("{}", table.render());
Output:

text
┌──────┬────────────────────┬──────────┬──────┬─────────────┐
│ 序号 │ 镜像源             │ 平均延迟 │ 可用 │ serde最新版 │
├──────┼────────────────────┼──────────┼──────┼─────────────┤
│    1 │ rsproxy (字节跳动) │   57 ms  │ 是   │ 1.0.229     │
│    2 │ tuna (清华)        │   16 ms  │ 是   │ 1.0.229     │
│    8 │ cqu (重大)         │ 失败     │ 否   │ -           │
└──────┴────────────────────┴──────────┴──────┴─────────────┘
After — with truncation
Long values are capped at max_cell_width and end with ASCII ....
Truncation never breaks alignment.

rust
let mut rows_with_url = rows.clone();
rows_with_url[0].push("地址".to_string());
let urls = [
    "sparse+https://rsproxy.cn/index/",
    "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/",
    "sparse+https://mirrors.cqu.edu.cn/crates.io-index/",
];
for (i, url) in urls.iter().enumerate() {
    rows_with_url[i + 1].push((*url).to_string());
}

let table = Table::new(rows_with_url)
    .style(Style::Boxed)
    .aligns(vec![
        Align::Right, Align::Left, Align::Auto,
        Align::Left, Align::Left, Align::Left,
    ])
    .max_cell_width(40)
    .header_color(Color::BrightCyan)
    .body_color(Color::White);

println!("{}", table.render());
Output:

text
┌──────┬────────────────────┬──────────┬──────┬─────────────┬──────────────────────────────────────────┐
│ 序号 │ 镜像源             │ 平均延迟 │ 可用 │ serde最新版 │ 地址                                     │
├──────┼────────────────────┼──────────┼──────┼─────────────┼──────────────────────────────────────────┤
│    1 │ rsproxy (字节跳动) │   57 ms  │ 是   │ 1.0.229     │ sparse+https://rsproxy.cn/index/         │
│    2 │ tuna (清华)        │   16 ms  │ 是   │ 1.0.229     │ sparse+https://mirrors.tuna.tsinghua.edu… │
│    8 │ cqu (重大)         │ 失败     │ 否   │ -           │ sparse+https://mirrors.cqu.edu.cn/crates… │
└──────┴────────────────────┴──────────┴──────┴─────────────┴──────────────────────────────────────────┘
Summary
manual format!	manual width fn	console-table
CJK-aware width	✗	✓	✓
Ambiguous-width handling	✗	✗	✓
Column widths auto-computed	✗	✗	✓
Borders	✗	✗	✓
Per-column alignment	✗	✗	✓
Truncation	✗	✗	✓
Colors	✗	✗	✓
Lines of code	~6	~30	~10
API overview
Table
Method	Description
Table::new(rows)	Create a table. The first row is treated as the header. Rows may have different lengths; missing cells are treated as empty.
.style(Style)	Style::Simple (default) or Style::Boxed.
.aligns(Vec<Align>)	Per-column alignment. Missing columns default to Align::Left.
.max_cell_width(usize)	Truncate data cells to at most this display width. Headers are not truncated.
.header_color(Color)	Foreground color for the header row.
.body_color(Color)	Foreground color for data rows.
.ambiguous_width(AmbiguousWidth)	How to count ambiguous-width characters. Default Wide.
.cjk_context(bool)	Shorthand for .ambiguous_width(Wide) / .ambiguous_width(Narrow).
.render() -> String	Render the table. Every line ends with \n.
AmbiguousWidth
Variant	Φ counted as	Description
Wide (default)	2 columns	Matches CJK terminals.
Narrow	1 column	Matches Western terminals.
Auto	guessed	Guesses from LANG/LC_ALL/LC_CTYPE. Not reliable; opt in only if you have verified it.
Style
Variant	Description
Simple	Header row, a single separator, then data rows.
Boxed	Full box drawing with top, header separator, row separators, and bottom border.
Align
Variant	Description
Left	Left align.
Right	Right align.
Auto	Right align if the first whitespace-separated token parses as f64, otherwise left align.
Color
16 ANSI foreground colors:

Black, Red, Green, Yellow, Blue, Magenta, Cyan, White

BrightBlack, BrightRed, BrightGreen, BrightYellow,
BrightBlue, BrightMagenta, BrightCyan, BrightWhite

Free functions
Function	Description
render_table(rows, style)	Convenience: Table::new(rows).style(style).render().
display_width(&str) -> usize	Terminal display width, ignoring ANSI sequences. Uses the default Wide mode.
display_width_with(&str, aw: usize)	Same, with explicit ambiguous width (1 or 2).
truncate_visible(&str, usize) -> String	Truncate to a display width, appending ASCII .... Uses the default Wide mode.
truncate_visible_with(&str, usize, aw: usize)	Same, with explicit ambiguous width (1 or 2).
strip_ansi(&str) -> String	Remove CSI-style ANSI escape sequences.
pad_right_with_spaces(&str, usize)	Pad on the right by display width.
pad_left_with_spaces(&str, usize)	Pad on the left by display width.
is_numeric_like(&str) -> bool	Heuristic used by Align::Auto.
Design notes
Widths are measured, not assumed. Every column is
max(display_width of all cells in that column, including the header) + 2,
where +2 reserves one space of padding on each side.

Ambiguous characters default to 2 columns. Φ, ±, Ⅱ, ① and
similar characters are counted as 2 by default, matching CJK terminals.
Override with .cjk_context(false) if your terminal renders them as 1.
See Ambiguous-width characters.

... instead of …. The single-character ellipsis … (U+2026) renders
as 1 or 2 columns depending on the terminal and font, which breaks alignment.
The ASCII ... is always exactly 3 columns.

Colors are applied at render time. Width computation strips ANSI
sequences, so colored cells never widen a column.

Existing ANSI in cell text is stripped. If a cell already contains color
codes, they are removed and replaced by body_color (or no color). Do not mix
per-cell colors with body_color.

Every rendered line has equal display width. This includes the header,
separators, and data rows, so the table stays rectangular even when the
terminal renders wide characters at 2 columns.

Windows note
Older cmd.exe consoles may not interpret ANSI escape sequences. Use
Windows Terminal or enable virtual terminal
processing in the console.

When redirecting output to a file, prefer disabling colors yourself:

rust
use std::io::IsTerminal;

let table = Table::new(rows);
let table = if std::io::stdout().is_terminal() {
    table.header_color(Color::BrightCyan).body_color(Color::White)
} else {
    table
};
This keeps the redirected file free of \x1b[...m sequences.

Windows Terminal and Φ. Windows Terminal defaults to narrow for
ambiguous-width characters (one column). If you are rendering into Windows
Terminal, you may want .cjk_context(false). If you are rendering into
classic cmd.exe with a CJK font, keep the default Wide. See
Ambiguous-width characters.

FAQ
Why does my CJK table look misaligned in some terminals?

Two common causes:

Ambiguous-width characters. Φ, ±, Ⅱ, ① and similar are 1 or 2
columns depending on the terminal. The default is 2 (Wide). If your
terminal renders them as 1, call .cjk_context(false). See
Ambiguous-width characters.

Font mismatch. Some terminals and fonts render … (U+2026) as 2
columns, and a few render it as 1. This library uses ASCII ... for
truncation so the width is always 3.

If you still see misalignment, check that your terminal uses a font where
CJK characters are exactly twice the width of ASCII characters, and that
.cjk_context(...) matches your terminal.

Why is Auto not the default?

Because environment locale does not determine how the terminal renders
ambiguous characters. A machine can have LANG=en_US.UTF-8 and still render
Φ as 2 columns (CJK console with a CJK font). Auto would guess Narrow
and misalign, while the fixed default Wide stays correct. Auto is opt-in
for deployments that have verified it works.

Can I color individual cells?

Not directly. body_color applies to the whole data row, and any ANSI codes
inside a cell are stripped before rendering. If you need per-cell colors,
render the row yourself or use a lower-level API.

Why is max_cell_width applied to data cells only?

Headers are typically short labels, and truncating them can hide useful
information. If you need header truncation, apply truncate_visible to the
header string before passing it to Table::new.

Does the library write to stdout?

No. render() returns a String. Printing is up to the caller.

License
Licensed under either of

Apache License, Version 2.0
(LICENSE-APACHE or
https://www.apache.org/licenses/LICENSE-2.0)

MIT license
(LICENSE-MIT or
https://opensource.org/licenses/MIT)

at your option.

Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

text

## 主要改动


| 位置 | 改动 |
|------|------|
| 顶部简介 | 加"handles ambiguous-width characters like `Φ` predictably" |
| Features | 新增 **Predictable ambiguous-width handling** 一条 |
| Installation | 版本从 `0.1` → `0.2`(默认行为变了,算破坏性) |
| 新增章节 | **Ambiguous-width characters**:解释 `Φ` 类字符、终端差异表、三种模式、为什么 `Auto` 不是默认、如何自测 |
| Before and after 汇总表 | 加一行 "Ambiguous-width handling" |
| API overview | `Table` 加 `.ambiguous_width()`、`.cjk_context()`;新增 `AmbiguousWidth` 枚举表;Free functions 加 `display_width_with`、`truncate_visible_with` |
| Design notes | 加 **Ambiguous characters default to 2 columns** 一条 |
| Windows note | 加 Windows Terminal vs `cmd.exe` 的 `Φ` 差异提示 |
| FAQ | 更新"为什么错位",加"为什么 `Auto` 不是默认" |

## 一句话


> README 新增了 **Ambiguous-width characters** 章节,明确说明 `Φ` 类字符在终端里是 1 还是 2 列**不取决于操作系统语言**,本库**默认 `Wide`(2 列)**,并给出 `.cjk_context(false)` / `.ambiguous_width(Auto)` 的覆盖方式,以及"怎么自测终端需要哪种模式"的示例。API overview、Design notes、FAQ、Windows note 同步更新。