| 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 | |
| 7 | Determine displayed width of `char` and `str` types according to [Unicode Standard Annex #11][UAX11] |
| 8 | and other portions of the Unicode standard. |
| 9 | |
| 10 | This crate is `#![no_std]`. |
| 11 | |
| 12 | [UAX11]: http://www.unicode.org/reports/tr11/ |
| 13 | |
| 14 | ```rust |
| 15 | use unicode_width::UnicodeWidthStr; |
| 16 | |
| 17 | fn 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 |
| 28 | width. For example, many Brahmic scripts like Devanagari have complex rendering rules |
| 29 | which this crate does not currently handle (and will never fully handle, because |
| 30 | the exact rendering depends on the font): |
| 31 | |
| 32 | ```rust |
| 33 | extern crate unicode_width; |
| 34 | use unicode_width::UnicodeWidthStr; |
| 35 | |
| 36 | fn 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 | |
| 43 | Additionally, [defective combining character sequences](https://unicode.org/glossary/#defective_combining_character_sequence) |
| 44 | and nonstandard [Korean jamo](https://unicode.org/glossary/#jamo) sequences may |
| 45 | be rendered with a different width than what this crate says. (This is not an |
| 46 | exhaustive 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 | |
| 51 | You can use this package in your project by adding the following |
| 52 | to your `Cargo.toml`: |
| 53 | |
| 54 | ```toml |
| 55 | [dependencies] |
| 56 | unicode-width = "0.2" |
| 57 | ``` |
| 58 | |
| 59 | |
| 60 | ## Changelog |
| 61 | |
| 62 | |
| 63 | ### 0.2.0 |
| 64 | |
| 65 | - Treat `\n` as width 1 (#60) |
| 66 | - Treat ambiguous `Modifier_Letter`s as narrow (#63) |
| 67 | - Support `Grapheme_Cluster_Break=Prepend` (#62) |
| 68 | - Support lots of ligatures (#53) |
| 69 | |
| 70 | Note: If you are using `unicode-width` for linebreaking, the change treating `\n` as width 1 _may cause behavior changes_. It is recommended that in such cases you feed already-line segmented text to `unicode-width`. In other words, please apply higher level control character based line breaking protocols before feeding text to `unicode-width`. Relying on any character producing a stable width in this crate is likely the sign of a bug. |
| 71 |