Split MaybeUninit::write into new feature gate and stabilize it

[est31]

This splits off the MaybeUninit::write function from the maybe_uninit_extra feature gate into a new maybe_uninit_write feature gate and stabilizes it.

Earlier work to improve the documentation of the write function: #86220

Tracking issue: #63567

[rust-highfive]

r? @scottmcm

(rust-highfive has picked a reviewer for you, use r? to override)

[est31]

Original proposal to stabilize the feature: #63567 (comment)

After that there have been suggestions to split off the write function to stabilize it in isolation.

The const-ness of the function is not stabilized for now because assume_init_mut is not stably const, which is due to assert_inhabited not being stably const. See also #86273.

cc @RalfJung @mgeier @SimonSapin

[scottmcm]

This seems reasonable to me, but it'll need an FCP, so sending to a random libs member:

r? @dtolnay

[RalfJung]

No objections from my side, if T-libs agrees that this is useful.

impl<T> MaybeUninit<T> {
  pub fn write(&mut self, val: T) -> &mut T
}

What makes this somewhat non-standard is the fact that write returns something.

[SkiFire13]

What makes this somewhat non-standard is the fact that write returns something.

Maybe it could be called init?

[est31]

@RalfJung

What makes this somewhat non-standard is the fact that write returns something.

Indeed there is no analog function called write that also returns something. However, returning the reference is nothing completely novel. E.g. VacantEntry::insert returns a mutable reference after insertion. The newly stable Option::insert and unstable Entry::insert functions do the same (cc #65225), as do the stable Entry::or_insert and Entry::or_insert_with functions. insert might be an alternative name for the write function. I prefer write though as it shares a small (safe) footgun with ptr::write: if you call the function twice, no drop is executed for the first content. Insert doesn't have this footgun. write is also safe sugar for the unsafe .as_mut_ptr().write(). Those two reasons speak in favour of calling it write I think.

As for init, I think the best argument that speaks in favour is the linguistic relationship to the MaybeUninit name. By calling the init function, the maybe-un-init is now initialized. I think there is confusion potential with the new function though, and I can't find any other function named init in the standard library.

[est31]

@rustbot label S-waiting-on-team

[ghost]

Should "the destructor is not ran for the inner data" say run instead of ran at the top of the docs for write?

https://github.com/rust-lang/rust/blob/4aaaa424727a9bb02b494d34e1cc408e1de876f2/library/core/src/mem/maybe_uninit.rs#L412-L413

[est31]

@skippy10110 it seems you are right. "the destructor is not ran for the inner data" seems to be a present perfect passive construction, which means it needs to use the past participle form of run which is run.

https://www.wallstreetenglish.com/blog/the-present-perfect-tense-and-the-passive-voice/

https://dictionary.cambridge.org/dictionary/english/run

Good catch!

[BurntSushi]

I love the example! Thank you for digging that up. I suggested a few edits to make it a smidge clearer IMO. :-)

[RalfJung]

FCP passed, so I think this is ready to land. :)

However, I think there are some more examples that could use the new method. In the docs for MaybeUninit itself, we have x.as_mut_ptr().write and *elem = MaybeUninit::new; I think both of these would be written more ergonomically with write, wouldn't they?

[est31]

r? @dtolnay

[RalfJung]

Based on the example review by @BurntSushi
@bors r+

[bors]

📌 Commit 848a621 has been approved by RalfJung

[bors]

⌛ Testing commit 848a621 with merge 14c0c3e...