Add Option::insert method

[canndrew]

Fix for this bug: #29203

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @aturon (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[Manishearth]

I think this needs an RfC

[canndrew]

Maybe. It seemed too small and trivial for an RFC though.

[alexcrichton]

To me this brushes up against the line of needing an RFC. While small, the Option type is a ubiquitous type and methods should not be added lightly. There's always a question of conventions here as well, for example:

• If this is added to Option, why not Result?
• This doesn't mirror the insert signature on all other collections.
• Should the previous value be returned? Or just an interior pointer?

This will at least need an #[unstable] annotation plus some unit tests (beyond those in the docs), but I wouldn't be torn up if we just discussed this and then decided rather than punting to an RFC.

[canndrew]

If this is added to Option, why not Result?

You can start asking that about all enum types. I think it matters more for Option though. I quite often carry Options around in data structures and need to mutate them in place. I don't do that so much with Result. Result is mainly used as the result of a function.

This doesn't mirror the insert signature on all other collections.

Perhaps a different name would suit better? It was a combination of the insert methods on the VacantEntry/OccupiedEntry types that I had in mind but a full-blown entry API on Option would be overkill.

Should the previous value be returned? Or just an interior pointer?

I'm indifferent.

[llasram]

I've wanted something like this, but closer to the various Entry enum or_insert and or_insert_with methods. For unilateral replacement it isn't clear to me why this method is any better than simple assignment, but I've several times wanted to start with a None, conditionally update to a Some if still None, then unconditionally use the held value via a mutable reference.

[tbu-]

See also my older pull request: #25149.

[alexcrichton]

The libs team discussed this during triage yesterday, and the conclusion was to postpone this for an RFC. If you need any help writing one, though, please just let me know!