Add PartialEq impls to the character case iterators

Allows easily checking whether a string is in a particular case

Author: Jules-Bertholet

library/core/src/char/methods.rs

@@ -1076,7 +1076,8 @@ impl char {
     }
 
     /// Returns an iterator that yields the lowercase mapping of this `char` as one or more
-    /// `char`s.
+    /// `char`s. The iterator also has implementations of [`Display`][core::fmt::Display]
+    /// and [`PartialEq`].
     ///
     /// If this `char` does not have a lowercase mapping, the iterator yields the same `char`.
     ///
@@ -1134,6 +1135,13 @@ impl char {
     /// // convert into themselves.
     /// assert_eq!('山'.to_lowercase().to_string(), "山");
     /// ```
+    ///
+    /// Check if a string is in lowercase:
+    ///
+    /// ```
+    /// let s = "abcde\u{0301} 山";
+    /// assert!(s.chars().all(|c| c.to_lowercase() == c));
+    /// ```
     #[must_use = "this returns the lowercased character as a new iterator, \
                   without modifying the original"]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -1143,7 +1151,8 @@ impl char {
     }
 
     /// Returns an iterator that yields the titlecase mapping of this `char` as one or more
-    /// `char`s.
+    /// `char`s. The iterator also has implementations of [`Display`][core::fmt::Display]
+    /// and [`PartialEq`].
     ///
     /// If this `char` does not have an titlecase mapping, the iterator yields the same `char`.
     ///
@@ -1206,6 +1215,21 @@ impl char {
     /// assert_eq!('山'.to_titlecase().to_string(), "山");
     /// ```
     ///
+    /// Check if a word is in titlecase:
+    ///
+    /// ```
+    /// #![feature(titlecase)]
+    /// let word = "Dross";
+    /// let mut chars = word.chars();
+    /// let first_cased_char = chars.find(|c| c.is_cased());
+    /// let word_is_in_titlecase = if let Some(f) = first_cased_char {
+    ///     f.to_titlecase() == f && chars.all(|c| c.to_lowercase() == c)
+    /// } else {
+    ///     true
+    /// };
+    /// assert!(word_is_in_titlecase);
+    /// ```
+    ///
     /// # Note on locale
     ///
     /// In Turkish and Azeri, the equivalent of 'i' in Latin has five forms instead of two:
@@ -1241,7 +1265,8 @@ impl char {
     }
 
     /// Returns an iterator that yields the uppercase mapping of this `char` as one or more
-    /// `char`s.
+    /// `char`s. The iterator also has implementations of [`Display`][core::fmt::Display]
+    /// and [`PartialEq`].
     ///
     /// If this `char` does not have an uppercase mapping, the iterator yields the same `char`.
     ///
@@ -1300,6 +1325,13 @@ impl char {
     /// assert_eq!('山'.to_uppercase().to_string(), "山");
     /// ```
     ///
+    /// Check if a string is in uppercase:
+    ///
+    /// ```
+    /// let s = "ABCDE\u{0301} 山";
+    /// assert!(s.chars().all(|c| c.to_uppercase() == c));
+    /// ```
+    ///
     /// # Note on locale
     ///
     /// In Turkish and Azeri, the equivalent of 'i' in Latin has five forms instead of two:

library/core/src/char/mod.rs

@@ -140,7 +140,7 @@ pub const fn from_digit(num: u32, radix: u32) -> Option<char> {
     self::convert::from_digit(num, radix)
 }
 
-/// Returns an iterator that yields the hexadecimal Unicode escape of a
+/// An iterator that yields the hexadecimal Unicode escape of a
 /// character, as `char`s.
 ///
 /// This `struct` is created by the [`escape_unicode`] method on [`char`]. See
@@ -373,7 +373,9 @@ impl fmt::Display for EscapeDebug {
     }
 }
 
-/// Returns an iterator that yields the lowercase equivalent of a `char`.
+/// An iterator that yields the lowercase equivalent of a `char`.
+/// Also implements [`Display`][`core::fmt::Display`], as well as
+/// [`PartialEq`] with itself, the other case iterators, and [`char`].
 ///
 /// This `struct` is created by the [`to_lowercase`] method on [`char`]. See
 /// its documentation for more.
@@ -414,7 +416,46 @@ impl fmt::Display for ToLowercase {
     }
 }
 
