core/ops/
control_flow.rs

1use crate::{convert, ops};
2
3/// Used to tell an operation whether it should exit early or go on as usual.
4///
5/// This is used when exposing things (like graph traversals or visitors) where
6/// you want the user to be able to choose whether to exit early.
7/// Having the enum makes it clearer -- no more wondering "wait, what did `false`
8/// mean again?" -- and allows including a value.
9///
10/// Similar to [`Option`] and [`Result`], this enum can be used with the `?` operator
11/// to return immediately if the [`Break`] variant is present or otherwise continue normally
12/// with the value inside the [`Continue`] variant.
13///
14/// # Examples
15///
16/// Early-exiting from [`Iterator::try_for_each`]:
17/// ```
18/// use std::ops::ControlFlow;
19///
20/// let r = (2..100).try_for_each(|x| {
21///     if 403 % x == 0 {
22///         return ControlFlow::Break(x)
23///     }
24///
25///     ControlFlow::Continue(())
26/// });
27/// assert_eq!(r, ControlFlow::Break(13));
28/// ```
29///
30/// A basic tree traversal:
31/// ```
32/// use std::ops::ControlFlow;
33///
34/// pub struct TreeNode<T> {
35///     value: T,
36///     left: Option<Box<TreeNode<T>>>,
37///     right: Option<Box<TreeNode<T>>>,
38/// }
39///
40/// impl<T> TreeNode<T> {
41///     pub fn traverse_inorder<B>(&self, f: &mut impl FnMut(&T) -> ControlFlow<B>) -> ControlFlow<B> {
42///         if let Some(left) = &self.left {
43///             left.traverse_inorder(f)?;
44///         }
45///         f(&self.value)?;
46///         if let Some(right) = &self.right {
47///             right.traverse_inorder(f)?;
48///         }
49///         ControlFlow::Continue(())
50///     }
51///     fn leaf(value: T) -> Option<Box<TreeNode<T>>> {
52///         Some(Box::new(Self { value, left: None, right: None }))
53///     }
54/// }
55///
56/// let node = TreeNode {
57///     value: 0,
58///     left: TreeNode::leaf(1),
59///     right: Some(Box::new(TreeNode {
60///         value: -1,
61///         left: TreeNode::leaf(5),
62///         right: TreeNode::leaf(2),
63///     }))
64/// };
65/// let mut sum = 0;
66///
67/// let res = node.traverse_inorder(&mut |val| {
68///     if *val < 0 {
69///         ControlFlow::Break(*val)
70///     } else {
71///         sum += *val;
72///         ControlFlow::Continue(())
73///     }
74/// });
75/// assert_eq!(res, ControlFlow::Break(-1));
76/// assert_eq!(sum, 6);
77/// ```
78///
79/// [`Break`]: ControlFlow::Break
80/// [`Continue`]: ControlFlow::Continue
81#[stable(feature = "control_flow_enum_type", since = "1.55.0")]
82#[rustc_diagnostic_item = "ControlFlow"]
83#[must_use]
84// ControlFlow should not implement PartialOrd or Ord, per RFC 3058:
85// https://rust-lang.github.io/rfcs/3058-try-trait-v2.html#traits-for-controlflow
86#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
87pub enum ControlFlow<B, C = ()> {
88    /// Move on to the next phase of the operation as normal.
89    #[stable(feature = "control_flow_enum_type", since = "1.55.0")]
90    #[lang = "Continue"]
91    Continue(C),
92    /// Exit the operation without running subsequent phases.
93    #[stable(feature = "control_flow_enum_type", since = "1.55.0")]
94    #[lang = "Break"]
95    Break(B),
96    // Yes, the order of the variants doesn't match the type parameters.
97    // They're in this order so that `ControlFlow<A, B>` <-> `Result<B, A>`
98    // is a no-op conversion in the `Try` implementation.
99}
100
101#[unstable(feature = "try_trait_v2", issue = "84277", old_name = "try_trait")]
102impl<B, C> ops::Try for ControlFlow<B, C> {
103    type Output = C;
104    type Residual = ControlFlow<B, convert::Infallible>;
105
106    #[inline]
107    fn from_output(output: Self::Output) -> Self {
108        ControlFlow::Continue(output)
109    }
110
111    #[inline]
112    fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
113        match self {
114            ControlFlow::Continue(c) => ControlFlow::Continue(c),
115            ControlFlow::Break(b) => ControlFlow::Break(ControlFlow::Break(b)),
116        }
117    }
118}
119
120#[unstable(feature = "try_trait_v2", issue = "84277", old_name = "try_trait")]
121// Note: manually specifying the residual type instead of using the default to work around
122// https://github.com/rust-lang/rust/issues/99940
123impl<B, C> ops::FromResidual<ControlFlow<B, convert::Infallible>> for ControlFlow<B, C> {
124    #[inline]
125    fn from_residual(residual: ControlFlow<B, convert::Infallible>) -> Self {
126        match residual {
127            ControlFlow::Break(b) => ControlFlow::Break(b),
128        }
129    }
130}
131
132#[unstable(feature = "try_trait_v2_residual", issue = "91285")]
133impl<B, C> ops::Residual<C> for ControlFlow<B, convert::Infallible> {
134    type TryType = ControlFlow<B, C>;
135}
136
137impl<B, C> ControlFlow<B, C> {
138    /// Returns `true` if this is a `Break` variant.
139    ///
140    /// # Examples
141    ///
142    /// ```
143    /// use std::ops::ControlFlow;
144    ///
145    /// assert!(ControlFlow::<&str, i32>::Break("Stop right there!").is_break());
146    /// assert!(!ControlFlow::<&str, i32>::Continue(3).is_break());
147    /// ```
148    #[inline]
149    #[stable(feature = "control_flow_enum_is", since = "1.59.0")]
150    pub fn is_break(&self) -> bool {
151        matches!(*self, ControlFlow::Break(_))
152    }
153
154    /// Returns `true` if this is a `Continue` variant.
155    ///
156    /// # Examples
157    ///
158    /// ```
159    /// use std::ops::ControlFlow;
160    ///
161    /// assert!(!ControlFlow::<&str, i32>::Break("Stop right there!").is_continue());
162    /// assert!(ControlFlow::<&str, i32>::Continue(3).is_continue());
163    /// ```
164    #[inline]
165    #[stable(feature = "control_flow_enum_is", since = "1.59.0")]
166    pub fn is_continue(&self) -> bool {
167        matches!(*self, ControlFlow::Continue(_))
168    }
169
170    /// Converts the `ControlFlow` into an `Option` which is `Some` if the
171    /// `ControlFlow` was `Break` and `None` otherwise.
172    ///
173    /// # Examples
174    ///
175    /// ```
176    /// use std::ops::ControlFlow;
177    ///
178    /// assert_eq!(ControlFlow::<&str, i32>::Break("Stop right there!").break_value(), Some("Stop right there!"));
179    /// assert_eq!(ControlFlow::<&str, i32>::Continue(3).break_value(), None);
180    /// ```
181    #[inline]
182    #[stable(feature = "control_flow_enum", since = "1.83.0")]
183    pub fn break_value(self) -> Option<B> {
184        match self {
185            ControlFlow::Continue(..) => None,
186            ControlFlow::Break(x) => Some(x),
187        }
188    }
189
190    /// Converts the `ControlFlow` into an `Result` which is `Ok` if the
191    /// `ControlFlow` was `Break` and `Err` if otherwise.
192    ///
193    /// # Examples
194    ///
195    /// ```
196    /// #![feature(control_flow_ok)]
197    ///
198    /// use std::ops::ControlFlow;
199    ///
200    /// struct TreeNode<T> {
201    ///     value: T,
202    ///     left: Option<Box<TreeNode<T>>>,
203    ///     right: Option<Box<TreeNode<T>>>,
204    /// }
205    ///
206    /// impl<T> TreeNode<T> {
207    ///     fn find<'a>(&'a self, mut predicate: impl FnMut(&T) -> bool) -> Result<&'a T, ()> {
208    ///         let mut f = |t: &'a T| -> ControlFlow<&'a T> {
209    ///             if predicate(t) {
210    ///                 ControlFlow::Break(t)
211    ///             } else {
212    ///                 ControlFlow::Continue(())
213    ///             }
214    ///         };
215    ///
216    ///         self.traverse_inorder(&mut f).break_ok()
217    ///     }
218    ///
219    ///     fn traverse_inorder<'a, B>(
220    ///         &'a self,
221    ///         f: &mut impl FnMut(&'a T) -> ControlFlow<B>,
222    ///     ) -> ControlFlow<B> {
223    ///         if let Some(left) = &self.left {
224    ///             left.traverse_inorder(f)?;
225    ///         }
226    ///         f(&self.value)?;
227    ///         if let Some(right) = &self.right {
228    ///             right.traverse_inorder(f)?;
229    ///         }
230    ///         ControlFlow::Continue(())
231    ///     }
232    ///
233    ///     fn leaf(value: T) -> Option<Box<TreeNode<T>>> {
234    ///         Some(Box::new(Self {
235    ///             value,
236    ///             left: None,
237    ///             right: None,
238    ///         }))
239    ///     }
240    /// }
241    ///
242    /// let node = TreeNode {
243    ///     value: 0,
244    ///     left: TreeNode::leaf(1),
245    ///     right: Some(Box::new(TreeNode {
246    ///         value: -1,
247    ///         left: TreeNode::leaf(5),
248    ///         right: TreeNode::leaf(2),
249    ///     })),
250    /// };
251    ///
252    /// let res = node.find(|val: &i32| *val > 3);
253    /// assert_eq!(res, Ok(&5));
254    /// ```
255    #[inline]
256    #[unstable(feature = "control_flow_ok", issue = "140266")]
257    pub fn break_ok(self) -> Result<B, C> {
258        match self {
259            ControlFlow::Continue(c) => Err(c),
260            ControlFlow::Break(b) => Ok(b),
261        }
262    }
263
264    /// Maps `ControlFlow<B, C>` to `ControlFlow<T, C>` by applying a function
265    /// to the break value in case it exists.
266    #[inline]
267    #[stable(feature = "control_flow_enum", since = "1.83.0")]
268    pub fn map_break<T>(self, f: impl FnOnce(B) -> T) -> ControlFlow<T, C> {
269        match self {
270            ControlFlow::Continue(x) => ControlFlow::Continue(x),
271            ControlFlow::Break(x) => ControlFlow::Break(f(x)),
272        }
273    }
274
275    /// Converts the `ControlFlow` into an `Option` which is `Some` if the
276    /// `ControlFlow` was `Continue` and `None` otherwise.
277    ///
278    /// # Examples
279    ///
280    /// ```
281    /// use std::ops::ControlFlow;
282    ///
283    /// assert_eq!(ControlFlow::<&str, i32>::Break("Stop right there!").continue_value(), None);
284    /// assert_eq!(ControlFlow::<&str, i32>::Continue(3).continue_value(), Some(3));
285    /// ```
286    #[inline]
287    #[stable(feature = "control_flow_enum", since = "1.83.0")]
288    pub fn continue_value(self) -> Option<C> {
289        match self {
290            ControlFlow::Continue(x) => Some(x),
291            ControlFlow::Break(..) => None,
292        }
293    }
294
295    /// Converts the `ControlFlow` into an `Result` which is `Ok` if the
296    /// `ControlFlow` was `Continue` and `Err` if otherwise.
297    ///
298    /// # Examples
299    ///
300    /// ```
301    /// #![feature(control_flow_ok)]
302    ///
303    /// use std::ops::ControlFlow;
304    ///
305    /// struct TreeNode<T> {
306    ///     value: T,
307    ///     left: Option<Box<TreeNode<T>>>,
308    ///     right: Option<Box<TreeNode<T>>>,
309    /// }
310    ///
311    /// impl<T> TreeNode<T> {
312    ///     fn validate<B>(&self, f: &mut impl FnMut(&T) -> ControlFlow<B>) -> Result<(), B> {
313    ///         self.traverse_inorder(f).continue_ok()
314    ///     }
315    ///
316    ///     fn traverse_inorder<B>(&self, f: &mut impl FnMut(&T) -> ControlFlow<B>) -> ControlFlow<B> {
317    ///         if let Some(left) = &self.left {
318    ///             left.traverse_inorder(f)?;
319    ///         }
320    ///         f(&self.value)?;
321    ///         if let Some(right) = &self.right {
322    ///             right.traverse_inorder(f)?;
323    ///         }
324    ///         ControlFlow::Continue(())
325    ///     }
326    ///
327    ///     fn leaf(value: T) -> Option<Box<TreeNode<T>>> {
328    ///         Some(Box::new(Self {
329    ///             value,
330    ///             left: None,
331    ///             right: None,
332    ///         }))
333    ///     }
334    /// }
335    ///
336    /// let node = TreeNode {
337    ///     value: 0,
338    ///     left: TreeNode::leaf(1),
339    ///     right: Some(Box::new(TreeNode {
340    ///         value: -1,
341    ///         left: TreeNode::leaf(5),
342    ///         right: TreeNode::leaf(2),
343    ///     })),
344    /// };
345    ///
346    /// let res = node.validate(&mut |val| {
347    ///     if *val < 0 {
348    ///         return ControlFlow::Break("negative value detected");
349    ///     }
350    ///
351    ///     if *val > 4 {
352    ///         return ControlFlow::Break("too big value detected");
353    ///     }
354    ///
355    ///     ControlFlow::Continue(())
356    /// });
357    /// assert_eq!(res, Err("too big value detected"));
358    /// ```
359    #[inline]
360    #[unstable(feature = "control_flow_ok", issue = "140266")]
361    pub fn continue_ok(self) -> Result<C, B> {
362        match self {
363            ControlFlow::Continue(c) => Ok(c),
364            ControlFlow::Break(b) => Err(b),
365        }
366    }
367
368    /// Maps `ControlFlow<B, C>` to `ControlFlow<B, T>` by applying a function
369    /// to the continue value in case it exists.
370    #[inline]
371    #[stable(feature = "control_flow_enum", since = "1.83.0")]
372    pub fn map_continue<T>(self, f: impl FnOnce(C) -> T) -> ControlFlow<B, T> {
373        match self {
374            ControlFlow::Continue(x) => ControlFlow::Continue(f(x)),
375            ControlFlow::Break(x) => ControlFlow::Break(x),
376        }
377    }
378}
379
380impl<T> ControlFlow<T, T> {
381    /// Extracts the value `T` that is wrapped by `ControlFlow<T, T>`.
382    ///
383    /// # Examples
384    ///
385    /// ```
386    /// #![feature(control_flow_into_value)]
387    /// use std::ops::ControlFlow;
388    ///
389    /// assert_eq!(ControlFlow::<i32, i32>::Break(1024).into_value(), 1024);
390    /// assert_eq!(ControlFlow::<i32, i32>::Continue(512).into_value(), 512);
391    /// ```
392    #[unstable(feature = "control_flow_into_value", issue = "137461")]
393    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]
394    pub const fn into_value(self) -> T {
395        match self {
396            ControlFlow::Continue(x) | ControlFlow::Break(x) => x,
397        }
398    }
399}
400
401/// These are used only as part of implementing the iterator adapters.
402/// They have mediocre names and non-obvious semantics, so aren't
403/// currently on a path to potential stabilization.
404impl<R: ops::Try> ControlFlow<R, R::Output> {
405    /// Creates a `ControlFlow` from any type implementing `Try`.
406    #[inline]
407    pub(crate) fn from_try(r: R) -> Self {
408        match R::branch(r) {
409            ControlFlow::Continue(v) => ControlFlow::Continue(v),
410            ControlFlow::Break(v) => ControlFlow::Break(R::from_residual(v)),
411        }
412    }
413
414    /// Converts a `ControlFlow` into any type implementing `Try`.
415    #[inline]
416    pub(crate) fn into_try(self) -> R {
417        match self {
418            ControlFlow::Continue(v) => R::from_output(v),
419            ControlFlow::Break(v) => v,
420        }
421    }
422}
core/ops/control_flow.rs

core/ops/
control_flow.rs
