Implement Display for char Escape*, To*case.

1 files changed, 150 insertions, 49 deletions

diff --git a/src/libstd_unicode/char.rs b/src/libstd_unicode/char.rs
index 53dafadb5d5..f2c53efda17 100644
--- a/src/libstd_unicode/char.rs
+++ b/src/libstd_unicode/char.rs
@@ -30,7 +30,7 @@
 
 use core::char::CharExt as C;
 use core::iter::FusedIterator;
-use core::fmt;
+use core::fmt::{self, Write};
 use tables::{conversions, derived_property, general_category, property};
 
 // stable reexports
@@ -131,6 +131,41 @@ impl Iterator for CaseMappingIter {
     }
 }
 
+#[stable(feature = "char_struct_display", since = "1.17.0")]
+impl fmt::Display for CaseMappingIter {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match *self {
+            CaseMappingIter::Three(a, b, c) => {
+                f.write_char(a)?;
+                f.write_char(b)?;
+                f.write_char(c)
+            }
+            CaseMappingIter::Two(b, c) => {
+                f.write_char(b)?;
+                f.write_char(c)
+            }
+            CaseMappingIter::One(c) => {
+                f.write_char(c)
+            }
+            CaseMappingIter::Zero => Ok(()),
+        }
+    }
+}
+
+#[stable(feature = "char_struct_display", since = "1.17.0")]
+impl fmt::Display for ToLowercase {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Display::fmt(&self.0, f)
+    }
+}
+
+#[stable(feature = "char_struct_display", since = "1.17.0")]
+impl fmt::Display for ToUppercase {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        fmt::Display::fmt(&self.0, f)
+    }
+}
+
 #[lang = "char"]
 impl char {
     /// Checks if a `char` is a digit in the given radix.
@@ -240,34 +275,38 @@ impl char {
     }
 
     /// Returns an iterator that yields the hexadecimal Unicode escape of a
-    /// character, as `char`s.
+    /// character as `char`s.
     ///
-    /// All characters are escaped with Rust syntax of the form `\u{NNNNNN}`
-    /// where `NNNNNN` is the shortest hexadecimal representation.
+    /// This will escape characters with the Rust syntax of the form
+    /// `\u{NNNNNN}` where `NNNNNN` is a hexadecimal representation.
     ///
     /// # Examples
     ///
-    /// Basic usage:
+    /// As an iterator:
     ///
     /// ```
     /// for c in '❤'.escape_unicode() {
     ///     print!("{}", c);
     /// }
-    /// println!("");
+    /// println!();
     /// ```
     ///
-    /// This prints:
+    /// Using `println!` directly:
     ///
-    /// ```text
-    /// \u{2764}
+    /// ```
+    /// println!("{}", '❤'.escape_unicode());
     /// ```
     ///
-    /// Collecting into a `String`:
+    /// Both are equivalent to:
     ///
     /// ```
-    /// let heart: String = '❤'.escape_unicode().collect();
+    /// println!("\\u{{2764}}");
+    /// ```
     ///
-    /// assert_eq!(heart, r"\u{2764}");
+    /// Using `to_string`:
+    ///
+    /// ```
+    /// assert_eq!('❤'.escape_unicode().to_string(), "\\u{2764}");
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
@@ -275,34 +314,42 @@ impl char {
         C::escape_unicode(self)
     }
 
-    /// Returns an iterator that yields the literal escape code of a `char`.
+    /// Returns an iterator that yields the literal escape code of a character
+    /// as `char`s.
     ///
     /// This will escape the characters similar to the `Debug` implementations
     /// of `str` or `char`.
     ///
     /// # Examples
     ///
-    /// Basic usage:
+    /// As an iterator:
     ///
     /// ```
-    /// for i in '\n'.escape_default() {
-    ///     println!("{}", i);
+    /// # #![feature(char_escape_debug)]
+    /// for c in '\n'.escape_debug() {
+    ///     print!("{}", c);
     /// }
+    /// println!();
     /// ```
     ///
-    /// This prints:
+    /// Using `println!` directly:
     ///
-    /// ```text
-    /// \
-    /// n
+    /// ```
+    /// # #![feature(char_escape_debug)]
+    /// println!("{}", '\n'.escape_debug());
     /// ```
     ///
-    /// Collecting into a `String`:
+    /// Both are equivalent to:
     ///
     /// ```
-    /// let quote: String = '\n'.escape_default().collect();
+    /// println!("\\n");
+    /// ```
     ///
-    /// assert_eq!(quote, "\\n");
+    /// Using `to_string`:
+    ///
+    /// ```
+    /// # #![feature(char_escape_debug)]
+    /// assert_eq!('\n'.escape_debug().to_string(), "\\n");
     /// ```
     #[unstable(feature = "char_escape_debug", issue = "35068")]
     #[inline]
@@ -310,7 +357,8 @@ impl char {
         C::escape_debug(self)
     }
 
-    /// Returns an iterator that yields the literal escape code of a `char`.
+    /// Returns an iterator that yields the literal escape code of a character
+    /// as `char`s.
     ///
     /// The default is chosen with a bias toward producing literals that are
     /// legal in a variety of languages, including C++11 and similar C-family
@@ -331,27 +379,32 @@ impl char {
     ///
     /// # Examples
     ///
-    /// Basic usage:
+    /// As an iterator:
     ///
     /// ```
-    /// for i in '"'.escape_default() {
-    ///     println!("{}", i);
+    /// for c in '"'.escape_default() {
+    ///     print!("{}", c);
     /// }
+    /// println!();
     /// ```
     ///
-    /// This prints:
+    /// Using `println!` directly:
     ///
-    /// ```text
-    /// \
-    /// "
     /// ```
+    /// println!("{}", '"'.escape_default());
+    /// ```
+    ///
     ///
-    /// Collecting into a `String`:
+    /// Both are equivalent to:
     ///
     /// ```
-    /// let quote: String = '"'.escape_default().collect();
+    /// println!("\\\"");
+    /// ```
+    ///
+    /// Using `to_string`:
     ///
-    /// assert_eq!(quote, "\\\"");
+    /// ```
+    /// assert_eq!('"'.escape_default().to_string(), "\\\"");
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
@@ -726,9 +779,11 @@ impl char {
         }
     }
 
-    /// Returns an iterator that yields the lowercase equivalent of a `char`.
+    /// Returns an iterator that yields the lowercase equivalent of a `char`
+    /// as one or more `char`s.
     ///
-    /// If no conversion is possible then an iterator with just the input character is returned.
+    /// If a character does not have a lowercase equivalent, the same character
+    /// will be returned back by the iterator.
     ///
     /// This performs complex unconditional mappings with no tailoring: it maps
     /// one Unicode character to its lowercase equivalent according to the
@@ -746,16 +801,37 @@ impl char {
     ///
     /// # Examples
     ///
-    /// Basic usage:
+    /// As an iterator:
+    ///
+    /// ```
+    /// for c in 'İ'.to_lowercase() {
+    ///     print!("{}", c);
+    /// }
+    /// println!();
+    /// ```
+    ///
+    /// Using `println!` directly:
+    ///
+    /// ```
+    /// println!("{}", 'İ'.to_lowercase());
+    /// ```
+    ///
+    /// Both are equivalent to:
+    ///
+    /// ```
+    /// println!("i\u{307}");
+    /// ```
+    ///
+    /// Using `to_string`:
     ///
     /// ```
-    /// assert_eq!('C'.to_lowercase().collect::<String>(), "c");
+    /// assert_eq!('C'.to_lowercase().to_string(), "c");
     ///
     /// // Sometimes the result is more than one character:
-    /// assert_eq!('İ'.to_lowercase().collect::<String>(), "i\u{307}");
+    /// assert_eq!('İ'.to_lowercase().to_string(), "i\u{307}");
     ///
     /// // Japanese scripts do not have case, and so:
-    /// assert_eq!('山'.to_lowercase().collect::<String>(), "山");
+    /// assert_eq!('山'.to_lowercase().to_string(), "山");
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
@@ -763,12 +839,14 @@ impl char {
         ToLowercase(CaseMappingIter::new(conversions::to_lower(self)))
     }
 
-    /// Returns an iterator that yields the uppercase equivalent of a `char`.
+    /// Returns an iterator that yields the uppercase equivalent of a `char`
+    /// as one or more `char`s.
     ///
-    /// If no conversion is possible then an iterator with just the input character is returned.
+    /// If a character does not have a uppercase equivalent, the same character
+    /// will be returned back by the iterator.
     ///
     /// This performs complex unconditional mappings with no tailoring: it maps
-    /// one Unicode character to its uppercase equivalent according to the
+    /// one Unicode character to its lowercase equivalent according to the
     /// [Unicode database] and the additional complex mappings
     /// [`SpecialCasing.txt`]. Conditional mappings (based on context or
     /// language) are not considered here.
@@ -783,18 +861,41 @@ impl char {
     ///
     /// # Examples
     ///
-    /// Basic usage:
+    /// As an iterator:
     ///
     /// ```
-    /// assert_eq!('c'.to_uppercase().collect::<String>(), "C");
+    /// for c in 'ß'.to_uppercase() {
+    ///     print!("{}", c);
+    /// }
+    /// println!();
+    /// ```
+    ///
+    /// Using `println!` directly:
+    ///
+    /// ```
+    /// println!("{}", 'ß'.to_uppercase());
+    /// ```
+    ///
+    /// Both are equivalent to:
+    ///
+    /// ```
+    /// println!("SS");
+    /// ```
+    ///
+    /// Using `to_string`:
+    ///
+    /// ```
+    /// assert_eq!('c'.to_uppercase().to_string(), "C");
     ///
     /// // Sometimes the result is more than one character:
-    /// assert_eq!('ß'.to_uppercase().collect::<String>(), "SS");
+    /// assert_eq!('ß'.to_uppercase().to_string(), "SS");
     ///
     /// // Japanese does not have case, and so:
-    /// assert_eq!('山'.to_uppercase().collect::<String>(), "山");
+    /// assert_eq!('山'.to_uppercase().to_string(), "山");
     /// ```
     ///
+    /// # Note on locale
+    ///
     /// In Turkish, the equivalent of 'i' in Latin has five forms instead of two:
     ///
     /// * 'Dotless': I / ı, sometimes written ï
@@ -803,7 +904,7 @@ impl char {
     /// Note that the lowercase dotted 'i' is the same as the Latin. Therefore:
     ///
     /// ```
-    /// let upper_i: String = 'i'.to_uppercase().collect();
+    /// let upper_i = 'i'.to_uppercase().to_string();
     /// ```
     ///
     /// The value of `upper_i` here relies on the language of the text: if we're
@@ -811,7 +912,7 @@ impl char {
     /// be `"İ"`. `to_uppercase()` does not take this into account, and so:
     ///
     /// ```
-    /// let upper_i: String = 'i'.to_uppercase().collect();
+    /// let upper_i = 'i'.to_uppercase().to_string();
     ///
     /// assert_eq!(upper_i, "I");
     /// ```