DOCSEARCHbyAlgolia
Submit Docs

unicode-width Rust Crate

repository·master·Indexed 43 days ago

https://github.com/unicode-rs/unicode-width

A Rust crate for determining the visual displayed width of Unicode characters and strings following Unicode Standard Annex #11 (UAX11). Version 0.2.2 provides the UnicodeWidthStr and UnicodeWidthChar traits to calculate column widths, including specialized CJK width calculations via the 'cjk' feature flag.

Tokens
987
Snippets
4
Records
8
Agent score
6%

What's inside unicode-width

  2. Determine the displayed width of strings and characters

    master

    Use the unicode-width crate to calculate the visual column width of char and str types based on the Unicode Standard Annex #11 (UAX11).

    To use the API, import the UnicodeWidthStr trait, which provides the .width() method for strings. For CJK (Chinese, Japanese, Korean) specific width calculations, use the .width_cjk() method.

    Limitations:

    • Computed widths may not match actual rendered column widths in complex scripts (e.g., Devanagari) because rendering depends on the specific font used.
    • Defective combining character sequences and nonstandard Korean jamo sequences may result in different widths than those reported by this crate.
    use unicode_width::UnicodeWidthStr;

fn main() {
    let teststr = "Ｈｅｌｌｏ, ｗｏｒｌｄ!";
    let width = teststr.width();
    println!("The above string is {} columns wide.", width);
    
    let width_cjk = teststr.width_cjk();
    println!("The above string is {} columns wide (CJK).", width_cjk);
}

  3. Use CJK width calculations with the 'cjk' feature

    master

    When the cjk feature flag is enabled, you can use width_cjk() on both char and str types. This performs an alternate width calculation where characters in the 'Ambiguous' category are treated as 2 columns wide, which is more suited for CJK (Chinese, Japanese, Korean) contexts.

    use unicode_width::UnicodeWidthStr;

let teststr = "“𘀀”";
assert_eq!(teststr.width(), 4);

#[cfg(feature = "cjk")]
assert_eq!(teststr.width_cjk(), 6);

  4. Important note for linebreaking implementations

    master

    As of version 0.2.0, \n is treated as having a width of 1. If you are using unicode-width to implement linebreaking logic, this change may alter your existing behavior.

    Best Practice: To avoid issues, apply higher-level control character-based line breaking protocols before feeding text to unicode-width. It is recommended to feed already line-segmented text to the crate rather than relying on it to handle line breaks.

  5. Configure the 'cjk' feature flag

    master

    The cjk feature is enabled by default.

    • Enabled (default): Provides UnicodeWidthChar::width_cjk and UnicodeWidthStr::width_cjk methods.
    • Disabled: Use no_default_features in your Cargo.toml to disable it. This reduces the amount of static data required by the crate, which is useful for memory-constrained environments.

  6. Calculate the width of a Unicode string

    master

    Use the UnicodeWidthStr trait to determine the displayed width of a str in columns. By default, characters in the 'Ambiguous' category are treated as 1 column wide (suitable for non-CJK contexts).

    use unicode_width::UnicodeWidthStr;

let teststr = "Ｈｅｌｌｏ, ｗｏｒｌｄ!";
let width = UnicodeWidthStr::width(teststr);
println!("{}", teststr);
println!("The above string is {} columns wide.", width);

  7. Calculate width from a character iterator

    master

    If you have an iterator over char instead of a string slice, use the following functions:

    • char_iter_width(s): Calculates width using standard rules (Ambiguous = 1 column).
    • char_iter_width_cjk(s): Calculates width using CJK rules (Ambiguous = 2 columns). Requires the cjk feature.