rust/src/liballoc
bors 87e494c4cd Auto merge of #67330 - golddranks:split_inclusive, r=kodraus
Implement split_inclusive for slice and str

# Overview
* Implement `split_inclusive` for `slice` and `str` and `split_inclusive_mut` for `slice`
* `split_inclusive` is a substring/subslice splitting iterator that includes the matched part in the iterated substrings as a terminator.
* EDIT: The behaviour has now changed, as per @KodrAus 's input, to the same semantics with the `split_terminator` function. I updated the examples below.
* Two examples below:
```Rust
    let data = "\nMäry häd ä little lämb\nLittle lämb\n";
    let split: Vec<&str> = data.split_inclusive('\n').collect();
    assert_eq!(split, ["\n", "Märy häd ä little lämb\n", "Little lämb\n"]);
```

```Rust
    let uppercase_separated = "SheePSharKTurtlECaT";
    let mut first_char = true;
    let split: Vec<&str> = uppercase_separated.split_inclusive(|c: char| {
        let split = !first_char && c.is_uppercase();
        first_char = split;
        split
    }).collect();
    assert_eq!(split, ["SheeP", "SharK", "TurtlE", "CaT"]);
```

# Justification for the API
* I was surprised to find that stdlib currently only has splitting iterators that leave out the matched part. In my experience, wanting to leave a substring terminator as a part of the substring is a pretty common usecase.
* This API is strictly more expressive than the standard `split` API: it's easy to get the behaviour of `split` by mapping a subslicing operation that drops the terminator. On the other hand it's impossible to derive this behaviour from `split` without using hacky and brittle `unsafe` code. The normal way to achieve this functionality would be implementing the iterator yourself.
* Especially when dealing with mutable slices, the only way currently is to use `split_at_mut`. This API provides an ergonomic alternative that plays to the strengths of the iterating capabilities of Rust. (Using `split_at_mut` iteratively used to be a real pain before NLL, fortunately the situation is a bit better now.)

# Discussion items
* <s>Does it make sense to mimic `split_terminator` in that the final empty slice would be left off in case of the string/slice ending with a terminator? It might do, as this use case is naturally geared towards considering the matching part as a terminator instead of a separator.</s>
  * EDIT: The behaviour was changed to mimic `split_terminator`.
* Does it make sense to have `split_inclusive_mut` for `&mut str`?
2020-02-22 03:54:50 +00:00
..
alloc liballoc: ignore tests in Miri instead of removing them entirely 2019-12-07 12:42:19 +01:00
benches Create benchmarks for BTreeMap::range 2020-02-07 00:57:54 +01:00
collections Rollup merge of #68705 - BijanT:ll_remove, r=Mark-Simulacrum 2020-02-20 10:49:08 +01:00
prelude Format liballoc with rustfmt 2019-11-29 20:25:07 -08:00
raw_vec Rename Alloc to AllocRef 2020-01-27 21:39:51 +01:00
rc Format the world 2019-12-22 17:42:47 -05:00
sync Format the world 2019-12-22 17:42:47 -05:00
tests Auto merge of #67330 - golddranks:split_inclusive, r=kodraus 2020-02-22 03:54:50 +00:00
alloc.rs Preparation for allocator aware Box 2020-02-11 13:16:20 +01:00
borrow.rs Format the world 2019-12-22 17:42:47 -05:00
boxed.rs Preparation for allocator aware Box 2020-02-11 13:16:20 +01:00
Cargo.toml bump rand to fix Miri failures 2019-08-04 14:50:26 +02:00
fmt.rs Remove redundant link texts 2019-12-26 05:04:46 -08:00
lib.rs Add #![doc(html_playground_url = ...)] to alloc crate 2020-01-30 21:14:39 +00:00
macros.rs Scope format! temporaries 2019-09-27 17:36:45 -04:00
raw_vec.rs Remove common usage pattern from AllocRef 2020-02-10 18:38:09 +01:00
rc.rs Rename Alloc to AllocRef 2020-01-27 21:39:51 +01:00
slice.rs reuse capacity variable in slice::repeat 2019-12-24 12:44:05 +08:00
str.rs Format the world 2019-12-22 17:42:47 -05:00
string.rs Change FromStr for String to use Infallible directly 2020-02-19 16:37:58 -05:00
sync.rs Rename Alloc to AllocRef 2020-01-27 21:39:51 +01:00
tests.rs Format liballoc with rustfmt 2019-11-29 20:25:07 -08:00
vec.rs Fixed issue 68593 2020-01-31 13:41:07 -06:00