Box/Vec/slice convenience NonNull methods

[theemathas]

Proposal

Problem statement

NonNull is the correct type for implementing unsafe data structures. However, using them requires extra conversions from Box and Vec, meaning that the path of least resistance is using *mut/*const raw pointers. Thus, with similar motivation to the ACP for NonNull convenience methods, I'm proposing some convenience methods on Box and Vec.

Motivating examples or use cases

The linked list book has an example of how someone might want to allocate some memory with Box, convert it into NonNull for storage, and later convert it back to Box for deallocation.

Solution sketch

I would like to proposing the following API additions:

impl<T: ?Sized, A: Allocator> Box<T, A> {
    pub fn into_non_null(b: Self) -> NonNull<T> { .... }
    pub fn into_non_null_with_allocator(b: Self) -> (NonNull<T>, A) { .... }
    pub const unsafe fn from_non_null_in(ptr: NonNull<T>, alloc: A) -> Self { .... }
}
impl<T: ?Sized> Box<T> {
    pub const unsafe fn from_non_null(ptr: NonNull<T>) -> Self { .... }
}

impl<T, A: Allocator> Vec<T, A> {
    pub fn into_non_null_parts(self) -> (NonNull<T>, usize, usize) { .... }
    pub fn into_non_null_parts_with_alloc(self) -> (NonNull<T>, usize, usize, A) { .... }
    pub fn as_non_null(&mut self) -> NonNull<T> { .... }
    pub unsafe fn from_non_null_parts_in(ptr: NonNull<T>, length: usize, capacity: usize, alloc: A) -> Self { .... }
}
impl<T> Vec<T> {
    pub unsafe fn from_non_null_parts(ptr: NonNull<T>, length: usize, capacity: usize) -> Self { .... }
}

impl<T> [T] {
    pub const fn as_non_null(&mut self) -> NonNull<T> { .... }
    pub const fn as_non_null_range(&mut self) -> Range<NonNull<T>> { .... }
}

Alternatives

The status quo: users need to do an extra layer of conversion to/from NonNull.

Vec::as_non_null might take &self instead of &mut self.

We might also want convenience methods for slices.

Links and related work

There are already some methods on NonNull<[T]>.

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.

[joshtriplett]

We discussed this in today's @rust-lang/libs-api meeting. We'd like to add most of these, with some tweaks:

• We'd like the various _non_null_parts methods to just be _parts (e.g. from_parts/into_parts).
• We'd like to defer the two slice methods and Vec::as_non_null for now. We'd appreciate advice and recommendations from @rust-lang/opsem on what the API should look like to avoid UB.
  • We think that if Vec::as_non_null takes &self, that would be safe because it's taking a reference to Vec which contains a pointer, so it isn't UB to write through the returned NonNull. But we still want to defer those because we'll want to name them consistently with the slice methods.

We're accepting that subset of the ACP, and we'd ask you to open a new ACP for the remaining methods with guidance from T-opsem.