rust/library/core/tests
Matthias Krüger 64461dab01
Rollup merge of #117561 - tgross35:split-array, r=scottmcm
Stabilize `slice_first_last_chunk`

This PR does a few different things based around stabilizing `slice_first_last_chunk`. They are split up so this PR can be by-commit reviewed, I can move parts to a separate PR if desired.

This feature provides a very elegant API to extract arrays from either end of a slice, such as for parsing integers from binary data.

## Stabilize `slice_first_last_chunk`

ACP: https://github.com/rust-lang/libs-team/issues/69
Implementation: https://github.com/rust-lang/rust/issues/90091
Tracking issue: https://github.com/rust-lang/rust/issues/111774

This stabilizes the functionality from https://github.com/rust-lang/rust/issues/111774:

```rust
impl [T] {
    pub const fn first_chunk<const N: usize>(&self) -> Option<&[T; N]>;
    pub fn first_chunk_mut<const N: usize>(&mut self) -> Option<&mut [T; N]>;
    pub const fn last_chunk<const N: usize>(&self) -> Option<&[T; N]>;
    pub fn last_chunk_mut<const N: usize>(&mut self) -> Option<&mut [T; N]>;
    pub const fn split_first_chunk<const N: usize>(&self) -> Option<(&[T; N], &[T])>;
    pub fn split_first_chunk_mut<const N: usize>(&mut self) -> Option<(&mut [T; N], &mut [T])>;
    pub const fn split_last_chunk<const N: usize>(&self) -> Option<(&[T], &[T; N])>;
    pub fn split_last_chunk_mut<const N: usize>(&mut self) -> Option<(&mut [T], &mut [T; N])>;
}
```

Const stabilization is included for all non-mut methods, which are blocked on `const_mut_refs`. This change includes marking the trivial function `slice_split_at_unchecked` const-stable for internal use (but not fully stable).

## Remove `split_array` slice methods

Tracking issue: https://github.com/rust-lang/rust/issues/90091
Implementation: https://github.com/rust-lang/rust/pull/83233#pullrequestreview-780315524

This PR also removes the following unstable methods from the `split_array` feature, https://github.com/rust-lang/rust/issues/90091:

```rust
impl<T> [T] {
    pub fn split_array_ref<const N: usize>(&self) -> (&[T; N], &[T]);
    pub fn split_array_mut<const N: usize>(&mut self) -> (&mut [T; N], &mut [T]);

    pub fn rsplit_array_ref<const N: usize>(&self) -> (&[T], &[T; N]);
    pub fn rsplit_array_mut<const N: usize>(&mut self) -> (&mut [T], &mut [T; N]);
}
```

This is done because discussion at #90091 and its implementation PR indicate a strong preference for nonpanicking APIs that return `Option`. The only difference between functions under the `split_array` and `slice_first_last_chunk` features is `Option` vs. panic, so remove the duplicates as part of this stabilization.

This does not affect the array methods from `split_array`. We will want to revisit these once `generic_const_exprs` is further along.

## Reverse order of return tuple for `split_last_chunk{,_mut}`

An unresolved question for #111774 is whether to return `(preceding_slice, last_chunk)` (`(&[T], &[T; N])`) or the reverse (`(&[T; N], &[T])`), from `split_last_chunk` and `split_last_chunk_mut`. It is currently implemented as `(last_chunk, preceding_slice)` which matches `split_last -> (&T, &[T])`. The first commit changes these to `(&[T], &[T; N])` for these reasons:

