erra 0.2.0

Zero-dependency, type-preserving error annotation for Result
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

//! The [`ResultExt`] extension trait.

#[cfg(any(feature = "alloc", feature = "std"))]
use alloc::string::String;

use crate::Error;

/// Adds context to `Result<T, E>`.
///
/// Import this trait to use `.annotate(...)` and `.annotate_with(...)` on
/// `Result` values:
///
/// ```rust
/// use erra::ResultExt;
/// ```
pub trait ResultExt<T, E>: Sized {
    /// Wraps `Err(e)` with a static context string.
    ///
    /// ```rust
    /// use erra::{Result, ResultExt};
    /// use std::io;
    ///
    /// fn read_config(path: &str) -> Result<String, io::Error> {
    ///     std::fs::read_to_string(path)
    ///         .annotate("reading application config")
    /// }
    /// ```
    fn annotate(self, msg: &'static str) -> Result<T, Error<E>>;

    /// Wraps `Err(e)` with a context string built on demand.
    ///
    /// The closure runs only on the `Err` path.
    ///
    /// ```rust
    /// use erra::{Result, ResultExt};
    /// use std::io;
    ///
    /// fn read_named(path: &str) -> Result<String, io::Error> {
    ///     std::fs::read_to_string(path)
    ///         .annotate_with(|| format!("reading config at {path}"))
    /// }
    /// ```
    #[cfg(any(feature = "alloc", feature = "std"))]
    fn annotate_with<F>(self, f: F) -> Result<T, Error<E>>
    where
        F: FnOnce() -> String;
}

impl<T, E> ResultExt<T, E> for Result<T, E> {
    /// Wraps `Err(e)` with a static context string.
    #[inline]
    fn annotate(self, msg: &'static str) -> Result<T, Error<E>> {
        match self {
            Ok(v) => Ok(v),
            Err(e) => Err(Error::new(msg, e)),
        }
    }

    /// Wraps `Err(e)` with a lazily-built context string.
    #[cfg(any(feature = "alloc", feature = "std"))]
    #[inline]
    fn annotate_with<F>(self, f: F) -> Result<T, Error<E>>
    where
        F: FnOnce() -> String,
    {
        match self {
            Ok(v) => Ok(v),
            Err(e) => Err(Error::new_owned(f(), e)),
        }
    }
}