console-table 0.1.0

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
# 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), supports optional
per-cell truncation, ANSI foreground colors, and two border styles.

---

## Table of contents


- [Features]#features
- [Installation]#installation
- [Quick start]#quick-start
- [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.
- **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.1"
```

---

## 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   │
└──────┴─────────────────────┴──────────┘
```

---

## 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`](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 `char`s 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 | ✗ | ✓ | ✓ |
| 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. |
| `.render() -> String` | Render the table. Every line ends with `\n`. |

### `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. |
| `truncate_visible(&str, usize) -> String` | Truncate to a display width, appending ASCII `...`. |
| `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.
- **`...` 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](https://aka.ms/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.

---

## FAQ


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

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.

**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]LICENSE-APACHE or
  <https://www.apache.org/licenses/LICENSE-2.0>)
- MIT license
  ([LICENSE-MIT]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.