Struct UnicodeWidth 

pub struct UnicodeWidth { /* private fields */ }

A configuration helper to measure character and string widths.

It determines the width of Unicode characters and strings, optionally treating East Asian Ambiguous characters (such as certain Greek, Cyrillic, and CJK characters) as having a width of 2 (CJK mode).

The default CJK mode is initialized at startup based on the UNICODE_WIDTH environment variable, but can also be dynamically modified using UnicodeWidth::set_default_cjk.

Implementations

impl UnicodeWidth

pub fn new() -> Self

Create a UnicodeWidth instance using the default CJK mode.

The default CJK mode is determined by the global setting, which defaults to the value of the UNICODE_WIDTH environment variable (value "cjk" enabling CJK mode).

See also set_default_cjk.

pub fn with_cjk(is_cjk: bool) -> Self

Create a new UnicodeWidth instance with a specific CJK flag.

If is_cjk is true, East Asian Ambiguous characters will be treated as 2 columns wide. If false, they will be treated as 1 column wide.

Examples

use unicode_width_utils::UnicodeWidth;

let non_cjk = UnicodeWidth::with_cjk(false);
assert_eq!(non_cjk.char('█'), Some(1));

let cjk = UnicodeWidth::with_cjk(true);
assert_eq!(cjk.char('█'), Some(2));

pub fn set_default_cjk(is_cjk: bool)

Set the default CJK configuration dynamically.

Future instances created using UnicodeWidth::new or UnicodeWidth::default will inherit this default value unless explicitly overridden with UnicodeWidth::with_cjk.

Examples

use unicode_width_utils::UnicodeWidth;

// Set default CJK mode to true.
UnicodeWidth::set_default_cjk(true);
let uw = UnicodeWidth::new();
assert_eq!(uw.char('█'), Some(2));

// Set default CJK mode to false.
UnicodeWidth::set_default_cjk(false);
let uw2 = UnicodeWidth::new();
assert_eq!(uw2.char('█'), Some(1));

pub fn char(&self, ch: char) -> Option<usize>

👎Deprecated:

Please use char_opt instead.

pub fn char_opt(&self, ch: char) -> Option<usize>

Return the column width of a character.

Return None for control characters or other characters without a defined width.

This is a wrapper of UnicodeWidthChar. It calls width or width_cjk depending on the configuration.

Examples

use unicode_width_utils::UnicodeWidth;

let uw = UnicodeWidth::with_cjk(false);
assert_eq!(uw.char('A'), Some(1));
assert_eq!(uw.char('\n'), None);

pub fn str(&self, str: &str) -> usize

Return the total column width of a string.

This is a wrapper of UnicodeWidthStr. It calls width or width_cjk depending on the configuration.

Examples

use unicode_width_utils::UnicodeWidth;

let uw = UnicodeWidth::with_cjk(false);
assert_eq!(uw.str("Hello"), 5);

pub fn set_tab_size(&mut self, tab_size: u8)

Set the tab size for truncate. Initially 0.

See also set_expand_tab.

Examples

use unicode_width_utils::UnicodeWidth;

let mut uw = UnicodeWidth::new();
uw.set_tab_size(4);
assert_eq!(uw.truncate("A\tB", 3), Cow::Borrowed("A"));
assert_eq!(uw.truncate("A\tB", 4), Cow::Borrowed("A\t"));
assert_eq!(uw.truncate("A\tB", 5), Cow::Borrowed("A\tB"));

pub fn set_expand_tab(&mut self, should_expand_tab: bool)

Set whether tabs should be expanded to spaces in truncate. Initially false.

Examples

use unicode_width_utils::UnicodeWidth;

let mut uw = UnicodeWidth::new();
uw.set_tab_size(4);
uw.set_expand_tab(true);
assert_eq!(uw.truncate("A\tB", 3), Cow::Borrowed("A"));
assert_eq!(uw.truncate("A\tB", 4), Cow::Owned::<str>("A   ".into()));
assert_eq!(uw.truncate("A\tB", 5), Cow::Owned::<str>("A   B".into()));

pub fn truncate<'a>(&self, input: &'a str, max_width: usize) -> Cow<'a, str>

Truncate a string slice to a maximum column width.

The returned slice will be the longest prefix of str whose total column width does not exceed max_width.

See also set_tab_size and set_expand_tab.

Examples

use unicode_width_utils::UnicodeWidth;

let uw = UnicodeWidth::with_cjk(false);
assert_eq!(uw.truncate("hello", 3), "hel");

// Truncating CJK text (each 'あ' is 2 columns wide).
let cjk = UnicodeWidth::with_cjk(true);
assert_eq!(cjk.truncate("あああ", 3), "あ");
assert_eq!(cjk.truncate("A█B", 2), "A");

Trait Implementations

impl Clone for UnicodeWidth

fn clone(&self) -> UnicodeWidth

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnicodeWidth

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for UnicodeWidth

fn default() -> Self

Create a UnicodeWidth instance using the default CJK mode.

The default CJK mode is determined by the global setting, which defaults to the value of the UNICODE_WIDTH environment variable (value "cjk" enabling CJK mode).

See also set_default_cjk.