Add String::replace_first and String::replace_last

library/alloc/src/lib.rs

@@ -92,6 +92,7 @@
 // Library features:
 // tidy-alphabetical-start
 #![cfg_attr(bootstrap, feature(async_closure))]
+#![cfg_attr(not(no_global_oom_handling), feature(string_replace_in_place))]
 #![cfg_attr(test, feature(str_as_str))]
 #![feature(alloc_layout_extra)]
 #![feature(allocator_api)]

library/alloc/src/string.rs

@@ -2003,6 +2003,67 @@ 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)`][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: ✅❌❌");
+    /// ```
+    ///
+    /// [replacen]: ../../std/primitive.str.html#method.replacen
+    #[cfg(not(no_global_oom_handling))]
+    #[unstable(feature = "string_replace_in_place", issue = "none")]
+    pub fn replace_first<P: Pattern>(&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('❌', "✅");
+    /// assert_eq!(s, "Test Results: ❌❌✅");
+    /// ```
+    #[cfg(not(no_global_oom_handling))]
+    #[unstable(feature = "string_replace_in_place", issue = "none")]
+    pub fn replace_last<P: Pattern>(&mut self, from: P, to: &str)
+    where
+        for<'a> P::Searcher<'a>: core::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

@@ -37,6 +37,7 @@
 #![feature(local_waker)]
 #![feature(str_as_str)]
 #![feature(strict_provenance_lints)]
+#![feature(string_replace_in_place)]
 #![feature(vec_pop_if)]
 #![feature(unique_rc_arc)]
 #![feature(macro_metavar_expr_concat)]

library/alloc/tests/string.rs

@@ -710,6 +710,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("❌", "✅✅");
+    assert_eq!(s, "~ First ❌ Middle ❌ Last ✅✅ ~");
+    s.replace_last("🦀", "😳");
+    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();