1 use crate::{convert, ops};
3 /// Used to tell an operation whether it should exit early or go on as usual.
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.
12 /// Early-exiting from [`Iterator::try_for_each`]:
14 /// #![feature(control_flow_enum)]
15 /// use std::ops::ControlFlow;
17 /// let r = (2..100).try_for_each(|x| {
19 /// return ControlFlow::Break(x)
22 /// ControlFlow::Continue(())
24 /// assert_eq!(r, ControlFlow::Break(13));
27 /// A basic tree traversal:
29 /// #![feature(control_flow_enum)]
30 /// use std::ops::ControlFlow;
32 /// pub struct TreeNode<T> {
34 /// left: Option<Box<TreeNode<T>>>,
35 /// right: Option<Box<TreeNode<T>>>,
38 /// impl<T> TreeNode<T> {
39 /// pub fn traverse_inorder<B>(&self, mut f: impl FnMut(&T) -> ControlFlow<B>) -> ControlFlow<B> {
40 /// if let Some(left) = &self.left {
41 /// left.traverse_inorder(&mut f)?;
44 /// if let Some(right) = &self.right {
45 /// right.traverse_inorder(&mut f)?;
47 /// ControlFlow::Continue(())
51 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
52 #[derive(Debug, Clone, Copy, PartialEq)]
53 pub enum ControlFlow<B, C = ()> {
54 /// Move on to the next phase of the operation as normal.
55 #[cfg_attr(not(bootstrap), lang = "Continue")]
57 /// Exit the operation without running subsequent phases.
58 #[cfg_attr(not(bootstrap), lang = "Break")]
60 // Yes, the order of the variants doesn't match the type parameters.
61 // They're in this order so that `ControlFlow<A, B>` <-> `Result<B, A>`
62 // is a no-op conversion in the `Try` implementation.
65 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
67 impl<B, C> ops::TryV1 for ControlFlow<B, C> {
71 fn into_result(self) -> Result<Self::Output, Self::Error> {
73 ControlFlow::Continue(y) => Ok(y),
74 ControlFlow::Break(x) => Err(x),
78 fn from_error(v: Self::Error) -> Self {
82 fn from_ok(v: Self::Output) -> Self {
83 ControlFlow::Continue(v)
87 #[unstable(feature = "try_trait_v2", issue = "84277")]
88 impl<B, C> ops::TryV2 for ControlFlow<B, C> {
90 type Residual = ControlFlow<B, convert::Infallible>;
93 fn from_output(output: Self::Output) -> Self {
94 ControlFlow::Continue(output)
98 fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
100 ControlFlow::Continue(c) => ControlFlow::Continue(c),
101 ControlFlow::Break(b) => ControlFlow::Break(ControlFlow::Break(b)),
106 #[unstable(feature = "try_trait_v2", issue = "84277")]
107 impl<B, C> ops::FromResidual for ControlFlow<B, C> {
109 fn from_residual(residual: ControlFlow<B, convert::Infallible>) -> Self {
111 ControlFlow::Break(b) => ControlFlow::Break(b),
116 impl<B, C> ControlFlow<B, C> {
117 /// Returns `true` if this is a `Break` variant.
122 /// #![feature(control_flow_enum)]
123 /// use std::ops::ControlFlow;
125 /// assert!(ControlFlow::<i32, String>::Break(3).is_break());
126 /// assert!(!ControlFlow::<String, i32>::Continue(3).is_break());
129 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
130 pub fn is_break(&self) -> bool {
131 matches!(*self, ControlFlow::Break(_))
134 /// Returns `true` if this is a `Continue` variant.
139 /// #![feature(control_flow_enum)]
140 /// use std::ops::ControlFlow;
142 /// assert!(!ControlFlow::<i32, String>::Break(3).is_continue());
143 /// assert!(ControlFlow::<String, i32>::Continue(3).is_continue());
146 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
147 pub fn is_continue(&self) -> bool {
148 matches!(*self, ControlFlow::Continue(_))
151 /// Converts the `ControlFlow` into an `Option` which is `Some` if the
152 /// `ControlFlow` was `Break` and `None` otherwise.
157 /// #![feature(control_flow_enum)]
158 /// use std::ops::ControlFlow;
160 /// assert_eq!(ControlFlow::<i32, String>::Break(3).break_value(), Some(3));
161 /// assert_eq!(ControlFlow::<String, i32>::Continue(3).break_value(), None);
164 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
165 pub fn break_value(self) -> Option<B> {
167 ControlFlow::Continue(..) => None,
168 ControlFlow::Break(x) => Some(x),
172 /// Maps `ControlFlow<B, C>` to `ControlFlow<T, C>` by applying a function
173 /// to the break value in case it exists.
175 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
176 pub fn map_break<T, F>(self, f: F) -> ControlFlow<T, C>
181 ControlFlow::Continue(x) => ControlFlow::Continue(x),
182 ControlFlow::Break(x) => ControlFlow::Break(f(x)),
188 impl<R: ops::TryV1> ControlFlow<R, R::Output> {
189 /// Create a `ControlFlow` from any type implementing `Try`.
190 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
192 pub fn from_try(r: R) -> Self {
193 match R::into_result(r) {
194 Ok(v) => ControlFlow::Continue(v),
195 Err(v) => ControlFlow::Break(R::from_error(v)),
199 /// Convert a `ControlFlow` into any type implementing `Try`;
200 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
202 pub fn into_try(self) -> R {
204 ControlFlow::Continue(v) => R::from_ok(v),
205 ControlFlow::Break(v) => v,
210 #[cfg(not(bootstrap))]
211 impl<R: ops::TryV2> ControlFlow<R, R::Output> {
212 /// Create a `ControlFlow` from any type implementing `Try`.
213 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
215 pub fn from_try(r: R) -> Self {
217 ControlFlow::Continue(v) => ControlFlow::Continue(v),
218 ControlFlow::Break(v) => ControlFlow::Break(R::from_residual(v)),
222 /// Convert a `ControlFlow` into any type implementing `Try`;
223 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
225 pub fn into_try(self) -> R {
227 ControlFlow::Continue(v) => R::from_output(v),
228 ControlFlow::Break(v) => v,
233 impl<B> ControlFlow<B, ()> {
234 /// It's frequently the case that there's no value needed with `Continue`,
235 /// so this provides a way to avoid typing `(())`, if you prefer it.
240 /// #![feature(control_flow_enum)]
241 /// use std::ops::ControlFlow;
243 /// let mut partial_sum = 0;
244 /// let last_used = (1..10).chain(20..25).try_for_each(|x| {
245 /// partial_sum += x;
246 /// if partial_sum > 100 { ControlFlow::Break(x) }
247 /// else { ControlFlow::CONTINUE }
249 /// assert_eq!(last_used.break_value(), Some(22));
251 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
252 pub const CONTINUE: Self = ControlFlow::Continue(());
255 impl<C> ControlFlow<(), C> {
256 /// APIs like `try_for_each` don't need values with `Break`,
257 /// so this provides a way to avoid typing `(())`, if you prefer it.
262 /// #![feature(control_flow_enum)]
263 /// use std::ops::ControlFlow;
265 /// let mut partial_sum = 0;
266 /// (1..10).chain(20..25).try_for_each(|x| {
267 /// if partial_sum > 100 { ControlFlow::BREAK }
268 /// else { partial_sum += x; ControlFlow::CONTINUE }
270 /// assert_eq!(partial_sum, 108);
272 #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")]
273 pub const BREAK: Self = ControlFlow::Break(());