ACP: Slice to array version of split_off

[JarredAllen]

Proposal

Problem statement

Often, I have a slice containing some amount of elements, and I'd like the split off the first N elements as an array and leave behind the remainder.

Motivating examples or use cases

let message: &[u8] = ...;
let Some((head, tail)) = message.split_at_checked(4) else { /* Handle error path */ };
// `head` is the right length from above, so `.unwrap()` won't panic
let parsed_head = u32::from_le_bytes(head.try_into().unwrap());
let message = tail;

// And then repeat times the number of things you want to remove from the head.

This gets a little easier with slice::split_off, which is FCP'ed for stabilization, but still nothing there lets you avoid the .try_into().unwrap() conversion from a slice to an array.

Solution sketch

impl<T> [T] {
    fn split_off_chunk_first<'a, const N: usize>(self: &mut &'a Self) -> Option<&'a [T; N]>;
    fn split_off_chunk_first_mut<'a, const N: usize>(self: &mut &'a mut Self) -> Option<&'a mut [T; N]>;
    fn split_off_chunk_last<'a, const N: usize>(self: &mut &'a Self) -> Option<&'a [T; N]>;
    fn split_off_chunk_last_mut<'a, const N: usize>(self: &mut &'a mut Self) -> Option<&'a mut [T; N]>;
}

Each function removes N elements from the slice, either in front or in back, returning the removed elements as an array (or returning None and leaving self unchanged if self.len() < N).

My motivating example snippet would become:

let mut message: &[u8] = ...;
let parsed_head = u32::from_le_bytes(head.split_off_chunk_first()?);

Edge cases

If N == 0, then it'll always return Some, with the array being zero-length and having its address at the start or end of the slice (i.e. slice: &[u8] and slice.split_off_chunk_first<0>() have the same address).

If N == self.len(), then the returned array will be the full original contents of the slice, and the slice will now be empty, and will point to the end/beginning (same address as if the opposite method were called with N == 0).

Alternatives

I could write my own implementations of these functions as wrappers around slice::split_off, but this feels to me like something that belongs in the standard library.

I've only ever written code that would use the shared reference versions, not the mutable reference versions, so we could skip those two, but I feel like it'd be better to keep the shared/mutable symmetry a lot of slice methods already have.

These methods were originally suggested as take_chunk instead of split_off_chunk, to fit with what was then the name for the methods on this feature. There are other names that could be considered, but I think matching the name of those methods makes sense. We could bikeshed whether chunk comes before, after, or between first/last and mut in the name (I weakly prefer the order I wrote).

Links and related work

These methods have been mentioned on rust-lang/rust#62280, which is FCP'ed to stabilize similar methods but with a gap that I think this fulfills. I wanted to add these methods there (and I wasn't the only one to mention them), but it has been FCP'ed without response from anyone who seems official, so I'm writing them in a new ACP. I'm assuming the lack of comment meant "we're not adding these methods here" and not "we're not adding these methods".

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[tgross35]

Aren't these the same as the first_chunk/split_first_chunk and similar methods?

[JarredAllen]

Aren't these the same as the first_chunk/split_first_chunk and similar methods?

These are similar, but my proposed methods modify self in place (hence the &mut &'a Self signature).

[tgross35]

I don't think it makes sense to provide methods that require &mut [T] but return &[T]. It is pretty easy to split and reassign the slice in a single line if that is the desired outcome:

let mut slice = [0, 1, 2, 3].as_slice();

// reassign `slice`
let val;
(val, slice) = slice.split_first_chunk::<2>().unwrap();

// or just shadow
let (val, slice) = slice.split_first_chunk::<2>().unwrap();

https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=0b28a4ba5212b71536c63935dfc530d5

[JarredAllen]

I don't think it makes sense to provide methods that require &mut [T] but return &[T]. It is pretty easy to split and reassign the slice in a single line if that is the desired outcome:

They don't require &mut [T], the methods returning &'a [T; N] require &mut &'a T (note the double references, and the lifetime match to the inner, shared reference), similar to the split_off method in the linked feature.

[hanna-kruppe]

So these methods would be to the existing split_{first,last}_chunk[_mut] what the soon-to-be-stabilized split_off(n..) is to the non-chunk split_at_checked[_mut]? Not a huge big difference but it’s significantly nicer for some uses. More than once I’ve defined an extension trait just to get split_off_first_chunk and the variable-length equivalent split_off(n..).