ControlFlow

core::ops

Enum ControlFlow 

1.55.0 · Source 
pub enum ControlFlow<B, C = ()> {
    Continue(C),
    Break(B),
}
Expand description

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§

§1.55.0

Continue(C)

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

§1.55.0

Break(B)

Exit the operation without running subsequent phases.

Implementations§

Source§

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

1.59.0 (const: unstable) · Source

pub 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());
1.59.0 (const: unstable) · Source

pub 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());
1.83.0 (const: unstable) · Source

pub 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);
Source

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

🔬This is a nightly-only experimental API. (control_flow_ok #140266)

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

§Examples
#![feature(control_flow_ok)]

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));
1.83.0 (const: unstable) ·