`strip_circumfix` behavior doesn't match docs when prefix and suffix overlap.

[theemathas]

The str::strip_circumfix docs says:

If the string starts with the pattern prefix and ends with the pattern suffix, returns the substring after the prefix and before the suffix, wrapped in Some.

Similarly, the slice::strip_circumfix docs says:

If the slice starts with prefix and ends with suffix, returns the subslice after the prefix and before the suffix, wrapped in Some.

These documentation texts are problematic when the prefix and the suffix string overlap. For example:

fn main() {
    let s = "abcde";
    let stripped = s.strip_circumfix("abc", "cde");
    println!("{stripped:?}");
}

The above code outputs None. However, since the string does in fact start with the prefix, and end with the suffix, then arguably, the docs say that the method should return Some.

The same behavior occurs with slices.

Example code using slices instead of strings

fn main() {
    let s = [0, 1, 2, 3, 4];
    let stripped = s.strip_circumfix(&[0, 1, 2], &[2, 3, 4]);
    println!("{stripped:?}");
}

The above code outputs None.

I'm not sure whether the docs or the behavior is incorrect, though.

Note that these two methods has just been recently stabilized in nightly in the PR #158012 (tracking issue: #147946). Therefore, I'm nominating this issue for discussion.

Meta

Reproducible on the playground with version 1.98.0-nightly (2026-06-23 f28ac764c36004fa6a6e)

[Urgau]

I think both the behavior and the documentation are right.

The documentation states that it returns:

substring after the prefix and before the suffix

Which is impossible to statisfy when they overlap. In your example there isn't any substring that is both after and before the prefix and suffix. (Backward slices don't exist after all)

[asquared31415]

This probably warrants a "if the prefix and suffix are both found, but overlap (the end of the prefix occurs after the start of the suffix), None is returned." clarification, even if it's technically redundant. One could imagine an empty string/slice being returned in that case, so might as well clarify.

[Amanieu]

Discussed this in the @rust-lang/libs-api meeting: we agree that this just needs a clarification in the documentation that says that None is returned if the prefix and suffix overlap.