Tracking issue for `ControlFlow` enum, for use with `try_fold` and in `Try`

[NoraCodes]

(edited to turn this into a tracking issue, as it's referenced by the unstable attributes)

This is a tracking issue for the std::ops::ControlFlow type.
The feature gate for the issue is #![feature(control_flow_enum)].

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also uses as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Steps

• Implement
• Block interconversion with Results
  • Done with Implement the new desugaring from try_trait_v2 #84767
• Adjust documentation (see instructions on rustc-dev-guide)
• Stabilization PR (see instructions on rustc-dev-guide)
  • As part of stabilizing, mention in the docs for Iterator::try_fold and Iterator::try_for_each

Unresolved Questions

• Should we change the generic parameter order? https://github.com/rust-lang/rust/pull/76204/files#r481357223 done in change the order of type arguments on ControlFlow #76614
• What methods make sense
  • (probably not the into_try ones, https://github.com/rust-lang/rust/pull/76204/files#r481515347) Removed those ones in Demote ControlFlow::{from|into}_try to pub(crate) #85645
• Are the CONTINUE/BREAK constants valuable? See Stabilize ControlFlow::{BREAK, CONTINUE} #102697
  • Removed in Remove ControlFlow::{BREAK, CONTINUE} #107398
• Should it have B = () too? (Might be nice for try_for_each uses.)

Implementation history

Initial PR that added LoopState as an implementation detail: #45595
PR that exposed as unstable and renamed to ControlFlow: #76204
Added BREAK/CONTINUE associated constants: #76318
Changed type parameter order and defaulted C = (): #76614
Add is_break and is_continue methods: #78200

---

I work with an organization that has a large amount of Rust graph traversal code as part of its core business. We used to use itertools's fold_while for short-circuiting functional-style loops over slices of our graphs, which is now deprecated in favor of try_fold.

try_fold is great, but the lack of a standard library provided Try implementation that makes the loop semantics clear is confusing. We created our own, which is fine, but I think it would make a lot of sense to expose LoopState and provide an example in the docs.

Originally related to: rust-itertools/itertools#469

[ecstatic-morse]

Big +1 for this. A Break/Continue enum is also the correct abstraction for the Try trait instead of Result IMO, so I think this is worthy inclusion in the standard library (although in that case a name change would be in order). FWIW, I usually call this enum ControlFlow.

[scottmcm]

As the one who added LoopState initially, I'm not at all tied to that name, so morse's rename sounds good to me -- in fact I've also been calling it ControlFlow in the Try discussions.

@NoraCodes Want to take on making a PR here? There's probably a few parts:

• Renaming from LoopState to ControlFlow
• Making it pub and having appropriate #[unstable] markers on it
• Probably moving it out of core::iter; maybe to core::ops instead?
• Reexporting from std
• Derive a few more things on it now that it's intended to be a real type and not just something internal -- probably at least Clone, Copy, Debug (like morse's example has) in addition to its current PartialEq. (I would personally avoid PartialOrd and Ord for now -- if we stay order-agnostic for now we can change the discriminants later to make interconversion with result as cheap as possible without breaking people.)

Feel free to ping me (here, in a draft PR, on community Discord, or on Zulip) if you have questions.

Its methods are probably imperfect right now, but if it's unstable that's ok. People can start using it on nightly as we'll find out what needs fixing before stabilization that way.

[NoraCodes]

I would be happy to do this. I may ask for some help getting a development environment set up as I have yet to contribute to the core libraries.

[scottmcm]

@rustbot assign @NoraCodes