Expand the docs for ops::ControlFlow a bit

Since I was writing some examples for an RFC anyway.

Author: scottmcm

library/core/src/ops/control_flow.rs

@@ -1,13 +1,63 @@
 use crate::ops::Try;
 
-/// Used to make try_fold closures more like normal loops
+/// Used to tell an operation whether it should exit early or go on as usual.
+///
+/// This is used when exposing things (like graph traversals or visitors) where
+/// you want the user to be able to choose whether to exit early.
+/// Having the enum makes it clearer -- no more wondering "wait, what did `false`
+/// mean again?" -- and allows including a value.
+///
+/// # Examples
+///
+/// Early-exiting from [`Iterator::try_for_each`]:
+/// ```
+/// #![feature(control_flow_enum)]
+/// use std::ops::ControlFlow;
+///
+/// let r = (2..100).try_for_each(|x| {
+///     if 403 % x == 0 {
+///         return ControlFlow::Break(x)
+///     }
+///
+///     ControlFlow::Continue(())
+/// });
+/// assert_eq!(r, ControlFlow::Break(13));
+/// ```
+///
+/// A basic tree traversal:
+/// ```no_run
+/// #![feature(control_flow_enum)]
+/// use std::ops::ControlFlow;
+///
+/// pub struct TreeNode<T> {
+///     value: T,
+///     left: Option<Box<TreeNode<T>>>,
+///     right: Option<Box<TreeNode<T>>>,
+/// }
+///
+/// impl<T> TreeNode<T> {
+///     pub fn traverse_inorder<B>(&self, mut f: impl FnMut(&T) -> ControlFlow<B>) -> ControlFlow<B> {
+///         if let Some(left) = &self.left {
+///             left.traverse_inorder(&mut f)?;
+///         }
+///         f(&self.value)?;
+///         if let Some(right) = &self.right {
+///             right.traverse_inorder(&mut f)?;
+///         }
+///         ControlFlow::Continue(())
+///     }
+/// }
+/// ```
 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum ControlFlow<B, C = ()> {
-    /// Continue in the loop, using the given value for the next iteration
+    /// Move on to the next phase of the operation as normal.
     Continue(C),
-    /// Exit the loop, yielding the given value
+    /// Exit the operation without running subsequent phases.
     Break(B),
+    // Yes, the order of the variants doesn't match the type parameters.
+    // They're in this order so that `ControlFlow<A, B>` <-> `Result<B, A>`
+    // is a no-op conversion in the `Try` implementation.
 }
 
 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
@@ -33,13 +83,33 @@ impl<B, C> Try for ControlFlow<B, C> {
 
 impl<B, C> ControlFlow<B, C> {
     /// Returns `true` if this is a `Break` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(control_flow_enum)]
+    /// use std::ops::ControlFlow;
+    ///
+    /// assert!(ControlFlow::<i32, String>::Break(3).is_break());
+    /// assert!(!ControlFlow::<String, i32>::Continue(3).is_break());
+    /// ```
     #[inline]
     #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
     pub fn is_break(&self) -> bool {
         matches!(*self, ControlFlow::Break(_))
     }
 
     /// Returns `true` if this is a `Continue` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(control_flow_enum)]
+    /// use std::ops::ControlFlow;
+    ///
+    /// assert!(!ControlFlow::<i32, String>::Break(3).is_continue());
+    /// assert!(ControlFlow::<String, i32>::Continue(3).is_continue());
+    /// ```
     #[inline]
     #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
     pub fn is_continue(&self) -> bool {
@@ -48,6 +118,16 @@ impl<B, C> ControlFlow<B, C> {
 
     /// Converts the `ControlFlow` into an `Option` which is `Some` if the
     /// `ControlFlow` was `Break` and `None` otherwise.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// #![feature(control_flow_enum)]
+    /// use std::ops::ControlFlow;
+    ///
+    /// assert_eq!(ControlFlow::<i32, String>::Break(3).break_value(), Some(3));
+    /// assert_eq!(ControlFlow::<String, i32>::Continue(3).break_value(), None);
+    /// ```
     #[inline]
     #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
     pub fn break_value(self) -> Option<B> {

library/core/tests/lib.rs

@@ -15,6 +15,7 @@
 #![feature(const_maybe_uninit_assume_init)]
 #![feature(const_ptr_read)]
 #![feature(const_ptr_offset)]
+#![feature(control_flow_enum)]
 #![feature(core_intrinsics)]
 #![feature(core_private_bignum)]
 #![feature(core_private_diy_float)]

library/core/tests/ops.rs

@@ -1,3 +1,5 @@
+mod control_flow;
+
 use core::ops::{Bound, Range, RangeFrom, RangeFull, RangeInclusive, RangeTo, RangeToInclusive};
 use core::ops::{Deref, DerefMut};
 

library/core/tests/ops/control_flow.rs

@@ -0,0 +1,18 @@
+use core::intrinsics::discriminant_value;
+use core::ops::ControlFlow;
+
+#[test]
+fn control_flow_discriminants_match_result() {
+    // This isn't stable surface area, but helps keep `?` cheap between them,
+    // even if LLVM can't always take advantage of it right now.
+    // (Sadly Result and Option are inconsistent, so ControlFlow can't match both.)
+
+    assert_eq!(
+        discriminant_value(&ControlFlow::<i32, i32>::Break(3)),
+        discriminant_value(&Result::<i32, i32>::Err(3)),
+    );
+    assert_eq!(
+        discriminant_value(&ControlFlow::<i32, i32>::Continue(3)),
+        discriminant_value(&Result::<i32, i32>::Ok(3)),
+    );
+}