Add a Result::into_ok_or_err method to extract a T from Result<T, T>

[thomcc]

When updating code to handle the semi-recent deprecation of compare_and_swap in favor of compare_exchange, which returns Result<T, T>, I wanted this. I've also wanted it with code using slice::binary_search before.

The name (and perhaps the documentation) is the hardest part here, but this name seems consistent with the other Result methods, and equivalently memorable.

[rust-highfive]

r? @shepmaster

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

[jyn514]

ok_or_err makes me think of ok_or(), something like fn ok_or_err(self, err: E) -> Self. Maybe into_inner() is a better name?

[thomcc]

I'm comfortable renaming if desired. I think ok_or_err is clearer than into_inner, but into_inner is pretty good too (better than most of the other suggestions I got, which were: merge, collapse, converge, either_value, unwrap_either, ...).

I don't care that much about the name so long as the functionality is available under some name though.

Another suggestion I got was implementing From<Result<T, T>> for (bool, T), which is probably possible, but I didn't like, mainly because that seems strictly less convenient. For example, in the cas=>cmpxchg transition, I'd need to make atom.compare_and_swap(a, b, <ordering>) into <(bool, T)>::from(atom.compare_exchange(a, b, <ordering0>, <ordering1>)).1, which is awkward.

[thomcc]

Note that:

• I can't use the fancy intradoc links stuff here for reasons that only @jyn514 comprehends.
• Apparently primitives are only documented in std (No documentation for primitives in core #80334 or something), so I have to link it in std.

That said, I'm also okay with getting rid of these links entirely if that's desirable.

[camelid]

You can now use intra-doc links here!

Suggested change

	/// [binary_search]: ../../std/primitive.slice.html#method.binary_search
	/// [binary_search]: slice::binary_search

[camelid]

Actually, better yet you can change the part above that has the link to just [`slice::binary_search`] and remove this line.

[jyn514]

You can now use intra-doc links here!

No, the bootstrap bump hasn't happened yet. Intra-doc pointers landed in #80181, which is in 1.51, which is still in nightly.

[camelid]

Dang, I always forget about the bootstrap bump :(

[shepmaster]

Maybe into_inner() is a better name?

This at least tracks with the usage in futures (and either).

[shepmaster]

Binary search is the primary reason I've wanted similar, but I've also seen people want to use it in procedural macros where you use a TokenStream for success and failure cases.

This seems reasonable to add as an unstable feature.

[vandenheuvel]

Naming consistency with into_ok seems logical, so I propose a name like into_*, such as into_either or into_ok_or_err.

[bors]

☔ The latest upstream changes (presumably #81417) made this pull request unmergeable. Please resolve the merge conflicts.

[m-ou-se]

r? @m-ou-se

[m-ou-se]

We briefly discussed this in the libs team meeting last week, and agreed this is a function we should have. There was some discussion on the name, but felt comfortable landing this as ok_or_err or into_ok_or_err and leaving the bikeshedding for later (before stabilization).

Can you open a tracking issue? Thanks!

[thomcc]

Result::into_ok existing (even as unstable) is a compelling reason to use into_ok_or_err, so I renamed it (for now, I guess).

[m-ou-se]

@bors r+ rollup

[bors]

📌 Commit 404da0b has been approved by m-ou-se