Enum ControlFlow

#[must_use]
pub enum ControlFlow<B, C = ()>

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.

Similar to Option and Result, this enum can be used with the ? operator to return immediately if the Break variant is present or otherwise continue normally with the value inside the Continue variant.

Examples

Early-exiting from [Iterator::try_for_each]:

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:

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, f: &mut impl FnMut(&T) -> ControlFlow<B>) -> ControlFlow<B> {
        if let Some(left) = &self.left {
            left.traverse_inorder(f)?;
        }
        f(&self.value)?;
        if let Some(right) = &self.right {
            right.traverse_inorder(f)?;
        }
        ControlFlow::Continue(())
    }
    fn leaf(value: T) -> Option<Box<TreeNode<T>>> {
        Some(Box::new(Self { value, left: None, right: None }))
    }
}

let node = TreeNode {
    value: 0,
    left: TreeNode::leaf(1),
    right: Some(Box::new(TreeNode {
        value: -1,
        left: TreeNode::leaf(5),
        right: TreeNode::leaf(2),
    }))
};
let mut sum = 0;

let res = node.traverse_inorder(&mut |val| {
    if *val < 0 {
        ControlFlow::Break(*val)
    } else {
        sum += *val;
        ControlFlow::Continue(())
    }
});
assert_eq!(res, ControlFlow::Break(-1));
assert_eq!(sum, 6);

Variants

Continue(C)

Move on to the next phase of the operation as normal.

Break(B)

Exit the operation without running subsequent phases.

Implementations

impl<B, C> ControlFlow<B, C>

const fn is_break(&self) -> bool

Returns true if this is a Break variant.

Examples

use std::ops::ControlFlow;

assert!(ControlFlow::<&str, i32>::Break("Stop right there!").is_break());
assert!(!ControlFlow::<&str, i32>::Continue(3).is_break());

const fn is_continue(&self) -> bool

Returns true if this is a Continue variant.

Examples

use std::ops::ControlFlow;

assert!(!ControlFlow::<&str, i32>::Break("Stop right there!").is_continue());
assert!(ControlFlow::<&str, i32>::Continue(3).is_continue());

const fn break_value(self) -> Option<B>
where
    Self: ,

Converts the ControlFlow into an Option which is Some if the ControlFlow was Break and None otherwise.

Examples

use std::ops::ControlFlow;

assert_eq!(ControlFlow::<&str, i32>::Break("Stop right there!").break_value(), Some("Stop right there!"));
assert_eq!(ControlFlow::<&str, i32>::Continue(3).break_value(), None);

const fn break_ok(self) -> Result<B, C>

Converts the ControlFlow into a Result which is Ok if the ControlFlow was Break and Err if otherwise.

Examples

use std::ops::ControlFlow;

struct TreeNode<T> {
    value: T,
    left: Option<Box<TreeNode<T>>>,
    right: Option<Box<TreeNode<T>>>,
}

impl<T> TreeNode<T> {
    fn find<'a>(&'a self, mut predicate: impl FnMut(&T) -> bool) -> Result<&'a T, ()> {
        let mut f = |t: &'a T| -> ControlFlow<&'a T> {
            if predicate(t) {
                ControlFlow::Break(t)
            } else {
                ControlFlow::Continue(())
            }
        };

        self.traverse_inorder(&mut f).break_ok()
    }

    fn traverse_inorder<'a, B>(
        &'a self,
        f: &mut impl FnMut(&'a T) -> ControlFlow<B>,
    ) -> ControlFlow<B> {
        if let Some(left) = &self.left {
            left.traverse_inorder(f)?;
        }
        f(&self.value)?;
        if let Some(right) = &self.right {
            right.traverse_inorder(f)?;
        }
        ControlFlow::Continue(())
    }

    fn leaf(value: T) -> Option<Box<TreeNode<T>>> {
        Some(Box::new(Self {
            value,
            left: None,
            right: None,
        }))
    }
}

let node = TreeNode {
    value: 0,
    left: TreeNode::leaf(1),
    right: Some(Box::new(TreeNode {
        value: -1,
        left: TreeNode::leaf(5),
        right: TreeNode::leaf(2),
    })),
};

let res = node.find(|val: &i32| *val > 3);
assert_eq!(res, Ok(&5));

const fn map_break<T, F>(self, f: F) -> ControlFlow<T, C>
where
    F: ~const FnOnce(B) -> T,

Maps ControlFlow<B, C> to ControlFlow<T, C> by applying a function to the break value in case it exists.

const fn continue_value(self) -> Option<C>
where
    Self: ,

Converts the ControlFlow into an Option which is Some if the ControlFlow was Continue and None otherwise.

Examples

use std::ops::ControlFlow;

assert_eq!(ControlFlow::<&str, i32>::Break("Stop right there!").continue_value(), None);
assert_eq!(ControlFlow::<&str, i32>::Continue(3).continue_value(), Some(3));

const fn continue_ok(self) -> Result<C, B>

Converts the ControlFlow into a Result which is Ok if the ControlFlow was Continue and Err if otherwise.

Examples

use std::ops::ControlFlow;

struct TreeNode<T> {
    value: T,
    left: Option<Box<TreeNode<T>>>,
    right: Option<Box<TreeNode<T>>>,
}

