errors 0.1.0

std::error::Error utilities
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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! Iterating error source chains
//!
//! This contains tools for inspecting error `source` chains.
//!
//! There are two `Iterator`s:
//!
//! - [`chain`](iter::chain): Iterates over the source chain, including the
//!   first `Error`.
//! - [`sources`](iter::sources): Iterates over only the sources of an `Error`,
//!   excluding itself.
//!
//! There also a few utilities for quickly traversing a source chain with a
//! specific goal in mind.
//!
//! - [`root`](iter::root): Finds the root source for a given error.
//! - [`is`](iter::is): Checks a source chain if it contains a given type.
//! - [`find`](iter::find): Finds the first occurance of a type in a source
//!   chain.

use super::{Error, ErrorRef};

/// Get an `Iterator` of the whole chain of errors.
///
/// Includes the `err` in the iterator as the first item.
///
/// # Example
///
/// ```
/// let err = errors::wrap("c", errors::wrap("b", "a"));
///
/// let expected = ["c", "b", "a"];
///
/// for (err, &s) in errors::iter::chain(&err).zip(expected.iter()) {
///     assert_eq!(err.to_string(), s);
/// }
/// ```
pub fn chain<'a>(err: &'a ErrorRef) -> impl Iterator<Item = &'a ErrorRef> + 'a {
    Iter { err: Some(err) }
}

/// Get an `Iterator` of the source chain of this error.
///
/// Skips `err`, starting as `err.source()`. Equivalent to `chain(err).skip(1)`.
///
/// # Example
///
/// ```
/// let err = errors::wrap("c", errors::wrap("b", "a"));
///
///
/// let expected = ["b", "a"];
///
/// for (err, &s) in errors::iter::sources(&err).zip(expected.iter()) {
///     assert_eq!(err.to_string(), s);
/// }
/// ```
pub fn sources(err: &dyn Error) -> impl Iterator<Item = &ErrorRef> {
    Iter { err: err.source() }
}

/// Returns whether the error source chain contains a given type.
///
/// # Example
///
/// ```
/// use std::io;
///
/// let err1 = io::Error::new(io::ErrorKind::Other, "boom");
/// let err2 = errors::wrap("ruh roh", err1);
///
/// let io = errors::find::<io::Error>(&err2).unwrap();
/// ```
pub fn find<E: Error + 'static>(err: &ErrorRef) -> Option<&E> {
    chain(err)
        .find_map(|e| e.downcast_ref::<E>())
}

/// Returns whether the error source chain contains a given type.
///
/// # Example
///
/// ```
/// use std::io;
///
/// let err1 = io::Error::new(io::ErrorKind::Other, "boom");
/// assert!(errors::is::<io::Error>(&err1));
///
/// let err2 = errors::wrap("ruh roh", err1);
/// assert!(errors::is::<io::Error>(&err2));
/// ```
pub fn is<E: Error + 'static>(err: &ErrorRef) -> bool {
    chain(err)
        .any(|e| e.is::<E>())
}

/// Get the root source of an `Error`.
///
/// If the provided `Error` has a source chain, this will find the last one
/// in the chain. If there is no chain, returns the same `Error`.
///
/// # Example
///
/// ```
/// // Error chain: c -> b -> a (root)
/// let err = errors::wrap("c", errors::wrap("b", "a"));
///
/// assert_eq!(errors::iter::root(&err).to_string(), "a");
///
/// // No chain:
/// let root = errors::new("ninja cat");
///
/// assert_eq!(errors::iter::root(&root).to_string(), "ninja cat");
/// ```
pub fn root(err: &ErrorRef) -> &ErrorRef {
    chain(err)
        .last()
        .expect("errors::iter::chain always yields at least 1 item")
}

struct Iter<'a> {
    err: Option<&'a ErrorRef>,
}

impl<'a> Iterator for Iter<'a> {
    type Item = &'a ErrorRef;

    fn next(&mut self) -> Option<Self::Item> {
        let next = self.err?;
        self.err = next.source();
        Some(next)
    }
}