Document strip_circumfix behavior on overlapping prefix and suffix.

library/core/src/slice/mod.rs

@@ -2738,10 +2738,12 @@ impl<T> [T] {
 
     /// Returns a subslice with the prefix and suffix removed.
     ///
-    /// If the slice starts with `prefix` and ends with `suffix`, returns the subslice after the
-    /// prefix and before the suffix, wrapped in `Some`.
+    /// If the slice starts with `prefix`, ends with `suffix`, and
+    /// the prefix and suffix don't overlap, returns the subslice after
+    /// the prefix and before the suffix, wrapped in `Some`.
     ///
-    /// If the slice does not start with `prefix` or does not end with `suffix`, returns `None`.
+    /// If the slice does not start with `prefix`, does not end with `suffix`,
+    /// or the prefix and suffix overlap in the slice, returns `None`.
     ///
     /// # Examples
     ///
@@ -2754,6 +2756,7 @@ impl<T> [T] {
     /// assert_eq!(v.strip_circumfix(&[10], &[40]), None);
     /// assert_eq!(v.strip_circumfix(&[], &[40, 30]), Some(&[10, 50][..]));
     /// assert_eq!(v.strip_circumfix(&[10, 50], &[]), Some(&[40, 30][..]));
+    /// assert_eq!(v.strip_circumfix(&[10, 50, 40], &[50, 40, 30]), None);
     /// ```
     #[must_use = "returns the subslice without modifying the original"]
     #[stable(feature = "strip_circumfix", since = "CURRENT_RUSTC_VERSION")]

library/core/src/str/mod.rs

@@ -2492,12 +2492,14 @@ impl str {
 
     /// Returns a string slice with the prefix and suffix removed.
     ///
-    /// If the string starts with the pattern `prefix` and ends with the pattern `suffix`, returns
+    /// If the string starts with the pattern `prefix` and ends with
+    /// the pattern `suffix`, and the prefix and suffix don't overlap, returns
     /// the substring after the prefix and before the suffix, wrapped in `Some`.
     /// Unlike [`trim_start_matches`] and [`trim_end_matches`], this method removes both the prefix
     /// and suffix exactly once.
     ///
-    /// If the string does not start with `prefix` or does not end with `suffix`, returns `None`.
+    /// If the string does not start with `prefix`, does not end with `suffix`,
+    /// or the prefix and suffix overlap in the string, returns `None`.
     ///
     /// Each [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
@@ -2513,6 +2515,7 @@ impl str {
     /// assert_eq!("bar:hello:foo".strip_circumfix("bar:", ":foo"), Some("hello"));
     /// assert_eq!("bar:foo".strip_circumfix("foo", "foo"), None);
     /// assert_eq!("foo:bar;".strip_circumfix("foo:", ';'), Some("bar"));
+    /// assert_eq!("foo:bar:baz".strip_circumfix("foo:bar:", ":bar:baz"), None);
     /// ```
     #[must_use = "this returns the remaining substring as a new slice, \
                   without modifying the original"]