impl<T> TreeNode<T> {
    fn validate<B>(&self, f: &mut impl FnMut(&T) -> ControlFlow<B>) -> Result<(), B> {
        self.traverse_inorder(f).continue_ok()
    }

    fn traverse_inorder<B>(&self, f: &mut impl FnMut(&T) -> ControlFlow<B>) -> ControlFlow<B> {
        if let Some(left) = &self.left {
            left.traverse_inorder(f)?;
        }
        f(&self.value)?;
        if let Some(right) = &self.right {
            right.traverse_inorder(f)?;
        }
        ControlFlow::Continue(())
    }

    fn leaf(value: T) -> Option<Box<TreeNode<T>>> {
        Some(Box::new(Self {
            value,
            left: None,
            right: None,
        }))
    }
}

let node = TreeNode {
    value: 0,
    left: TreeNode::leaf(1),
    right: Some(Box::new(TreeNode {
        value: -1,
        left: TreeNode::leaf(5),
        right: TreeNode::leaf(2),
    })),
};

let res = node.validate(&mut |val| {
    if *val < 0 {
        return ControlFlow::Break("negative value detected");
    }

    if *val > 4 {
        return ControlFlow::Break("too big value detected");
    }

    ControlFlow::Continue(())
});
assert_eq!(res, Err("too big value detected"));

const fn map_continue<T, F>(self, f: F) -> ControlFlow<B, T>
where
    F: ~const FnOnce(C) -> T,

Maps ControlFlow<B, C> to ControlFlow<B, T> by applying a function to the continue value in case it exists.

impl<R: Try> ControlFlow<R, R::Output>

const fn from_try(r: R) -> Self
where
    R: ~const Try,

Creates a ControlFlow from any type implementing Try.

const fn into_try(self) -> R
where
    R: ~const Try,

Converts a ControlFlow into any type implementing Try.

impl<T> ControlFlow<T, T>

const fn into_value(self) -> T

Extracts the value T that is wrapped by ControlFlow<T, T>.

Examples

#![feature(control_flow_into_value)]
use std::ops::ControlFlow;

assert_eq!(ControlFlow::<i32, i32>::Break(1024).into_value(), 1024);
assert_eq!(ControlFlow::<i32, i32>::Continue(512).into_value(), 512);

Trait Implementations

impl<B, C> FromResidual<ControlFlow<B, Infallible>> for ControlFlow<B, C>

fn from_residual(residual: ControlFlow<B, Infallible>) -> Self

impl<B, C> Residual<C> for ControlFlow<B, Infallible>

type TryType = ControlFlow<B, C>;

impl<B, C> Try for ControlFlow<B, C>

type Output = C;
type Residual = ControlFlow<B, Infallible>;
fn from_output(output: Self::Output) -> Self
fn branch(self) -> ControlFlow<Self::Residual, Self::Output>

impl<B: Copy, C: Copy> Copy for ControlFlow<B, C>

impl<B: Debug, C: Debug> Debug for ControlFlow<B, C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

impl<B: Hash, C: Hash> Hash for ControlFlow<B, C>

fn hash<__H: Hasher>(&self, state: &mut __H)

impl<B: PartialEq, C: PartialEq> StructuralPartialEq for ControlFlow<B, C>

impl<B: ~const Clone, C: ~const Clone> Clone for ControlFlow<B, C>

fn clone(&self) -> ControlFlow<B, C>

impl<B: ~const Eq, C: ~const Eq> Eq for ControlFlow<B, C>

fn assert_fields_are_eq(&self)

impl<B: ~const PartialEq, C: ~const PartialEq> PartialEq for ControlFlow<B, C>

fn eq(&self, other: &ControlFlow<B, C>) -> bool

Auto Trait Implementations

impl<B, C> Freeze for ControlFlow<B, C> where C: Freeze, B: Freeze,

impl<B, C> RefUnwindSafe for ControlFlow<B, C> where C: RefUnwindSafe, B: RefUnwindSafe,

impl<B, C> Send for ControlFlow<B, C> where C: Send, B: Send,

impl<B, C> Sync for ControlFlow<B, C> where C: Sync, B: Sync,

impl<B, C> Unpin for ControlFlow<B, C> where C: Unpin, B: Unpin,

impl<B, C> UnsafeUnpin for ControlFlow<B, C> where C: UnsafeUnpin, B: UnsafeUnpin,

impl<B, C> UnwindSafe for ControlFlow<B, C> where C: UnwindSafe, B: UnwindSafe,

Blanket Implementations

impl<T> Any for ControlFlow<B, C> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for ControlFlow<B, C> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for ControlFlow<B, C> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> CloneToUninit for ControlFlow<B, C> where T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

impl<T> From<T> for ControlFlow<B, C>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Printable for ControlFlow<B, C> where T: Copy + Debug,

impl<T> SizeHint for ControlFlow<B, C> where T: ?Sized,

fn lower_bound(&self) -> usize
fn upper_bound(&self) -> Option<usize>

impl<T> SizedTypeProperties for ControlFlow<B, C>

impl<T, U> Into<U> for ControlFlow<B, C> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for ControlFlow<B, C> where U: Into<T>,

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for ControlFlow<B, C> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>