console-table 0.1.4

Console table rendering with Unicode/CJK-aware alignment, truncation, and ANSI color support
Documentation

console-table

Crates.io Docs.rs 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

  • 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 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.

Installation

Add this to your Cargo.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 同步更新。