wlan_hw_sim/event/
convert.rs

1// Copyright 2023 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Fallible conversions.
6//!
7//! This module abstracts over branching (fallible) types like [`Option`] and [`Result`] and is a
8//! stop-gap for traits in the Rust core library that are unstable at time of writing (namely
9//! `core::ops::Try`). The [`Try`] trait allows event handlers to compose such types in their
10//! outputs. For example, [`Handler::expect`] is available when the output of a handler implements
11//! [`Try`].
12//!
13//! See the documentation for `core::ops::Try` etc. for more about how this mechanism works:
14//! https://doc.rust-lang.org/std/ops/trait.Try.html#
15//!
16//! [`Handler::expect`]: crate::event::handler::expect
17//! [`Option`]: core::option::Option
18//! [`Result`]: core::result::Result
19//! [`Try`]: crate::event::Try
20
21// TODO(https://fxbug.dev/42078844): Implement this in terms of the standard `core::ops::Try` and related
22//                         traits when they stabilize. Simplify (and eventually remove) this module
23//                         when those APIs can be used instead. Note that `core::ops::Try` is
24//                         already be implemented for `Option` and `Result`, so `core::ops::Try`
25//                         and `core::ops::FromResidual` must only be implemented for `Handled`.
26
27use std::convert::Infallible;
28use std::fmt::Display;
29use std::ops::ControlFlow;
30
31// This trait provides methods that (at time of writing) are unstable. They must be invoked using
32// fully qualified syntax since they share the same names as their unstable counterparts.
33pub trait ControlFlowExt<B, C> {
34    // TODO(https://fxbug.dev/335283785): Remove or document unused code
35    #[allow(dead_code)]
36    fn map_break<T, F>(self, f: F) -> ControlFlow<T, C>
37    where
38        F: FnOnce(B) -> T;
39
40    // TODO(https://fxbug.dev/335283785): Remove or document unused code
41    #[allow(dead_code)]
42    fn map_continue<T, F>(self, f: F) -> ControlFlow<B, T>
43    where
44        F: FnOnce(C) -> T;
45}
46
47impl<B, C> ControlFlowExt<B, C> for ControlFlow<B, C> {
48    fn map_break<T, F>(self, f: F) -> ControlFlow<T, C>
49    where
50        F: FnOnce(B) -> T,
51    {
52        match self {
53            ControlFlow::Break(inner) => ControlFlow::Break(f(inner)),
54            ControlFlow::Continue(inner) => ControlFlow::Continue(inner),
55        }
56    }
57
58    fn map_continue<T, F>(self, f: F) -> ControlFlow<B, T>
59    where
60        F: FnOnce(C) -> T,
61    {
62        match self {
63            ControlFlow::Break(inner) => ControlFlow::Break(inner),
64            ControlFlow::Continue(inner) => ControlFlow::Continue(f(inner)),
65        }
66    }
67}
68
69// This trait resembles the (at time of writing) unstable `core::ops::Try` and
70// `core::ops::FromResidual` traits. While it does not enable the `?` operator, it provides the
71// same abstraction of branching types and is used to enable APIs like `Handler::expect` and
72// `Handler::try_and`.
73/// Divergent (fallible) types.
74///
75/// This trait abstracts the branching of types that represent independent outputs and non-outputs
76/// (errors). Such types must be constructible from these variants and queried for a corresponding
77/// control flow.
78pub trait Try {
79    type Output;
80    // See the documentation for `core::ops::Try::Residual` for more about this associated type:
81    // https://doc.rust-lang.org/std/ops/trait.Try.html#associatedtype.Residual
82    type Residual;
83
84    fn from_output(output: Self::Output) -> Self;
85
86    fn from_residual(residual: Self::Residual) -> Self;
87
88    fn branch(self) -> ControlFlow<Self::Residual, Self::Output>;
89
90    fn unwrap(self) -> Self::Output
91    where
92        Self: Sized,
93    {
94        match self.branch() {
95            ControlFlow::Continue(output) => output,
96            _ => panic!(),
97        }
98    }
99
100    fn expect(self, message: impl Display) -> Self::Output
101    where
102        Self: Sized,
103    {
104        match self.branch() {
105            ControlFlow::Continue(output) => output,
106            _ => panic!("{}", message),
107        }
108    }
109}
110
111impl<T> Try for Option<T> {
112    type Output = T;
113    type Residual = Option<Infallible>;
114
115    fn from_output(output: Self::Output) -> Self {
116        Some(output)
117    }
118
119    fn from_residual(_: Self::Residual) -> Self {
120        None
121    }
122
123    fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
124        match self {
125            Some(inner) => ControlFlow::Continue(inner),
126            _ => ControlFlow::Break(None),
127        }
128    }
129}
130
131impl<T, E> Try for Result<T, E> {
132    type Output = T;
133    type Residual = Result<Infallible, E>;
134
135    fn from_output(output: Self::Output) -> Self {
136        Ok(output)
137    }
138
139    fn from_residual(residual: Self::Residual) -> Self {
140        match residual {
141            Err(error) => Err(error),
142            _ => unreachable!(),
143        }
144    }
145
146    fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
147        match self {
148            Ok(inner) => ControlFlow::Continue(inner),
149            Err(error) => ControlFlow::Break(Err(error)),
150        }
151    }
152}
wlan_hw_sim/event/convert.rs

wlan_hw_sim/event/
convert.rs
