unicode_width_16/
lib.rs

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//! rules.
14//!
15//! ```rust
16//! extern crate unicode_width_16;
17//!
18//! use unicode_width_16::UnicodeWidthStr;
19//!
20//! fn main() {
21//!     let teststr = "Ｈｅｌｌｏ, ｗｏｒｌｄ!";
22//!     let width = UnicodeWidthStr::width(teststr);
23//!     println!("{}", teststr);
24//!     println!("The above string is {} columns wide.", width);
25//!     let width = teststr.width_cjk();
26//!     println!("The above string is {} columns wide (CJK).", width);
27//! }
28//! ```
29//!
30//! # features
31//!
32//! unicode-width supports a `no_std` feature. This eliminates dependence
33//! on std, and instead uses equivalent functions from core.
34//!
35//! # crates.io
36//!
37//! You can use this package in your project by adding the following
38//! to your `Cargo.toml`:
39//!
40//! ```toml
41//! [dependencies]
42//! unicode-width = "0.1.5"
43//! ```
44
45#![deny(missing_docs, unsafe_code)]
46#![doc(html_logo_url = "https://unicode-rs.github.io/unicode-rs_sm.png",
47       html_favicon_url = "https://unicode-rs.github.io/unicode-rs_sm.png")]
48
49#![cfg_attr(feature = "bench", feature(test))]
50#![no_std]
51
52#[cfg(test)]
53#[macro_use]
54extern crate std;
55
56#[cfg(feature = "bench")]
57extern crate test;
58
59use tables::charwidth as cw;
60pub use tables::UNICODE_VERSION;
61
62mod tables;
63
64#[cfg(test)]
65mod tests;
66
67/// Methods for determining displayed width of Unicode characters.
68pub trait UnicodeWidthChar {
69    /// Returns the character's displayed width in columns, or `None` if the
70    /// character is a control character other than `'\x00'`.
71    ///
72    /// This function treats characters in the Ambiguous category according
73    /// to [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
74    /// as 1 column wide. This is consistent with the recommendations for non-CJK
75    /// contexts, or when the context cannot be reliably determined.
76    fn width(self) -> Option<usize>;
77
78    /// Returns the character's displayed width in columns, or `None` if the
79    /// character is a control character other than `'\x00'`.
80    ///
81    /// This function treats characters in the Ambiguous category according
82    /// to [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
83    /// as 2 columns wide. This is consistent with the recommendations for
84    /// CJK contexts.
85    fn width_cjk(self) -> Option<usize>;
86}
87
88impl UnicodeWidthChar for char {
89    #[inline]
90    fn width(self) -> Option<usize> { cw::width(self, false) }
91
92    #[inline]
93    fn width_cjk(self) -> Option<usize> { cw::width(self, true) }
94}
95
96/// Methods for determining displayed width of Unicode strings.
97pub trait UnicodeWidthStr {
98    /// Returns the string's displayed width in columns.
99    ///
100    /// Control characters are treated as having zero width.
101    ///
102    /// This function treats characters in the Ambiguous category according
103    /// to [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
104    /// as 1 column wide. This is consistent with the recommendations for
105    /// non-CJK contexts, or when the context cannot be reliably determined.
106    fn width<'a>(&'a self) -> usize;
107
108    /// Returns the string's displayed width in columns.
109    ///
110    /// Control characters are treated as having zero width.
111    ///
112    /// This function treats characters in the Ambiguous category according
113    /// to [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
114    /// as 2 column wide. This is consistent with the recommendations for
115    /// CJK contexts.
116    fn width_cjk<'a>(&'a self) -> usize;
117}
118
119impl UnicodeWidthStr for str {
120    #[inline]
121    fn width(&self) -> usize {
122        self.chars().map(|c| cw::width(c, false).unwrap_or(0)).sum()
123    }
124
125    #[inline]
126    fn width_cjk(&self) -> usize {
127        self.chars().map(|c| cw::width(c, true).unwrap_or(0)).sum()
128    }
129}
unicode_width_16/lib.rs

unicode_width_16/
lib.rs