-/// Returns an iterator that yields the titlecase equivalent of a `char`.
+// No reflexive impl because it would break type inference
+#[stable(feature = "case_iter_partialeq", since = "CURRENT_RUSTC_VERSION")]
+impl PartialEq<char> for ToLowercase {
+    #[inline]
+    fn eq(&self, other: &char) -> bool {
+        self.0 == *other
+    }
+}
+
+// Not `derive`d so as not to commit to `StructuralPartialEq`
+#[stable(feature = "case_iter_partialeq", since = "CURRENT_RUSTC_VERSION")]
+impl PartialEq for ToLowercase {
+    #[inline]
+    fn eq(&self, other: &Self) -> bool {
+        self.0 == other.0
+    }
+}
+
+#[stable(feature = "case_iter_partialeq", since = "CURRENT_RUSTC_VERSION")]
+impl Eq for ToLowercase {}
+
+#[unstable(feature = "titlecase", issue = "none")]
+impl PartialEq<ToTitlecase> for ToLowercase {
+    #[inline]
+    fn eq(&self, other: &ToTitlecase) -> bool {
+        self.0 == other.0
+    }
+}
+
+#[stable(feature = "case_iter_partialeq", since = "CURRENT_RUSTC_VERSION")]
+impl PartialEq<ToUppercase> for ToLowercase {
+    #[inline]
+    fn eq(&self, other: &ToUppercase) -> bool {
+        self.0 == other.0
+    }
+}
+
+/// An iterator that yields the titlecase equivalent of a `char`.
+/// Also implements [`Display`][`core::fmt::Display`], as well as
+/// [`PartialEq`] with itself, the other case iterators, and [`char`].
 ///
 /// This `struct` is created by the [`to_titlecase`] method on [`char`]. See
 /// its documentation for more.
@@ -455,7 +496,46 @@ impl fmt::Display for ToTitlecase {
     }
 }
 
-/// Returns an iterator that yields the uppercase equivalent of a `char`.
+// No reflexive impl because it would break type inference
+#[unstable(feature = "titlecase", issue = "none")]
+impl PartialEq<char> for ToTitlecase {
+    #[inline]
+    fn eq(&self, other: &char) -> bool {
+        self.0 == *other
+    }
+}
+
+// Not `derive`d so as not to commit to `StructuralPartialEq`
+#[unstable(feature = "titlecase", issue = "none")]
+impl PartialEq for ToTitlecase {
+    #[inline]
+    fn eq(&self, other: &Self) -> bool {
+        self.0 == other.0
+    }
+}
+
+#[unstable(feature = "titlecase", issue = "none")]
+impl Eq for ToTitlecase {}
+
+#[unstable(feature = "titlecase", issue = "none")]
+impl PartialEq<ToLowercase> for ToTitlecase {
+    #[inline]
+    fn eq(&self, other: &ToLowercase) -> bool {
+        self.0 == other.0
+    }
+}
+
+#[unstable(feature = "titlecase", issue = "none")]
+impl PartialEq<ToUppercase> for ToTitlecase {
+    #[inline]
+    fn eq(&self, other: &ToUppercase) -> bool {
+        self.0 == other.0
+    }
+}
+
+/// An iterator that yields the uppercase equivalent of a `char`.
+/// Also implements [`Display`][`core::fmt::Display`], as well as
+/// [`PartialEq`] with itself, the other case iterators, and [`char`].
 ///
 /// This `struct` is created by the [`to_uppercase`] method on [`char`]. See
 /// its documentation for more.
@@ -496,7 +576,44 @@ impl fmt::Display for ToUppercase {
     }
 }
 
-#[derive(Debug, Clone)]
+// No reflexive impl because it would break type inference
+#[stable(feature = "case_iter_partialeq", since = "CURRENT_RUSTC_VERSION")]
+impl PartialEq<char> for ToUppercase {
+    #[inline]
+    fn eq(&self, other: &char) -> bool {
+        self.0 == *other
+    }
+}
+
+// Not `derive`d so as not to commit to `StructuralPartialEq`
+#[stable(feature = "case_iter_partialeq", since = "CURRENT_RUSTC_VERSION")]
+impl PartialEq for ToUppercase {
+    #[inline]
+    fn eq(&self, other: &Self) -> bool {
+        self.0 == other.0
+    }
+}
+
+#[stable(feature = "case_iter_partialeq", since = "CURRENT_RUSTC_VERSION")]
+impl Eq for ToUppercase {}
+
+#[stable(feature = "case_iter_partialeq", since = "CURRENT_RUSTC_VERSION")]
+impl PartialEq<ToLowercase> for ToUppercase {
+    #[inline]
+    fn eq(&self, other: &ToLowercase) -> bool {
+        self.0 == other.0
+    }
+}
+
+#[unstable(feature = "titlecase", issue = "none")]
+impl PartialEq<ToTitlecase> for ToUppercase {
+    #[inline]
+    fn eq(&self, other: &ToTitlecase) -> bool {
+        self.0 == other.0
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
 enum CaseMappingIter {
     Three(char, char, char),
     Two(char, char),
@@ -587,6 +704,13 @@ impl fmt::Display for CaseMappingIter {
     }
 }
 
+impl PartialEq<char> for CaseMappingIter {
+    #[inline]
+    fn eq(&self, other: &char) -> bool {
+        if let CaseMappingIter::One(c) = self { *c == *other } else { false }
+    }
+}
+
 /// The error type returned when a checked char conversion fails.
 #[stable(feature = "u8_from_char", since = "1.59.0")]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]