unicode-rs · Manishearth · Oct 12, 2018 · Oct 11, 2018 · Oct 11, 2018 · Manishearth
diff --git a/README.md b/README.md
@@ -1,8 +1,9 @@
 # unicode-width
 
 Determine displayed width of `char` and `str` types according to
-[Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
-rules.
+[Unicode Standard Annex #11][UAX11] rules.
+
+[UAX11]: (http://www.unicode.org/reports/tr11/)
 
 [![Build Status](https://travis-ci.org/unicode-rs/unicode-width.svg)](https://travis-ci.org/unicode-rs/unicode-width)
 
@@ -23,6 +24,24 @@ fn main() {
 }
 ```
 
+**NOTE:** The computed width values may not match the actual rendered column
+width. For example, the woman scientist emoji comprises of a woman emoji, a
+zero-width joiner and a microscope emoji.
+
+```rust
+extern crate unicode_width;
+use unicode_width::UnicodeWidthStr;
+
+fn main() {
+    assert_eq!(UnicodeWidthStr::width("👩"), 2); // Woman
+    assert_eq!(UnicodeWidthStr::width("🔬"), 2); // Microscope
+    assert_eq!(UnicodeWidthStr::width("👩‍🔬"), 4); // Woman scientist
+}
+```
+
+See [Unicode Standard Annex #11](UAX11) for precise details on what is and isn't
+covered by this crate.
+
 ## features
 
 unicode-width does not depend on libstd, so it can be used in crates

diff --git a/src/tests.rs b/src/tests.rs
@@ -108,6 +108,16 @@ fn test_str() {
     assert_eq!("\u{2081}\u{2082}\u{2083}\u{2084}".width_cjk(), 8);
 }
 
+#[test]
+fn test_emoji() {
+    // Example from the README.
+    use super::UnicodeWidthStr;
+
+    assert_eq!(UnicodeWidthStr::width("👩"), 2); // Woman
+    assert_eq!(UnicodeWidthStr::width("🔬"), 2); // Microscope
+    assert_eq!(UnicodeWidthStr::width("👩‍🔬"), 4); // Woman scientist
+}
+
 #[test]
 fn test_char() {
     use super::UnicodeWidthChar;