core::ops

Enum ControlFlow

source
pub enum ControlFlow<B, C = ()> {
    Continue(C),
    Break(B),
}
๐Ÿ”ฌThis is a nightly-only experimental API. (control_flow_enum #75744)
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 ยท source

pub fn is_break(&self) -> bool

Returns true if this is a Break variant.

ยงExamples
use std::ops::ControlFlow;

assert!(ControlFlow::<i32, String>::Break(3).is_break());
assert!(!ControlFlow::<String, i32>::Continue(3).is_break());
1.59.0 ยท source

pub fn is_continue(&self) -> bool

Returns true if this is a Continue variant.

ยงExamples
use std::ops::ControlFlow;

assert!(!ControlFlow::<i32, String>::Break(3).is_continue());
assert!(ControlFlow::<String, i32>::Continue(3).is_continue());
source

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

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.

source

pub fn continue_value(self) -> Option<C>

๐Ÿ”ฌThis is a nightly-only experimental API. (control_flow_enum #75744)

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

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

assert_eq!(ControlFlow::<i32, String>::Break(3).continue_value(), None);
assert_eq!(ControlFlow::<String, i32>::Continue(3).continue_value(), Some(3));
source

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

๐Ÿ”ฌThis is a nightly-only experimental API. (control_flow_enum #75744)

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

Trait Implementationsยง

1.55.0 ยท sourceยง

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

sourceยง

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

Returns a copy of the value. Read more
1.6.0 ยท sourceยง

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

Performs copy-assignment from source. Read more
1.55.0 ยท sourceยง

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

sourceยง

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

Formats the value using the given formatter. Read more
sourceยง

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

sourceยง

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

๐Ÿ”ฌThis is a nightly-only experimental API. (try_trait_v2 #84277)
Constructs the type from a compatible Residual type. Read more
1.55.0 ยท sourceยง

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

sourceยง

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

Feeds this value into the given Hasher. Read more
1.6.0 ยท sourceยง

fn hash_slice<H: Hasher>(data: &[Self], state: &mut H)
where Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
1.55.0 ยท sourceยง

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

sourceยง

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

Tests for self and other values to be equal, and is used by ==.
1.6.0 ยท sourceยง

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
sourceยง

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

sourceยง

type TryType = ControlFlow<B, C>

๐Ÿ”ฌThis is a nightly-only experimental API. (try_trait_v2_residual #91285)
The โ€œreturnโ€ type of this meta-function.
sourceยง

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

sourceยง

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.
sourceยง

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. Read more
sourceยง

fn from_output(output: Self::Output) -> Self

๐Ÿ”ฌThis is a nightly-only experimental API. (try_trait_v2 #84277)
Constructs the type from its Output type. Read more
sourceยง

fn branch(self) -> ControlFlow<Self::Residual, Self::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). Read more
1.55.0 ยท sourceยง

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

1.55.0 ยท sourceยง

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

1.55.0 ยท sourceยง

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

Auto Trait Implementationsยง

ยง

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

ยง

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

ยง

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> UnwindSafe for ControlFlow<B, C>
where C: UnwindSafe, B: UnwindSafe,

Blanket Implementationsยง

sourceยง

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

sourceยง

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
sourceยง

impl<T> Borrow<T> for T
where T: ?Sized,

sourceยง

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
sourceยง

impl<T> BorrowMut<T> for T
where T: ?Sized,

sourceยง

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

Mutably borrows from an owned value. Read more
sourceยง

impl<T> CloneToUninit for T
where T: Clone,

sourceยง

unsafe fn clone_to_uninit(&self, dst: *mut T)

๐Ÿ”ฌThis is a nightly-only experimental API. (clone_to_uninit #126799)
Performs copy-assignment from self to dst. Read more
sourceยง

impl<T> From<T> for T

sourceยง

fn from(t: T) -> T

Returns the argument unchanged.

sourceยง

impl<T, U> Into<U> for T
where U: From<T>,

sourceยง

fn into(self) -> U

Calls U::from(self).

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

sourceยง

impl<T, U> TryFrom<U> for T
where U: Into<T>,

sourceยง

type Error = Infallible

The type returned in the event of a conversion error.
sourceยง

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

Performs the conversion.
sourceยง

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

sourceยง

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
sourceยง

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

Performs the conversion.