Function string_width_with_options 

pub fn string_width_with_options(
    input: &str,
    options: StringWidthOptions,
) -> usize

Main function that calculates the display width of a string

This is the core width calculation function that processes a string grapheme by grapheme, handling:

• ANSI escape sequences (optionally)
• Zero-width character clusters
• Emoji sequences
• East Asian character widths
• Combining characters and modifiers

Arguments

• input - The string to measure
• options - Configuration options for the calculation

Returns

The display width of the string in terminal columns

Examples

use string_width::{string_width_with_options, StringWidthOptions};

let options = StringWidthOptions::default();
assert_eq!(string_width_with_options("Hello", options.clone()), 5);
assert_eq!(string_width_with_options("😀", options), 2);

Examples found in repository

examples/basic_usage.rs (line 57)

fn main() {
    println!("=== Basic String Width Examples ===\n");

    // Basic ASCII text
    let text = "Hello, World!";
    println!("Text: '{}'", text);
    println!("Width: {}\n", string_width(text));

    // East Asian characters (full-width)
    let text = "你好世界";
    println!("Text: '{}'", text);
    println!("Width: {}\n", string_width(text));

    // Mixed content
    let text = "Hello 世界!";
    println!("Text: '{}'", text);
    println!("Width: {}\n", string_width(text));

    // Emoji examples
    let text = "Hello 👋 World 🌍";
    println!("Text: '{}'", text);
    println!("Width: {}\n", string_width(text));

    // Complex emoji sequences
    let text = "Family: 👨‍👩‍👧‍👦";
    println!("Text: '{}'", text);
    println!("Width: {}\n", string_width(text));

    // Keycap sequences
    let text = "Numbers: 1️⃣ 2️⃣ 3️⃣";
    println!("Text: '{}'", text);
    println!("Width: {}\n", string_width(text));

    // Flag sequences
    let text = "Flags: 🇺🇸 🇯🇵 🇬🇧";
    println!("Text: '{}'", text);
    println!("Width: {}\n", string_width(text));

    // ANSI escape sequences (stripped by default)
    let text = "\x1b[31mRed text\x1b[0m";
    println!("Text with ANSI: '{}'", text);
    println!("Width (ANSI stripped): {}", string_width(text));

    let options = StringWidthOptions {
        count_ansi: true,
        ambiguous_width: AmbiguousWidthTreatment::Narrow,
    };
    println!(
        "Width (ANSI counted): {}\n",
        string_width_with_options(text, options)
    );

    // Ambiguous width characters
    let text = "±×÷";
    println!("Text: '{}'", text);
    println!("Width (narrow): {}", string_width(text));

    let options = StringWidthOptions {
        count_ansi: false,
        ambiguous_width: AmbiguousWidthTreatment::Wide,
    };
    println!(
        "Width (wide): {}\n",
        string_width_with_options(text, options)
    );

    // Zero-width characters
    let text = "a\u{200B}b\u{200C}c";
    println!("Text with zero-width chars: 'a\\u{{200B}}b\\u{{200C}}c'");
    println!("Width: {}\n", string_width(text));

    // Combining characters
    let text = "e\u{0301}"; // e with acute accent
    println!("Text with combining: 'e\\u{{0301}}'");
    println!("Width: {}\n", string_width(text));
}

examples/cli_tool.rs (line 89)

fn main() {
    let args: Vec<String> = env::args().collect();

    let input = if args.len() > 1 {
        // Use command line argument
        args[1..].join(" ")
    } else {
        // Read from stdin
        let mut buffer = String::new();
        match io::stdin().read_to_string(&mut buffer) {
            Ok(_) => buffer.trim_end().to_string(),
            Err(e) => {
                eprintln!("Error reading from stdin: {}", e);
                std::process::exit(1);
            }
        }
    };

    if input.is_empty() {
        eprintln!("Usage: {} <text> or echo <text> | {}", args[0], args[0]);
        eprintln!("       Measures the display width of Unicode text");
        std::process::exit(1);
    }

    println!("Text analysis for: '{}'", input);
    println!("{}", "─".repeat(50));

    // Basic width
    let width = input.display_width();
    println!("Display width: {} characters", width);

    // Character count vs display width
    let char_count = input.chars().count();
    let byte_count = input.len();
    println!("Character count: {}", char_count);
    println!("Byte count: {}", byte_count);

    if width != char_count {
        println!("Note: Display width differs from character count");
        if width > char_count {
            println!("  → Contains wide characters (CJK, emoji)");
        } else {
            println!("  → Contains zero-width or combining characters");
        }
    }

    // Detailed analysis
    println!("\nDetailed breakdown:");
    for (i, ch) in input.chars().enumerate() {
        let ch_width = string_width(ch.to_string().as_str());
        let code_point = ch as u32;

        let char_type = match ch_width {
            0 => "zero-width",
            1 => "narrow",
            2 => "wide",
            _ => "unknown",
        };

        println!(
            "  {}: '{}' (U+{:04X}) - {} width",
            i + 1,
            ch,
            code_point,
            char_type
        );
    }

    // Different width calculation options
    println!("\nWidth with different options:");

    let narrow_ambiguous = StringWidthOptions {
        count_ansi: false,
        ambiguous_width: AmbiguousWidthTreatment::Narrow,
    };
    println!(
        "  Ambiguous as narrow: {}",
        string_width_with_options(input.as_str(), narrow_ambiguous)
    );

    let wide_ambiguous = StringWidthOptions {
        count_ansi: false,
        ambiguous_width: AmbiguousWidthTreatment::Wide,
    };
    println!(
        "  Ambiguous as wide: {}",
        string_width_with_options(input.as_str(), wide_ambiguous)
    );

    let count_ansi = StringWidthOptions {
        count_ansi: true,
        ambiguous_width: AmbiguousWidthTreatment::Narrow,
    };
    println!(
        "  Counting ANSI codes: {}",
        string_width_with_options(input.as_str(), count_ansi)
    );

    // Terminal formatting example
    println!("\nTerminal formatting examples:");
    let box_width = 40;
    let content_width = input.display_width();

    if content_width <= box_width - 4 {
        let padding = box_width - content_width - 4;
        let left_pad = padding / 2;
        let right_pad = padding - left_pad;

        println!("┌{}┐", "─".repeat(box_width - 2));
        println!(
            "│{}{}{}│",
            " ".repeat(left_pad + 1),
            input,
            " ".repeat(right_pad + 1)
        );
        println!("└{}┘", "─".repeat(box_width - 2));
    } else {
        println!(
            "Text too wide for box (width: {}, box: {})",
            content_width,
            box_width - 4
        );
    }
}