error_stack/
result.rs

1#![expect(deprecated, reason = "We use `Context` to maintain compatibility")]
2
3use crate::{Attachment, Context, IntoReport, OpaqueAttachment, Report};
4
5#[expect(rustdoc::invalid_html_tags, reason = "False positive")]
6/// <code>[Result](core::result::Result)<T, [Report<C>]></code>
7///
8/// A reasonable return type to use throughout an application.
9///
10/// The `Result` type can be used with one or two parameters, where the first parameter represents
11/// the [`Ok`] arm and the second parameter `Error` is used as in [`Report<C>`].
12///
13/// # Examples
14///
15/// `Result` can also be used in `fn main()`:
16///
17/// ```rust
18/// # fn has_permission(_: (), _: ()) -> bool { true }
19/// # fn get_user() -> Result<(), AccessError> { Ok(()) }
20/// # fn get_resource() -> Result<(), Report<AccessError>> { Ok(()) }
21/// # #[derive(Debug)] enum AccessError { PermissionDenied((), ()) }
22/// # impl core::fmt::Display for AccessError {
23/// #    fn fmt(&self, _: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { Ok(()) }
24/// # }
25/// # impl core::error::Error for AccessError {}
26/// use error_stack::{ensure, Report};
27///
28/// fn main() -> Result<(), Report<AccessError>> {
29///     let user = get_user()?;
30///     let resource = get_resource()?;
31///
32///     ensure!(
33///         has_permission(user, resource),
34///         AccessError::PermissionDenied(user, resource)
35///     );
36///
37///     # const _: &str = stringify! {
38///     ...
39///     # }; Ok(())
40/// }
41/// ```
42#[deprecated(
43    note = "Use `core::result::Result<T, Report<C>>` instead",
44    since = "0.6.0"
45)]
46pub type Result<T, C> = core::result::Result<T, Report<C>>;
47
48/// Extension trait for [`Result`][core::result::Result] to provide context information on
49/// [`Report`]s.
50pub trait ResultExt {
51    /// The [`Context`] type of the [`Result`].
52    type Context: ?Sized;
53
54    /// Type of the [`Ok`] value in the [`Result`]
55    type Ok;
56
57    /// Adds a new printable attachment to the [`Report`] inside the [`Result`].
58    ///
59    /// Applies [`Report::attach`] on the [`Err`] variant, refer to it for more
60    /// information.
61    fn attach<A>(self, attachment: A) -> core::result::Result<Self::Ok, Report<Self::Context>>
62    where
63        A: Attachment;
64
65    /// Lazily adds a new printable attachment to the [`Report`] inside the [`Result`].
66    ///
67    /// Applies [`Report::attach`] on the [`Err`] variant, refer to it for more
68    /// information.
69    fn attach_with<A, F>(
70        self,
71        attachment: F,
72    ) -> core::result::Result<Self::Ok, Report<Self::Context>>
73    where
74        A: Attachment,
75        F: FnOnce() -> A;
76
77    #[deprecated(
78        note = "Use `attach_opaque_with` instead. `attach_lazy` was renamed to \
79                `attach_opaque_with` and `attach_printable_lazy` was renamed to `attach_with`",
80        since = "0.6.0"
81    )]
82    fn attach_lazy<A, F>(
83        self,
84        attachment: F,
85    ) -> core::result::Result<Self::Ok, Report<Self::Context>>
86    where
87        A: OpaqueAttachment,
88        F: FnOnce() -> A;
89
90    /// Adds a new attachment to the [`Report`] inside the [`Result`].
91    ///
92    /// Applies [`Report::attach_opaque`] on the [`Err`] variant, refer to it for more information.
93    fn attach_opaque<A>(
94        self,
95        attachment: A,
96    ) -> core::result::Result<Self::Ok, Report<Self::Context>>
97    where
98        A: OpaqueAttachment;
99
100    /// Lazily adds a new attachment to the [`Report`] inside the [`Result`].
101    ///
102    /// Applies [`Report::attach_opaque`] on the [`Err`] variant, refer to it for more information.
103    fn attach_opaque_with<A, F>(
104        self,
105        attachment: F,
106    ) -> core::result::Result<Self::Ok, Report<Self::Context>>
107    where
108        A: OpaqueAttachment,
109        F: FnOnce() -> A;
110
111    #[deprecated(
112        note = "Use `attach` instead. `attach` was renamed to `attach_opaque` and \
113                `attach_printable` was renamed to `attach`",
114        since = "0.6.0"
115    )]
116    fn attach_printable<A>(
117        self,
118        attachment: A,
119    ) -> core::result::Result<Self::Ok, Report<Self::Context>>
120    where
121        A: Attachment;
122
123    #[deprecated(
124        note = "Use `attach_with` instead. `attach_lazy` was renamed to `attach_opaque_with` and \
125                `attach_printable_lazy` was renamed to `attach_with`",
126        since = "0.6.0"
127    )]
128    fn attach_printable_lazy<A, F>(
129        self,
130        attachment: F,
131    ) -> core::result::Result<Self::Ok, Report<Self::Context>>
132    where
133        A: Attachment,
134        F: FnOnce() -> A;
135
136    /// Changes the context of the [`Report`] inside the [`Result`].
137    ///
138    /// Applies [`Report::change_context`] on the [`Err`] variant, refer to it for more information.
139    fn change_context<C>(self, context: C) -> core::result::Result<Self::Ok, Report<C>>
140    where
141        C: Context;
142
143    /// Lazily changes the context of the [`Report`] inside the [`Result`].
144    ///
145    /// Applies [`Report::change_context`] on the [`Err`] variant, refer to it for more information.
146    fn change_context_lazy<C, F>(self, context: F) -> core::result::Result<Self::Ok, Report<C>>
147    where
148        C: Context,
149        F: FnOnce() -> C;
150}
151
152impl<T, E> ResultExt for core::result::Result<T, E>
153where
154    E: IntoReport,
155{
156    type Context = E::Context;
157    type Ok = T;
158
159    #[track_caller]
160    fn attach<A>(self, attachment: A) -> core::result::Result<T, Report<E::Context>>
161    where
162        A: Attachment,
163    {
164        match self {
165            Ok(value) => Ok(value),
166            Err(error) => Err(error.into_report().attach(attachment)),
167        }
168    }
169
170    #[track_caller]
171    fn attach_with<A, F>(self, attachment: F) -> core::result::Result<T, Report<E::Context>>
172    where
173        A: Attachment,
174        F: FnOnce() -> A,
175    {
176        match self {
177            Ok(value) => Ok(value),
178            Err(error) => Err(error.into_report().attach(attachment())),
179        }
180    }
181
182    #[track_caller]
183    fn attach_lazy<A, F>(self, attachment: F) -> core::result::Result<T, Report<E::Context>>
184    where
185        A: OpaqueAttachment,
186        F: FnOnce() -> A,
187    {
188        match self {
189            Ok(value) => Ok(value),
190            Err(error) => Err(error.into_report().attach_opaque(attachment())),
191        }
192    }
193
194    #[track_caller]
195    fn attach_opaque<A>(self, attachment: A) -> core::result::Result<T, Report<E::Context>>
196    where
197        A: OpaqueAttachment,
198    {
199        match self {
200            Ok(value) => Ok(value),
201            Err(error) => Err(error.into_report().attach_opaque(attachment)),
202        }
203    }
204
205    #[track_caller]
206    fn attach_opaque_with<A, F>(self, attachment: F) -> core::result::Result<T, Report<E::Context>>
207    where
208        A: OpaqueAttachment,
209        F: FnOnce() -> A,
210    {
211        match self {
212            Ok(value) => Ok(value),
213            Err(error) => Err(error.into_report().attach_opaque(attachment())),
214        }
215    }
216
217    #[track_caller]
218    fn attach_printable<A>(self, attachment: A) -> core::result::Result<T, Report<E::Context>>
219    where
220        A: Attachment,
221    {
222        match self {
223            Ok(value) => Ok(value),
224            Err(error) => Err(error.into_report().attach(attachment)),
225        }
226    }
227
228    #[track_caller]
229    fn attach_printable_lazy<A, F>(
230        self,
231        attachment: F,
232    ) -> core::result::Result<T, Report<E::Context>>
233    where
234        A: Attachment,
235        F: FnOnce() -> A,
236    {
237        match self {
238            Ok(value) => Ok(value),
239            Err(error) => Err(error.into_report().attach(attachment())),
240        }
241    }
242
243    #[track_caller]
244    fn change_context<C>(self, context: C) -> core::result::Result<T, Report<C>>
245    where
246        C: Context,
247    {
248        match self {
249            Ok(value) => Ok(value),
250            Err(error) => Err(error.into_report().change_context(context)),
251        }
252    }
253
254    #[track_caller]
255    fn change_context_lazy<C, F>(self, context: F) -> core::result::Result<T, Report<C>>
256    where
257        C: Context,
258        F: FnOnce() -> C,
259    {
260        match self {
261            Ok(value) => Ok(value),
262            Err(error) => Err(error.into_report().change_context(context())),
263        }
264    }
265}
error_stack/result.rs

error_stack/
result.rs
