Repository: rust
Issue: Tracking Issue for `remainder` methods for `str` split iterators
Labels: T-libs-api,B-unstable,C-tracking-issue,A-iterators,A-str,Libs-Tracked

<!--
Thank you for creating a tracking issue! 📜 Tracking issues are for tracking a
feature from implementation to stabilisation. Make sure to include the relevant
RFC for the feature if it has one. Otherwise provide a short summary of the
feature and link any relevant PRs or issues, and remove any sections that are
not relevant to the feature.

Remember to add team labels to the tracking issue.
For a language team feature, this would e.g., be `T-lang`.
Such a feature should also be labeled with e.g., `F-my_feature`.
This label is used to associate issues (e.g., bugs and design questions) to the feature.
-->

This is a tracking issue for the methods implemented in #75265 and #82570, which allow viewing the remainder of the underlying string in str-split iterators. E.g.:

```rust
let mut split = "Mary had a little lamb".split(' '); 
assert_eq!(split.remainder(), Some("Mary had a little lamb"));

_ = split.next();
assert_eq!(split.remainder(), Some("had a little lamb"));

split.by_ref().for_each(drop);
assert_eq!(split.remainder(), None);
```

The feature gates for the issue are `#![feature(str_split_remainder)]` (for most split iterators), `#![feature(str_split_inclusive_remainder)]` (for `SplitInclusive`) and `#![feature(str_split_whitespace_remainder)]` (for `SplitWhitespace` and `SplitAsciiWhitespace`).

### Public API

```rust
// mod core::str
impl<'a, P: Pattern<'a>> Split<'a, P> {
    fn remainder(&self) -> Option<&'a str>;
}

// And the same for
// - `RSplit<'a, P>`
// - `SplitTerminator<'a, P>`
// - `RSplitTerminator<'a, P>`
// - `SplitN<'a, P>`
// - `RSplitN<'a, P>`
// - `SplitWhitespace<'a>`
// - `SplitAsciiWhitespace<'a>`
// - `SplitInclusive<'a, P>`
```

### Steps
<!--
Include each step required to complete the feature. Typically this is a PR
implementing a feature, followed by a PR that stabilises the feature. However
for larger features an implementation could be broken up into multiple PRs.
-->

- [x] Implement the feature
- [x] Adjust documentation ([see instructions on rustc-dev-guide][doc-guide])
- [ ] Stabilization PR ([see instructions on rustc-dev-guide][stabilization-guide])

[stabilization-guide]: https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#stabilization-pr
[doc-guide]: https://rustc-dev-guide.rust-lang.org/stabilization_guide.html#documentation-prs

### Unresolved Questions
<!--
Include any open questions that need to be answered before the feature can be
stabilised.
-->

- ~~Should empty strings point to the end of the haystack, or they can be arbitrary constants? (see https://github.com/rust-lang/rust/pull/75265#discussion_r487358752)~~ `None` is now returned instead of an empty string, making this irrelevant

### Implementation history

- #75265 — implemented `as_str` methods on `core::str::{Split,RSplit,SplitN,RSplitN,SplitTerminator,RSplitTerminator,SplitInclusive}`

- #82570 — implemented `as_str` methods on `core::str::{SplitWhitespace, SplitAsciiWhitespace}`
- #95644 — renamed `as_str`=>`remainder` and changed return type to `Option<&str>`