Enum `ControlFlow`

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: &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: &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: 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: Self) -> Result<B, C>

Converts the ControlFlow into a 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));

const fn map_break<T, F>(self: 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: 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: Self) -> Result<C, B>

Converts the ControlFlow into a Result which is Ok if the ControlFlow was Continue 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 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: 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<T> ControlFlow<T, T>`

const fn into_value(self: 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);

`impl<B, C> Freeze for ControlFlow<B, C>`

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

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

`impl<B, C> RefUnwindSafe for ControlFlow<B, C>`

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

`impl<B, C> Send for ControlFlow<B, C>`

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

`impl<B, C> Sync for ControlFlow<B, C>`

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

fn from_output(output: <Self as >::Output) -> Self
fn branch(self: Self) -> ControlFlow<<Self as >::Residual, <Self as >::Output>

`impl<B, C> Unpin for ControlFlow<B, C>`

`impl<B, C> UnsafeUnpin for ControlFlow<B, C>`

`impl<B, C> UnwindSafe for ControlFlow<B, C>`

`impl<B: $crate::fmt::Debug, C: $crate::fmt::Debug> Debug for ControlFlow<B, C>`

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

`impl<B: $crate::hash::Hash, C: $crate::hash::Hash> Hash for ControlFlow<B, C>`

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

`impl<B: $crate::marker::Copy, C: $crate::marker::Copy> Copy for ControlFlow<B, C>`

`impl<B: ~const $crate::clone::Clone, C: ~const $crate::clone::Clone> Clone for ControlFlow<B, C>`

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

`impl<B: ~const $crate::cmp::Eq, C: ~const $crate::cmp::Eq> Eq for ControlFlow<B, C>`

`impl<B: ~const $crate::cmp::PartialEq, C: ~const $crate::cmp::PartialEq> PartialEq for ControlFlow<B, C>`

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

`impl<T> Any for ControlFlow<B, C>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for ControlFlow<B, C>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for ControlFlow<B, C>`

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

`impl<T> CloneToUninit for ControlFlow<B, C>`

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

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

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T, U> Into for ControlFlow<B, C>`

fn into(self: 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 for ControlFlow<B, C>`

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

`impl<T, U> TryInto for ControlFlow<B, C>`

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