Add char::to_titlecase()

Author: Jules-Bertholet

library/core/src/char/methods.rs

@@ -1134,14 +1134,112 @@ impl char {
     /// // convert into themselves.
     /// assert_eq!('山'.to_lowercase().to_string(), "山");
     /// ```
-    #[must_use = "this returns the lowercase character as a new iterator, \
+    #[must_use = "this returns the lowercased character as a new iterator, \
                   without modifying the original"]
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]
     pub fn to_lowercase(self) -> ToLowercase {
         ToLowercase(CaseMappingIter::new(conversions::to_lower(self)))
     }
 
+    /// Returns an iterator that yields the titlecase mapping of this `char` as one or more
+    /// `char`s.
+    ///
+    /// If this `char` does not have an titlecase mapping, the iterator yields the same `char`.
+    ///
+    /// If this `char` has a one-to-one titlecase mapping given by the [Unicode Character
+    /// Database][ucd] [`UnicodeData.txt`], the iterator yields that `char`.
+    ///
+    /// [ucd]: https://www.unicode.org/reports/tr44/
+    /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt
+    ///
+    /// If this `char` requires special considerations (e.g. multiple `char`s) the iterator yields
+    /// the `char`(s) given by [`SpecialCasing.txt`].
+    ///
+    /// [`SpecialCasing.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt
+    ///
+    /// This operation performs an unconditional mapping without tailoring. That is, the conversion
+    /// is independent of context and language.
+    ///
+    /// In the [Unicode Standard], Chapter 4 (Character Properties) discusses case mapping in
+    /// general and Chapter 3 (Conformance) discusses the default algorithm for case conversion.
+    ///
+    /// [Unicode Standard]: https://www.unicode.org/versions/latest/
+    ///
+    /// # Examples
+    ///
+    /// As an iterator:
+    ///
+    /// ```
+    /// #![feature(titlecase)]
+    /// for c in 'ß'.to_titlecase() {
+    ///     print!("{c}");
+    /// }
+    /// println!();
+    /// ```
+    ///
+    /// Using `println!` directly:
+    ///
+    /// ```
+    /// #![feature(titlecase)]
+    /// println!("{}", 'ß'.to_titlecase());
+    /// ```
+    ///
+    /// Both are equivalent to:
+    ///
+    /// ```
+    /// #![feature(titlecase)]
+    /// println!("Ss");
+    /// ```
+    ///
+    /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string):
+    ///
+    /// ```
+    /// #![feature(titlecase)]
+    /// assert_eq!('c'.to_titlecase().to_string(), "C");
+    ///
+    /// // Sometimes the result is more than one character:
+    /// assert_eq!('ß'.to_titlecase().to_string(), "Ss");
+    ///
+    /// // Characters that do not have separate cased forms
+    /// // convert into themselves.
+    /// assert_eq!('山'.to_titlecase().to_string(), "山");
+    /// ```
+    ///
+    /// # Note on locale
+    ///
+    /// In Turkish and Azeri, the equivalent of 'i' in Latin has five forms instead of two:
+    ///
+    /// * 'Dotless': I / ı, sometimes written ï
+    /// * 'Dotted': İ / i
+    ///
+    /// Note that the lowercase dotted 'i' is the same as the Latin. Therefore:
+    ///
+    /// ```
+    /// #![feature(titlecase)]
+    /// let upper_i = 'i'.to_titlecase().to_string();
+    /// ```
+    ///
+    /// The value of `upper_i` here relies on the language of the text: if we're
+    /// in `en-US`, it should be `"I"`, but if we're in `tr-TR` or `az-AZ`, it should
+    /// be `"İ"`. `to_titlecase()` does not take this into account, and so:
+    ///
+    /// ```
+    /// #![feature(titlecase)]
+    /// let upper_i = 'i'.to_titlecase().to_string();
+    ///
+    /// assert_eq!(upper_i, "I");
+    /// ```
+    ///
+    /// holds across languages.
+    #[must_use = "this returns the titlecased character as a new iterator, \
+                  without modifying the original"]
+    #[unstable(feature = "titlecase", issue = "none")]
+    #[inline]
+    pub fn to_titlecase(self) -> ToTitlecase {
+        ToTitlecase(CaseMappingIter::new(conversions::to_title(self)))
+    }
+
     /// Returns an iterator that yields the uppercase mapping of this `char` as one or more
     /// `char`s.
     ///
