`Vec::as_non_null()` method

[theemathas]

Proposal

This is a follow-up to a previous ACP, which proposes convenience conversions from/to NonNull. This proposal proposes an API addition that was not accepted in that previous ACP.

Solution sketch

I would like to propose the following API addition:

impl<T, A: Allocator> Vec<T, A> {
    pub fn as_non_null(&mut self) -> NonNull<T> { .... }
}

Alternatives

&mut self vs &self

Consider the existing Vec::as_ptr() method, which converts a &Vec<T> into a *const T. It currently is implemented with code identical to Vec::as_mut_ptr(). However, as_ptr has documentation that prohibits using the returned pointer to mutate the buffer. Such a mutation wouldn't be language UB with the current implementation of as_ptr, but would be ruled as being library UB. That is, a &Vec<T> should not be used to mutate the underlying buffer.

In order to preserve this library UB, the proposed as_non_null method should take a &mut self argument, not &self.

Other APIs (which are not proposed in this ACP)

The following two methods were also proposed in the previous ACP but were not accepted:

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>> { .... }
}

It turns out that methods that turn slices into raw pointers should probably not take a reference as the argument. The existing [T]::as_mut_ptr() method, which converts a reference into a raw pointer in this way, is a footgun, since it imposes extra aliasing constraints. In particular, calling as_mut_ptr() a second time will invalidate the pointer returned from the first call. Therefore, a slice method that returns a raw pointer of some kind, should take a raw pointer of some kind as an argument.

Given that NonNull<[T]>::as_non_null_ptr() (which converts from NonNull<[T]> to NonNull<T>) already exists, there is no need to add another as_non_null method on slices.

As for as_non_null_range, it could potentially exist as a method that converts from NonNull<[T]> to a Range<NonNull<T>>. However, this would require doing pointer arithmetic to get the pointer pointing to the end of the range, and it is unclear whether the unsafe ptr::add semantics or the ptr::wrapping_add semantics are desirable. Therefore, I am not proposing this as_non_null_range method on slices.

Links and related work

T-opsem Zulip discussion

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.

[Amanieu]

We discussed this in the @rust-lang/libs-api meeting and decided to accept this. As per the discussion on the t-opsem zulip channel, &mut self seems to be the best receiver type for this method.

It may still be possible to add as_non_null to slices by adding methods to &[T] and &mut [T] separately, but that should be explored in a separate ACP. There may be implementation issues due to the way it interacts with auto-ref/auto-deref since there is no precedent for adding methods directly on references.