README.md
1# `unicode-width`
2
3[](https://github.com/unicode-rs/unicode-width/actions/workflows/rust.yml)
4[](https://crates.io/crates/unicode-width)
5[](https://docs.rs/unicode-width/)
6
7Determine displayed width of `char` and `str` types according to [Unicode Standard Annex #11][UAX11]
8and other portions of the Unicode standard.
9
10This crate is `#![no_std]`.
11
12[UAX11]: http://www.unicode.org/reports/tr11/
13
14```rust
15use unicode_width::UnicodeWidthStr;
16
17fn main() {
18 let teststr = "Ｈｅｌｌｏ, ｗｏｒｌｄ!";
19 let width = teststr.width();
20 println!("{}", teststr);
21 println!("The above string is {} columns wide.", width);
22 let width = teststr.width_cjk();
23 println!("The above string is {} columns wide (CJK).", width);
24}
25```
26
27**NOTE:** The computed width values may not match the actual rendered column
28width. For example, many Brahmic scripts like Devanagari have complex rendering rules
29which this crate does not currently handle (and will never fully handle, because
30the exact rendering depends on the font):
31
32```rust
33extern crate unicode_width;
34use unicode_width::UnicodeWidthStr;
35
36fn main() {
37 assert_eq!("क".width(), 1); // Devanagari letter Ka
38 assert_eq!("ष".width(), 1); // Devanagari letter Ssa
39 assert_eq!("क्ष".width(), 2); // Ka + Virama + Ssa
40}
41```
42
43Additionally, [defective combining character sequences](https://unicode.org/glossary/#defective_combining_character_sequence)
44and nonstandard [Korean jamo](https://unicode.org/glossary/#jamo) sequences may
45be rendered with a different width than what this crate says. (This is not an
46exhaustive list.) For a list of what this crate *does* handle, see
47[docs.rs](https://docs.rs/unicode-width/latest/unicode_width/#rules-for-determining-width).
48
49## crates.io
50
51You can use this package in your project by adding the following
52to your `Cargo.toml`:
53
54```toml
55[dependencies]
56unicode-width = "0.1.11"
57```
58
){kind=link}