Enum std::ops::ControlFlow

pub enum ControlFlow<B, C = ()> {
    Continue(C),
    Break(B),
}

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)

Tuple Fields

0: C

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

Break(B)

Tuple Fields

0: B

Exit the operation without running subsequent phases.

Implementations

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

pub fn is_break(&self) -> bool

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());

pub fn is_continue(&self) -> bool

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());

pub fn break_value(self) -> Option<B>

🔬 This is a nightly-only experimental API. (control_flow_enum #75744)

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

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

🔬 This is a nightly-only experimental API. (control_flow_enum #75744)

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

impl<B> ControlFlow<B, ()>

pub const CONTINUE: ControlFlow<B, ()>

🔬 This is a nightly-only experimental API. (control_flow_enum #75744)

It’s frequently the case that there’s no value needed with Continue, so this provides a way to avoid typing (()), if you prefer it.

Examples

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

let mut partial_sum = 0;
let last_used = (1..10).chain(20..25).try_for_each(|x| {
    partial_sum += x;
    if partial_sum > 100 { ControlFlow::Break(x) }
    else { ControlFlow::CONTINUE }
});
assert_eq!(last_used.break_value(), Some(22));

impl<C> ControlFlow<(), C>

pub const BREAK: ControlFlow<(), C>

🔬 This is a nightly-only experimental API. (control_flow_enum #75744)

APIs like try_for_each don’t need values with Break, so this provides a way to avoid typing (()), if you prefer it.

Examples

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

let mut partial_sum = 0;
(1..10).chain(20..25).try_for_each(|x| {
    if partial_sum > 100 { ControlFlow::BREAK }
    else { partial_sum += x; ControlFlow::CONTINUE }
});
assert_eq!(partial_sum, 108);

Trait Implementations

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

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

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<B, C> FromResidual<<ControlFlow<B, C> as Try>::Residual> for ControlFlow<B, C>

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

🔬 This is a nightly-only experimental API. (try_trait_v2 #84277)

Constructs the type from a compatible Residual type.

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

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

type TryType = ControlFlow<B, C>

🔬 This is a nightly-only experimental API. (try_trait_v2_residual #91285)

The “return” type of this meta-function.

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

type Output = C

🔬 This is a nightly-only experimental API. (try_trait_v2 #84277)

The type of the value produced by ? when not short-circuiting.

type Residual = ControlFlow<B, Infallible>

🔬 This is a nightly-only experimental API. (try_trait_v2 #84277)

The type of the value passed to FromResidual::from_residual as part of ? when short-circuiting.

pub fn from_output(
    output: <ControlFlow<B, C> as Try>::Output
) -> ControlFlow<B, C>

🔬 This is a nightly-only experimental API. (try_trait_v2 #84277)

Constructs the type from its Output type.

pub fn branch(
    self
) -> ControlFlow<<ControlFlow<B, C> as Try>::Residual, <ControlFlow<B, C> as Try>::Output>

🔬 This is a nightly-only experimental API. (try_trait_v2 #84277)

Used in ? to decide whether the operator should produce a value (because this returned ControlFlow::Continue) or propagate a value back to the caller (because this returned ControlFlow::Break).

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

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