Add String::replace_first and String::replace_last

Author: WilliamVenner

library/alloc/src/lib.rs

@@ -139,6 +139,7 @@
 #![feature(ptr_metadata)]
 #![feature(ptr_sub_ptr)]
 #![feature(receiver_trait)]
+#![feature(string_replace_in_place)]
 #![feature(set_ptr_value)]
 #![feature(sized_type_properties)]
 #![feature(slice_from_ptr_range)]

library/alloc/src/string.rs

@@ -1985,6 +1985,63 @@ impl String {
         unsafe { self.as_mut_vec() }.splice((start, end), replace_with.bytes());
     }
 
+    /// Replaces the leftmost occurrence of a pattern with another string, in-place.
+    ///
+    /// This method should be preferred over [`String::replacen(..., 1)`](str::replacen) as it can use the `String`'s existing capacity to prevent a reallocation if sufficient space is available.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// #![feature(string_replace_in_place)]
+    ///
+    /// let mut s = String::from("Test Results: ❌❌❌");
+    ///
+    /// // Replace the leftmost ❌ with a ✅
+    /// s.replace_first('❌', "✅");
+    /// assert_eq!(s, "Test Results: ✅❌❌");
+    /// ```
+    #[cfg(not(no_global_oom_handling))]
+    #[unstable(feature = "string_replace_in_place", issue = "none")]
+    pub fn replace_first<P: for<'a> Pattern<'a>>(&mut self, from: P, to: &str) {
+        let range = match self.match_indices(from).next() {
+            Some((start, match_str)) => start..start + match_str.len(),
+            None => return,
+        };
+
+        self.replace_range(range, to);
+    }
+
+    /// Replaces the rightmost occurrence of a pattern with another string, in-place.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// #![feature(string_replace_in_place)]
+    ///
+    /// let mut s = String::from("Test Results: ❌❌❌");
+    ///
+    /// // Replace the rightmost ❌ with a ✅
+    /// s.replace_last::<char>('❌', "✅");
+    /// assert_eq!(s, "Test Results: ❌❌✅");
+    /// ```
+    #[cfg(not(no_global_oom_handling))]
+    #[unstable(feature = "string_replace_in_place", issue = "none")]
+    pub fn replace_last<P>(&mut self, from: P, to: &str)
+    where
+        P: for<'a> Pattern<'a, Searcher: str::pattern::ReverseSearcher<'a>>,
+    {
+        let range = match self.rmatch_indices(from).next() {
+            Some((start, match_str)) => start..start + match_str.len(),
+            None => return,
+        };
+
+        self.replace_range(range, to);
+    }
+
     /// Converts this `String` into a <code>[Box]<[str]></code>.
     ///
     /// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`].

library/alloc/tests/lib.rs

@@ -28,6 +28,7 @@
 #![feature(iter_next_chunk)]
 #![feature(round_char_boundary)]
 #![feature(slice_partition_dedup)]
+#![feature(string_replace_in_place)]
 #![feature(string_remove_matches)]
 #![feature(const_btree_len)]
 #![feature(const_trait_impl)]

library/alloc/tests/string.rs

@@ -682,6 +682,40 @@ fn test_replace_range_evil_end_bound() {
     assert_eq!(Ok(""), str::from_utf8(s.as_bytes()));
 }
 
+#[test]
+fn test_replace_first() {
+    let mut s = String::from("~ First ❌ Middle ❌ Last ❌ ~");
+    s.replace_first("❌", "✅✅");
+    assert_eq!(s, "~ First ✅✅ Middle ❌ Last ❌ ~");
+    s.replace_first("🦀", "😳");
+    assert_eq!(s, "~ First ✅✅ Middle ❌ Last ❌ ~");
+
+    let mut s = String::from("❌");
+    s.replace_first('❌', "✅✅");
+    assert_eq!(s, "✅✅");
+
+    let mut s = String::from("");
+    s.replace_first('🌌', "❌");
+    assert_eq!(s, "");
+}
+
+#[test]
+fn test_replace_last() {
+    let mut s = String::from("~ First ❌ Middle ❌ Last ❌ ~");
+    s.replace_last::<&str>("❌", "✅✅");
+    assert_eq!(s, "~ First ❌ Middle ❌ Last ✅✅ ~");
+    s.replace_last::<&str>("🦀", "😳");
+    assert_eq!(s, "~ First ❌ Middle ❌ Last ✅✅ ~");
+
+    let mut s = String::from("❌");
+    s.replace_last::<char>('❌', "✅✅");
+    assert_eq!(s, "✅✅");
+
+    let mut s = String::from("");
+    s.replace_last::<char>('🌌', "❌");
+    assert_eq!(s, "");
+}
+
 #[test]
 fn test_extend_ref() {
     let mut a = "foo".to_string();