- More consistent with other splitting methods that return multiple values: `str::rsplit_once`, `slice::split_at{,_mut}`, `slice::align_to` all return tuples with the items in order
- More intuitive (arguably opinion, but it is consistent with other language elements like pattern matching `let [a, b, rest @ ..] ...`
- If we ever added a varidic way to obtain multiple chunks, it would likely return something in order: `.split_many_last::<(2, 4)>() -> (&[T], &[T; 2], &[T; 4])`
- It is the ordering used in the `rsplit_array` methods

I think the inconsistency with `split_last` could be acceptable in this case, since for `split_last` the scalar `&T` doesn't have any internal order to maintain with the other items.

## Unresolved questions

Do we want to reserve the same names on `[u8; N]` to avoid inference confusion? https://github.com/rust-lang/rust/pull/117561#issuecomment-1793388647

---

`slice_first_last_chunk` has only been around since early 2023, but `split_array` has been around since 2021.

`@rustbot` label -T-libs +T-libs-api -T-libs +needs-fcp
cc `@rust-lang/wg-const-eval,` `@scottmcm` who raised this topic, `@clarfonthey` implementer of `slice_first_last_chunk` `@jethrogb` implementer of `split_array`

Zulip discussion: https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/topic/Stabilizing.20array-from-slice.20*something*.3F

Fixes: #111774
2024-01-19 19:26:59 +01:00
..
async_iter Add IntoAsyncIterator 2023-12-22 11:01:05 -08:00
fmt apply fmt 2024-01-11 15:04:48 +03:00
hash apply fmt 2024-01-11 15:04:48 +03:00
io Move BorrowedBuf and BorrowedCursor from std:io to core::io 2023-11-09 07:10:11 +09:00
iter apply fmt 2024-01-11 15:04:48 +03:00
net apply fmt 2024-01-11 15:04:48 +03:00
num remove redundant imports 2023-12-10 10:56:22 +08:00
ops Expand the docs for ops::ControlFlow a bit 2021-02-06 22:36:05 -08:00
panic Fix test (location_const_file) 2022-10-08 11:48:53 +00:00
alloc.rs Re-optimize Layout::array 2022-07-13 17:07:41 -07:00
any.rs Adjust library tests for unused_tuple_struct_fields -> dead_code 2024-01-02 15:34:37 -05:00
array.rs apply fmt 2024-01-11 15:04:48 +03:00
ascii.rs introduce {char, u8}::is_ascii_octdigit 2022-09-27 11:55:13 +05:30
asserting.rs Spelling library/ 2023-04-26 02:10:22 -04:00
atomic.rs Adjust library tests for unused_tuple_struct_fields -> dead_code 2024-01-02 15:34:37 -05:00
bool.rs fix library and rustdoc tests 2023-04-16 11:38:52 +00:00
cell.rs apply fmt 2024-01-11 15:04:48 +03:00
char.rs remove redundant imports 2023-12-10 10:56:22 +08:00
clone.rs Bump to latest beta compiler 2023-05-30 08:00:10 -04:00
cmp.rs fix library and rustdoc tests 2023-04-16 11:38:52 +00:00
const_ptr.rs cleanup code w/ pointers in std a little 2022-08-05 16:47:49 +04:00
convert.rs fix library and rustdoc tests 2023-04-16 11:38:52 +00:00
error.rs apply fmt 2024-01-11 15:04:48 +03:00
future.rs enable test_join test in Miri 2023-07-03 14:05:55 +02:00
intrinsics.rs Adjust library tests for unused_tuple_struct_fields -> dead_code 2024-01-02 15:34:37 -05:00
lazy.rs Rollup merge of #110419 - jsoref:spelling-library, r=jyn514 2023-04-26 18:51:41 +02:00
lib.rs Stabilize slice_first_last_chunk 2024-01-10 03:06:49 -05:00
macros.rs Add the cfg_match! macro 2023-09-23 14:23:51 -03:00
manually_drop.rs Flip cfg's for bootstrap bump 2023-07-12 21:38:55 -04:00
mem.rs Stabilize const_maybe_uninit_zeroed 2023-11-04 15:27:25 -04:00
nonzero.rs remove redundant imports 2023-12-10 10:56:22 +08:00
ops.rs Test not never 2021-11-21 19:10:39 -08:00
option.rs apply fmt 2024-01-11 15:04:48 +03:00
panic.rs Add newlines 2022-09-27 19:23:52 +00:00
pattern.rs mv std libs to library/ 2020-07-27 19:51:13 -05:00
pin_macro.rs Write {ui,} tests for pin_macro and pin! 2022-02-14 16:56:37 +01:00
pin.rs Make some methods of Pin<&mut T> unstable const 2020-09-18 19:23:50 +02:00
ptr.rs apply fmt 2024-01-11 15:04:48 +03:00
result.rs Remove unstable Result::into_ok_or_err 2022-08-17 17:20:42 -07:00
simd.rs Fix library tests 2023-11-26 08:50:39 -05:00
slice.rs Rollup merge of #117561 - tgross35:split-array, r=scottmcm 2024-01-19 19:26:59 +01:00
str_lossy.rs Expose Utf8Lossy as Utf8Chunks 2022-08-20 12:49:20 -04:00
str.rs Update paths in comments. 2022-12-30 14:00:42 +01:00
task.rs Remove test of static Context 2023-01-02 10:33:23 -08:00
time.rs apply fmt 2024-01-11 15:04:48 +03:00
tuple.rs mv std libs to library/ 2020-07-27 19:51:13 -05:00
unicode.rs revert changes to unicode stability 2022-07-08 21:18:15 +00:00
waker.rs libcore tests: avoid int2ptr casts 2022-06-27 13:30:44 -04:00