@@ -1204,7 +1302,7 @@ impl char {
     ///
     /// # Note on locale
     ///
-    /// In Turkish, the equivalent of 'i' in Latin has five forms instead of two:
+    /// In Turkish and Azeri, the equivalent of 'i' in Latin has five forms instead of two:
     ///
     /// * 'Dotless': I / ı, sometimes written ï
     /// * 'Dotted': İ / i
@@ -1216,7 +1314,7 @@ impl char {
     /// ```
     ///
     /// The value of `upper_i` here relies on the language of the text: if we're
-    /// in `en-US`, it should be `"I"`, but if we're in `tr_TR`, it should
+    /// in `en-US`, it should be `"I"`, but if we're in `tr-TR` or `az-AZ`, it should
     /// be `"İ"`. `to_uppercase()` does not take this into account, and so:
     ///
     /// ```
@@ -1226,7 +1324,7 @@ impl char {
     /// ```
     ///
     /// holds across languages.
-    #[must_use = "this returns the uppercase character as a new iterator, \
+    #[must_use = "this returns the uppercased character as a new iterator, \
                   without modifying the original"]
     #[stable(feature = "rust1", since = "1.0.0")]
     #[inline]

library/core/src/char/mod.rs

@@ -374,13 +374,21 @@ impl fmt::Display for EscapeDebug {
 }
 
 macro_rules! casemappingiter_impls {
-    ($(#[$attr:meta])* $ITER_NAME:ident) => {
+    (
+        #[$stab:meta]
+        #[$dendstab:meta]
+        #[$fusedstab:meta]
+        #[$exactstab:meta]
+        #[$displaystab:meta]
+        $(#[$attr:meta])*
+        $ITER_NAME:ident
+    ) => {
         $(#[$attr])*
-        #[stable(feature = "rust1", since = "1.0.0")]
+        #[$stab]
         #[derive(Debug, Clone)]
         pub struct $ITER_NAME(CaseMappingIter);
 
-        #[stable(feature = "rust1", since = "1.0.0")]
+        #[$stab]
         impl Iterator for $ITER_NAME {
             type Item = char;
             fn next(&mut self) -> Option<char> {
@@ -416,7 +424,7 @@ macro_rules! casemappingiter_impls {
             }
         }
 
-        #[stable(feature = "case_mapping_double_ended", since = "1.59.0")]
+        #[$dendstab]
         impl DoubleEndedIterator for $ITER_NAME {
             fn next_back(&mut self) -> Option<char> {
                 self.0.next_back()
@@ -434,10 +442,10 @@ macro_rules! casemappingiter_impls {
             }
         }
 
-        #[stable(feature = "fused", since = "1.26.0")]
+        #[$fusedstab]
         impl FusedIterator for $ITER_NAME {}
 
-        #[stable(feature = "exact_size_case_mapping_iter", since = "1.35.0")]
+        #[$exactstab]
         impl ExactSizeIterator for $ITER_NAME {
             fn len(&self) -> usize {
                 self.0.len()
@@ -464,7 +472,7 @@ macro_rules! casemappingiter_impls {
         #[unstable(feature = "std_internals", issue = "none")]
         unsafe impl TrustedRandomAccess for $ITER_NAME {}
 
-        #[stable(feature = "char_struct_display", since = "1.16.0")]
+        #[$displaystab]
         impl fmt::Display for $ITER_NAME {
             fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                 fmt::Display::fmt(&self.0, f)
@@ -474,23 +482,48 @@ macro_rules! casemappingiter_impls {
 }
 
 casemappingiter_impls! {
-    /// Returns an iterator that yields the lowercase equivalent of a `char`.
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[stable(feature = "case_mapping_double_ended", since = "1.59.0")]
+    #[stable(feature = "fused", since = "1.26.0")]
+    #[stable(feature = "exact_size_case_mapping_iter", since = "1.35.0")]
+    #[stable(feature = "char_struct_display", since = "1.16.0")]
+    /// Returns an iterator that yields the uppercase equivalent of a `char`.
     ///
-    /// This `struct` is created by the [`to_lowercase`] method on [`char`]. See
+    /// This `struct` is created by the [`to_uppercase`] method on [`char`]. See
     /// its documentation for more.
     ///
-    /// [`to_lowercase`]: char::to_lowercase
-    ToLowercase
+    /// [`to_uppercase`]: char::to_uppercase
+    ToUppercase
 }
 
 casemappingiter_impls! {
-    /// Returns an iterator that yields the uppercase equivalent of a `char`.
+    #[unstable(feature = "titlecase", issue = "none")]
+    #[unstable(feature = "titlecase", issue = "none")]
+    #[unstable(feature = "titlecase", issue = "none")]
+    #[unstable(feature = "titlecase", issue = "none")]
+    #[unstable(feature = "titlecase", issue = "none")]
+    /// Returns an iterator that yields the titlecase equivalent of a `char`.
     ///
-    /// This `struct` is created by the [`to_uppercase`] method on [`char`]. See
+    /// This `struct` is created by the [`to_titlecase`] method on [`char`]. See
     /// its documentation for more.
     ///
-    /// [`to_uppercase`]: char::to_uppercase
-    ToUppercase
+    /// [`to_titlecase`]: char::to_titlecase
+    ToTitlecase
+}
+
+casemappingiter_impls! {
+    #[stable(feature = "rust1", since = "1.0.0")]
+    #[stable(feature = "case_mapping_double_ended", since = "1.59.0")]
+    #[stable(feature = "fused", since = "1.26.0")]
+    #[stable(feature = "exact_size_case_mapping_iter", since = "1.35.0")]
+    #[stable(feature = "char_struct_display", since = "1.16.0")]
+    /// Returns an iterator that yields the lowercase equivalent of a `char`.
+    ///
+    /// This `struct` is created by the [`to_lowercase`] method on [`char`]. See
+    /// its documentation for more.
+    ///
+    /// [`to_lowercase`]: char::to_lowercase
+    ToLowercase
 }
 
 #[derive(Debug, Clone)]

library/core/src/unicode/unicode_data.rs

@@ -616,7 +616,24 @@ pub mod conversions {
         }
     }
 
-    static LOWERCASE_TABLE: &[(char, u32)] = &[
+    pub fn to_title(c: char) -> [char; 3] {
+        if c.is_ascii() {
+            [(c as u8).to_ascii_uppercase() as char, '\0', '\0']
+        } else {
+            TITLECASE_TABLE
+                .binary_search_by(|&(key, _)| key.cmp(&c))
+                .map(|i| {
+                    let u = TITLECASE_TABLE[i].1;
+                    char::from_u32(u).map(|c| [c, '\0', '\0']).unwrap_or_else(|| {
+                        // SAFETY: Index comes from statically generated table
+                        unsafe { *TITLECASE_TABLE_MULTI.get_unchecked((u & (INDEX_MASK - 1)) as usize) }
+                    })
+                })
+                .unwrap_or(to_upper(c))
+        }
+    }
+
+    static LOWERCASE_TABLE: [(char, u32); 1407] = [
         ('\u{c0}', 224), ('\u{c1}', 225), ('\u{c2}', 226), ('\u{c3}', 227), ('\u{c4}', 228),
         ('\u{c5}', 229), ('\u{c6}', 230), ('\u{c7}', 231), ('\u{c8}', 232), ('\u{c9}', 233),
         ('\u{ca}', 234), ('\u{cb}', 235), ('\u{cc}', 236), ('\u{cd}', 237), ('\u{ce}', 238),
@@ -959,11 +976,11 @@ pub mod conversions {
         ('\u{1e920}', 125250), ('\u{1e921}', 125251),
     ];
 
-    static LOWERCASE_TABLE_MULTI: &[[char; 3]] = &[
+    static LOWERCASE_TABLE_MULTI: [[char; 3]; 1] = [
         ['i', '\u{307}', '\u{0}'],
     ];
 
-    static UPPERCASE_TABLE: &[(char, u32)] = &[
+    static UPPERCASE_TABLE: [(char, u32); 1499] = [
         ('\u{b5}', 924), ('\u{df}', 4194304), ('\u{e0}', 192), ('\u{e1}', 193), ('\u{e2}', 194),
         ('\u{e3}', 195), ('\u{e4}', 196), ('\u{e5}', 197), ('\u{e6}', 198), ('\u{e7}', 199),
         ('\u{e8}', 200), ('\u{e9}', 201), ('\u{ea}', 202), ('\u{eb}', 203), ('\u{ec}', 204),
@@ -1330,7 +1347,7 @@ pub mod conversions {
         ('\u{1e942}', 125216), ('\u{1e943}', 125217),
     ];
 
-    static UPPERCASE_TABLE_MULTI: &[[char; 3]] = &[
+    static UPPERCASE_TABLE_MULTI: [[char; 3]; 102] = [
         ['S', 'S', '\u{0}'], ['\u{2bc}', 'N', '\u{0}'], ['J', '\u{30c}', '\u{0}'],
         ['\u{399}', '\u{308}', '\u{301}'], ['\u{3a5}', '\u{308}', '\u{301}'],
         ['\u{535}', '\u{552}', '\u{0}'], ['H', '\u{331}', '\u{0}'], ['T', '\u{308}', '\u{0}'],
@@ -1380,4 +1397,53 @@ pub mod conversions {
         ['\u{544}', '\u{53b}', '\u{0}'], ['\u{54e}', '\u{546}', '\u{0}'],
         ['\u{544}', '\u{53d}', '\u{0}'],
     ];
+
+    static TITLECASE_TABLE: [(char, u32); 135] = [
+        ('\u{df}', 4194304), ('\u{1c4}', 453), ('\u{1c5}', 453), ('\u{1c6}', 453),
+        ('\u{1c7}', 456), ('\u{1c8}', 456), ('\u{1c9}', 456), ('\u{1ca}', 459), ('\u{1cb}', 459),
+        ('\u{1cc}', 459), ('\u{1f1}', 498), ('\u{1f2}', 498), ('\u{1f3}', 498),
+        ('\u{587}', 4194305), ('\u{10d0}', 4304), ('\u{10d1}', 4305), ('\u{10d2}', 4306),
+        ('\u{10d3}', 4307), ('\u{10d4}', 4308), ('\u{10d5}', 4309), ('\u{10d6}', 4310),
+        ('\u{10d7}', 4311), ('\u{10d8}', 4312), ('\u{10d9}', 4313), ('\u{10da}', 4314),
+        ('\u{10db}', 4315), ('\u{10dc}', 4316), ('\u{10dd}', 4317), ('\u{10de}', 4318),
+        ('\u{10df}', 4319), ('\u{10e0}', 4320), ('\u{10e1}', 4321), ('\u{10e2}', 4322),
+        ('\u{10e3}', 4323), ('\u{10e4}', 4324), ('\u{10e5}', 4325), ('\u{10e6}', 4326),
+        ('\u{10e7}', 4327), ('\u{10e8}', 4328), ('\u{10e9}', 4329), ('\u{10ea}', 4330),
+        ('\u{10eb}', 4331), ('\u{10ec}', 4332), ('\u{10ed}', 4333), ('\u{10ee}', 4334),
+        ('\u{10ef}', 4335), ('\u{10f0}', 4336), ('\u{10f1}', 4337), ('\u{10f2}', 4338),
+        ('\u{10f3}', 4339), ('\u{10f4}', 4340), ('\u{10f5}', 4341), ('\u{10f6}', 4342),
+        ('\u{10f7}', 4343), ('\u{10f8}', 4344), ('\u{10f9}', 4345), ('\u{10fa}', 4346),
+        ('\u{10fd}', 4349), ('\u{10fe}', 4350), ('\u{10ff}', 4351), ('\u{1f80}', 8072),
+        ('\u{1f81}', 8073), ('\u{1f82}', 8074), ('\u{1f83}', 8075), ('\u{1f84}', 8076),
+        ('\u{1f85}', 8077), ('\u{1f86}', 8078), ('\u{1f87}', 8079), ('\u{1f88}', 8072),
+        ('\u{1f89}', 8073), ('\u{1f8a}', 8074), ('\u{1f8b}', 8075), ('\u{1f8c}', 8076),
+        ('\u{1f8d}', 8077), ('\u{1f8e}', 8078), ('\u{1f8f}', 8079), ('\u{1f90}', 8088),
+        ('\u{1f91}', 8089), ('\u{1f92}', 8090), ('\u{1f93}', 8091), ('\u{1f94}', 8092),
+        ('\u{1f95}', 8093), ('\u{1f96}', 8094), ('\u{1f97}', 8095), ('\u{1f98}', 8088),
+        ('\u{1f99}', 8089), ('\u{1f9a}', 8090), ('\u{1f9b}', 8091), ('\u{1f9c}', 8092),
+        ('\u{1f9d}', 8093), ('\u{1f9e}', 8094), ('\u{1f9f}', 8095), ('\u{1fa0}', 8104),
+        ('\u{1fa1}', 8105), ('\u{1fa2}', 8106), ('\u{1fa3}', 8107), ('\u{1fa4}', 8108),
+        ('\u{1fa5}', 8109), ('\u{1fa6}', 8110), ('\u{1fa7}', 8111), ('\u{1fa8}', 8104),
+        ('\u{1fa9}', 8105), ('\u{1faa}', 8106), ('\u{1fab}', 8107), ('\u{1fac}', 8108),
+        ('\u{1fad}', 8109), ('\u{1fae}', 8110), ('\u{1faf}', 8111), ('\u{1fb2}', 4194306),
+        ('\u{1fb3}', 8124), ('\u{1fb4}', 4194307), ('\u{1fb7}', 4194308), ('\u{1fbc}', 8124),
+        ('\u{1fc2}', 4194309), ('\u{1fc3}', 8140), ('\u{1fc4}', 4194310), ('\u{1fc7}', 4194311),
+        ('\u{1fcc}', 8140), ('\u{1ff2}', 4194312), ('\u{1ff3}', 8188), ('\u{1ff4}', 4194313),
+        ('\u{1ff7}', 4194314), ('\u{1ffc}', 8188), ('\u{fb00}', 4194315), ('\u{fb01}', 4194316),
+        ('\u{fb02}', 4194317), ('\u{fb03}', 4194318), ('\u{fb04}', 4194319), ('\u{fb05}', 4194320),
+        ('\u{fb06}', 4194321), ('\u{fb13}', 4194322), ('\u{fb14}', 4194323), ('\u{fb15}', 4194324),
+        ('\u{fb16}', 4194325), ('\u{fb17}', 4194326),
+    ];
+
+    static TITLECASE_TABLE_MULTI: [[char; 3]; 23] = [
+        ['S', 's', '\u{0}'], ['\u{535}', '\u{582}', '\u{0}'], ['\u{1fba}', '\u{345}', '\u{0}'],
+        ['\u{386}', '\u{345}', '\u{0}'], ['\u{391}', '\u{342}', '\u{345}'],
+        ['\u{1fca}', '\u{345}', '\u{0}'], ['\u{389}', '\u{345}', '\u{0}'],
+        ['\u{397}', '\u{342}', '\u{345}'], ['\u{1ffa}', '\u{345}', '\u{0}'],
+        ['\u{38f}', '\u{345}', '\u{0}'], ['\u{3a9}', '\u{342}', '\u{345}'], ['F', 'f', '\u{0}'],
+        ['F', 'i', '\u{0}'], ['F', 'l', '\u{0}'], ['F', 'f', 'i'], ['F', 'f', 'l'],
+        ['S', 't', '\u{0}'], ['S', 't', '\u{0}'], ['\u{544}', '\u{576}', '\u{0}'],
+        ['\u{544}', '\u{565}', '\u{0}'], ['\u{544}', '\u{56b}', '\u{0}'],
+        ['\u{54e}', '\u{576}', '\u{0}'], ['\u{544}', '\u{56d}', '\u{0}'],
+    ];
 }