Crate string_width 

string-width

Accurate Unicode string width calculation for terminal applications.

This library correctly handles:

• Emoji sequences (👨‍👩‍👧‍👦, 🇺🇸, 1️⃣)
• East Asian characters (你好, こんにちは, 안녕하세요)
• Combining marks and diacritics (é, ñ, ü)
• Zero-width characters (ZWJ, ZWNJ, format characters)
• ANSI escape sequences (colors, cursor movement)
• Ambiguous width characters (±, ×, ÷)

Quick Start

use string_width::string_width;

// ASCII text
assert_eq!(string_width("Hello"), 5);

// East Asian characters (full-width)
assert_eq!(string_width("你好"), 4);

// Emoji
assert_eq!(string_width("👋"), 2);
assert_eq!(string_width("🇺🇸"), 2);  // Flag
assert_eq!(string_width("1️⃣"), 2);   // Keycap sequence

// Mixed content
assert_eq!(string_width("Hello 👋 世界"), 13);

// ANSI escape sequences are ignored by default
assert_eq!(string_width("\x1b[31mRed\x1b[0m"), 3);

Advanced Configuration

use string_width::{string_width, string_width_with_options, StringWidthOptions, AmbiguousWidthTreatment};

// Direct configuration
let options = StringWidthOptions {
    count_ansi: true,  // Count ANSI escape sequences
    ambiguous_width: AmbiguousWidthTreatment::Wide,  // Treat ambiguous as wide
};

assert_eq!(string_width_with_options("±×÷", options.clone()), 6);  // Ambiguous chars as wide
assert_eq!(string_width_with_options("\x1b[31mRed\x1b[0m", options), 12);  // Count ANSI

// Using the builder pattern (recommended)
let options = StringWidthOptions::builder()
    .count_ansi(true)
    .ambiguous_as_wide()
    .build();

assert_eq!(string_width_with_options("±×÷", options), 6);

Using the DisplayWidth Trait

use string_width::{DisplayWidth, StringWidthOptions};

let text = "Hello 🌍";
println!("Width: {}", text.display_width());

// With custom options
let options = StringWidthOptions::default();
println!("Width: {}", text.display_width_with_options(options));

Structs

StringWidthOptions

Configuration options for string width calculation

StringWidthOptionsBuilder

Builder for StringWidthOptions following the builder pattern

Enums

AmbiguousWidthTreatment

How to treat ambiguous width characters

Traits

DisplayWidth

Trait for types that can have their display width calculated

Functions

string_width

Convenience function for calculating string width with default options

string_width_with_options

Main function that calculates the display width of a string