1// Copyright 2012-2015 The Rust Project Developers. See the COPYRIGHT
2// file at the top-level directory of this distribution and at
3// http://rust-lang.org/COPYRIGHT.
4//
5// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8// option. This file may not be copied, modified, or distributed
9// except according to those terms.
10
11//! Determine displayed width of `char` and `str` types according to
12//! [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
13//! and other portions of the Unicode standard.
14//! See the [Rules for determining width](#rules-for-determining-width) section
15//! for the exact rules.
16//!
17//! This crate is `#![no_std]`.
18//!
19//! ```rust
20//! use unicode_width::UnicodeWidthStr;
21//!
22//! let teststr = "Ｈｅｌｌｏ, ｗｏｒｌｄ!";
23//! let width = UnicodeWidthStr::width(teststr);
24//! println!("{}", teststr);
25//! println!("The above string is {} columns wide.", width);
26//! ```
27//!
28//! # `"cjk"` feature flag
29//!
30//! This crate has one Cargo feature flag, `"cjk"`
31//! (enabled by default).
32//! It enables the [`UnicodeWidthChar::width_cjk`]
33//! and [`UnicodeWidthStr::width_cjk`],
34//! which perform an alternate width calculation
35//! more suited to CJK contexts. The flag also unseals the
36//! [`UnicodeWidthChar`] and [`UnicodeWidthStr`] traits.
37//!
38//! Disabling the flag (with `no_default_features` in `Cargo.toml`)
39//! will reduce the amount of static data needed by the crate.
40//!
41//! ```rust
42//! use unicode_width::UnicodeWidthStr;
43//!
44//! let teststr = "“𘀀”";
45//! assert_eq!(teststr.width(), 4);
46//!
47//! #[cfg(feature = "cjk")]
48//! assert_eq!(teststr.width_cjk(), 6);
49//! ```
50//!
51//! # Rules for determining width
52//!
53//! This crate currently uses the following rules to determine the width of a
54//! character or string, in order of decreasing precedence. These may be tweaked in the future.
55//!
56//! 1. In the following cases, the width of a string differs from the sum of the widths of its constituent characters:
57//! - The sequence `"\r\n"` has width 1.
58//! - Emoji-specific ligatures:
59//! - Well-formed, fully-qualified [emoji ZWJ sequences] have width 2.
60//! - [Emoji modifier sequences] have width 2.
61//! - [Emoji presentation sequences] have width 2.
62//! - Outside of an East Asian context, [text presentation sequences] have width 1 if their base character:
63//! - Has the [`Emoji_Presentation`] property, and
64//! - Is not in the [Enclosed Ideographic Supplement] block.
65//! - Script-specific ligatures:
66//! - For all the following ligatures, the insertion of any number of [default-ignorable][`Default_Ignorable_Code_Point`]
67//! [combining marks] anywhere in the sequence will not change the total width. In addition, for all non-Arabic
68//! ligatures, the insertion of any number of [`'\u{200D}'` ZERO WIDTH JOINER](https://www.unicode.org/versions/Unicode15.0.0/ch23.pdf#G23126)s
69//! will not affect the width.
70//! - **[Arabic]**: A character sequence consisting of one character with [`Joining_Group`]`=Lam`,
71//! followed by any number of characters with [`Joining_Type`]`=Transparent`, followed by one character
72//! with [`Joining_Group`]`=Alef`, has total width 1. For example: `لا`‎, `لآ`‎, `ڸا`‎, `لٟٞأ`
73//! - **[Buginese]**: `"\u{1A15}\u{1A17}\u{200D}\u{1A10}"` (<a, -i> ya, `ᨕᨗ‍ᨐ`) has total width 1.
74//! - **[Hebrew]**: `"א\u{200D}ל"` (Alef-Lamed, `א‍ל`) has total width 1.
75//! - **[Khmer]**: Coeng signs consisting of `'\u{17D2}'` followed by a character in
76//! `'\u{1780}'..='\u{1782}' | '\u{1784}'..='\u{1787}' | '\u{1789}'..='\u{178C}' | '\u{178E}'..='\u{1793}' | '\u{1795}'..='\u{1798}' | '\u{179B}'..='\u{179D}' | '\u{17A0}' | '\u{17A2}' | '\u{17A7}' | '\u{17AB}'..='\u{17AC}' | '\u{17AF}'`
77//! have width 0.
78//! - **[Lisu]**: Tone letter combinations consisting of a character in the range `'\u{A4F8}'..='\u{A4FB}'`
79//! followed by a character in the range `'\u{A4FC}'..='\u{A4FD}'` have width 1. For example: `ꓹꓼ`
80//! - **[Old Turkic]**: `"\u{10C32}\u{200D}\u{10C03}"` (`𐰲‍𐰃`) has total width 1.
81//! - **[Tifinagh]**: A sequence of a Tifinagh consonant in the range `'\u{2D31}'..='\u{2D65}' | '\u{2D6F}'`, followed by either
82//! [`'\u{2D7F}'` TIFINAGH CONSONANT JOINER] or `'\u{200D}'`, followed by another Tifinangh consonant, has total width 1.
83//! For example: `ⵏ⵿ⴾ`
84//! - In an East Asian context only, `<`, `=`, or `>` have width 2 when followed by [`'\u{0338}'` COMBINING LONG SOLIDUS OVERLAY].
85//! The two characters may be separated by any number of characters whose canonical decompositions consist only of characters meeting
86//! one of the following requirements:
87//! - Has [`Canonical_Combining_Class`] greater than 1, or
88//! - Is a [default-ignorable][`Default_Ignorable_Code_Point`] [combining mark][combining marks].
89//! 2. In all other cases, the width of the string equals the sum of its character widths:
90//! 1. [`'\u{2D7F}'` TIFINAGH CONSONANT JOINER] has width 1 (outside of the ligatures described previously).
91//! 2. [`'\u{115F}'` HANGUL CHOSEONG FILLER](https://util.unicode.org/UnicodeJsps/character.jsp?a=115F) and
92//! [`'\u{17A4}'` KHMER INDEPENDENT VOWEL QAA](https://util.unicode.org/UnicodeJsps/character.jsp?a=17A4) have width 2.
93//! 3. [`'\u{17D8}'` KHMER SIGN BEYYAL](https://util.unicode.org/UnicodeJsps/character.jsp?a=17D8) has width 3.
94//! 4. The following have width 0:
95//! - [Characters](https://util.unicode.org/UnicodeJsps/list-unicodeset.jsp?a=%5Cp%7BDefault_Ignorable_Code_Point%7D)
96//! with the [`Default_Ignorable_Code_Point`] property.
97//! - [Characters](https://util.unicode.org/UnicodeJsps/list-unicodeset.jsp?a=%5Cp%7BGrapheme_Extend%7D)
98//! with the [`Grapheme_Extend`] property.
99//! - The following 8 characters, all of which have NFD decompositions consisting of two [`Grapheme_Extend`] characters:
100//! - [`'\u{0CC0}'` KANNADA VOWEL SIGN II](https://util.unicode.org/UnicodeJsps/character.jsp?a=0CC0),
101//! - [`'\u{0CC7}'` KANNADA VOWEL SIGN EE](https://util.unicode.org/UnicodeJsps/character.jsp?a=0CC7),
102//! - [`'\u{0CC8}'` KANNADA VOWEL SIGN AI](https://util.unicode.org/UnicodeJsps/character.jsp?a=0CC8),
103//! - [`'\u{0CCA}'` KANNADA VOWEL SIGN O](https://util.unicode.org/UnicodeJsps/character.jsp?a=0CCA),
104//! - [`'\u{0CCB}'` KANNADA VOWEL SIGN OO](https://util.unicode.org/UnicodeJsps/character.jsp?a=0CCB),
105//! - [`'\u{1B3B}'` BALINESE VOWEL SIGN RA REPA TEDUNG](https://util.unicode.org/UnicodeJsps/character.jsp?a=1B3B),
106//! - [`'\u{1B3D}'` BALINESE VOWEL SIGN LA LENGA TEDUNG](https://util.unicode.org/UnicodeJsps/character.jsp?a=1B3D), and
107//! - [`'\u{1B43}'` BALINESE VOWEL SIGN PEPET TEDUNG](https://util.unicode.org/UnicodeJsps/character.jsp?a=1B43).
108//! - [Characters](https://util.unicode.org/UnicodeJsps/list-unicodeset.jsp?a=%5Cp%7BHangul_Syllable_Type%3DV%7D%5Cp%7BHangul_Syllable_Type%3DT%7D)
109//! with a [`Hangul_Syllable_Type`] of `Vowel_Jamo` (`V`) or `Trailing_Jamo` (`T`).
110//! - The following [`Prepended_Concatenation_Mark`]s:
111//! - [`'\u{0605}'` NUMBER MARK ABOVE](https://util.unicode.org/UnicodeJsps/character.jsp?a=0605),
112//! - [`'\u{070F}'` SYRIAC ABBREVIATION MARK](https://util.unicode.org/UnicodeJsps/character.jsp?a=070F),
113//! - [`'\u{0890}'` POUND MARK ABOVE](https://util.unicode.org/UnicodeJsps/character.jsp?a=0890),
114//! - [`'\u{0891}'` PIASTRE MARK ABOVE](https://util.unicode.org/UnicodeJsps/character.jsp?a=0891), and
115//! - [`'\u{08E2}'` DISPUTED END OF AYAH](https://util.unicode.org/UnicodeJsps/character.jsp?a=08E2).
116//! - [Characters](https://util.unicode.org/UnicodeJsps/list-unicodeset.jsp?a=%5Cp%7BGrapheme_Cluster_Break%3DPrepend%7D-%5Cp%7BPrepended_Concatenation_Mark%7D)
117//! with the [`Grapheme_Extend=Prepend`] property, that are not also [`Prepended_Concatenation_Mark`]s.
118//! - [`'\u{A8FA}'` DEVANAGARI CARET](https://util.unicode.org/UnicodeJsps/character.jsp?a=A8FA).
119//! 5. [Characters](https://util.unicode.org/UnicodeJsps/list-unicodeset.jsp?a=%5Cp%7BEast_Asian_Width%3DF%7D%5Cp%7BEast_Asian_Width%3DW%7D)
120//! with an [`East_Asian_Width`] of [`Fullwidth`] or [`Wide`] have width 2.
121//! 6. Characters fulfilling all of the following conditions have width 2 in an East Asian context, and width 1 otherwise:
122//! - Has an [`East_Asian_Width`] of [`Ambiguous`], or
123//! has a canonical decomposition to an [`Ambiguous`] character followed by [`'\u{0338}'` COMBINING LONG SOLIDUS OVERLAY], or
124//! is [`'\u{0387}'` GREEK ANO TELEIA](https://util.unicode.org/UnicodeJsps/character.jsp?a=0387), and
125//! - Does not have a [`General_Category`] of `Letter` or `Modifier_Symbol`.
126//! 7. All other characters have width 1.
127//!
128//! [`'\u{0338}'` COMBINING LONG SOLIDUS OVERLAY]: https://util.unicode.org/UnicodeJsps/character.jsp?a=0338
129//! [`'\u{2D7F}'` TIFINAGH CONSONANT JOINER]: https://util.unicode.org/UnicodeJsps/character.jsp?a=2D7F
130//!
131//! [`Canonical_Combining_Class`]: https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf#G50313
132//! [`Default_Ignorable_Code_Point`]: https://www.unicode.org/versions/Unicode15.0.0/ch05.pdf#G40095
133//! [`East_Asian_Width`]: https://www.unicode.org/reports/tr11/#ED1
134//! [`Emoji_Presentation`]: https://unicode.org/reports/tr51/#def_emoji_presentation
135//! [`General_Category`]: https://www.unicode.org/versions/Unicode15.0.0/ch04.pdf#G124142
136//! [`Grapheme_Extend=Prepend`]: https://www.unicode.org/reports/tr29/#Prepend
137//! [`Grapheme_Extend`]: https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf#G52443
138//! [`Hangul_Syllable_Type`]: https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf#G45593
139//! [`Joining_Group`]: https://www.unicode.org/versions/Unicode14.0.0/ch09.pdf#G36862
140//! [`Joining_Type`]: http://www.unicode.org/versions/Unicode15.0.0/ch09.pdf#G50009
141//! [`Prepended_Concatenation_Mark`]: https://www.unicode.org/versions/Unicode15.0.0/ch23.pdf#G37908
142//! [`Script`]: https://www.unicode.org/reports/tr24/#Script
143//!
144//! [`Fullwidth`]: https://www.unicode.org/reports/tr11/#ED2
145//! [`Wide`]: https://www.unicode.org/reports/tr11/#ED4
146//! [`Ambiguous`]: https://www.unicode.org/reports/tr11/#ED6
147//!
148//! [combining marks]: https://www.unicode.org/versions/Unicode15.0.0/ch03.pdf#G30602
149//!
150//! [emoji ZWJ sequences]: https://www.unicode.org/reports/tr51/#def_emoji_sequence
151//! [Emoji modifier sequences]: https://www.unicode.org/reports/tr51/#def_emoji_modifier_sequence
152//! [Emoji presentation sequences]: https://unicode.org/reports/tr51/#def_emoji_presentation_sequence
153//! [text presentation sequences]: https://unicode.org/reports/tr51/#def_text_presentation_sequence
154//!
155//! [Enclosed Ideographic Supplement]: https://unicode.org/charts/nameslist/n_1F200.html
156//!
157//! [Arabic]: https://www.unicode.org/versions/Unicode15.0.0/ch09.pdf#G7480
158//! [Buginese]: https://www.unicode.org/versions/Unicode15.0.0/ch17.pdf#G26743
159//! [Hebrew]: https://www.unicode.org/versions/Unicode15.0.0/ch09.pdf#G6528
160//! [Khmer]: https://www.unicode.org/versions/Unicode15.0.0/ch16.pdf#G64642
161//! [Lisu]: https://www.unicode.org/versions/Unicode15.0.0/ch18.pdf#G44587
162//! [Old Turkic]: https://www.unicode.org/versions/Unicode15.0.0/ch14.pdf#G41975
163//! [Tifinagh]: http://www.unicode.org/versions/Unicode15.0.0/ch19.pdf#G43184
164//!
165//!
166//! ## Canonical equivalence
167//!
168//! Canonically equivalent strings are assigned the same width (CJK and non-CJK).
169
170#![forbid(unsafe_code)]
171#![deny(missing_docs)]
172#![doc(
173 html_logo_url = "https://unicode-rs.github.io/unicode-rs_sm.png",
174 html_favicon_url = "https://unicode-rs.github.io/unicode-rs_sm.png"
175)]
176#![no_std]
177
178pub use tables::UNICODE_VERSION;
179
180mod tables;
181
182mod private {
183 pub trait Sealed {}
184 #[cfg(not(feature = "cjk"))]
185 impl Sealed for char {}
186 #[cfg(not(feature = "cjk"))]
187 impl Sealed for str {}
188 #[cfg(feature = "cjk")]
189 impl<T: ?Sized> Sealed for T {}
190}
191
192/// Methods for determining displayed width of Unicode characters.
193pub trait UnicodeWidthChar: private::Sealed {
194 /// Returns the character's displayed width in columns, or `None` if the
195 /// character is a control character.
196 ///
197 /// This function treats characters in the Ambiguous category according
198 /// to [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
199 /// as 1 column wide. This is consistent with the recommendations for non-CJK
200 /// contexts, or when the context cannot be reliably determined.
201 fn width(self) -> Option<usize>;
202
203 /// Returns the character's displayed width in columns, or `None` if the
204 /// character is a control character.
205 ///
206 /// This function treats characters in the Ambiguous category according
207 /// to [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
208 /// as 2 columns wide. This is consistent with the recommendations for
209 /// CJK contexts.
210 #[cfg(feature = "cjk")]
211 fn width_cjk(self) -> Option<usize>;
212}
213
214impl UnicodeWidthChar for char {
215 #[inline]
216 fn width(self) -> Option<usize> {
217 tables::single_char_width(self)
218 }
219
220 #[cfg(feature = "cjk")]
221 #[inline]
222 fn width_cjk(self) -> Option<usize> {
223 tables::single_char_width_cjk(self)
224 }
225}
226
227/// Methods for determining displayed width of Unicode strings.
228pub trait UnicodeWidthStr: private::Sealed {
229 /// Returns the string's displayed width in columns.
230 ///
231 /// This function treats characters in the Ambiguous category according
232 /// to [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
233 /// as 1 column wide. This is consistent with the recommendations for
234 /// non-CJK contexts, or when the context cannot be reliably determined.
235 fn width(&self) -> usize;
236
237 /// Returns the string's displayed width in columns.
238 ///
239 /// This function treats characters in the Ambiguous category according
240 /// to [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
241 /// as 2 column wide. This is consistent with the recommendations for
242 /// CJK contexts.
243 #[cfg(feature = "cjk")]
244 fn width_cjk(&self) -> usize;
245}
246
247impl UnicodeWidthStr for str {
248 #[inline]
249 fn width(&self) -> usize {
250 tables::str_width(self)
251 }
252
253 #[cfg(feature = "cjk")]
254 #[inline]
255 fn width_cjk(&self) -> usize {
256 tables::str_width_cjk(self)
257 }
258}
259