From 05fda5e006b01aa85674225213ea97722be3cda0 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sat, 28 Jul 2018 14:15:27 +0200 Subject: [PATCH 1/2] Clarify iteration behavior for causes by splitting it in two methods --- src/error/mod.rs | 17 ++++++++++++++--- src/lib.rs | 16 +++++++++++----- 2 files changed, 25 insertions(+), 8 deletions(-) diff --git a/src/error/mod.rs b/src/error/mod.rs index 18a103c..4860299 100644 --- a/src/error/mod.rs +++ b/src/error/mod.rs @@ -132,13 +132,24 @@ impl Error { self.as_fail().find_root_cause() } - /// Returns a iterator over the causes of the `Error`, beginning with - /// the failure returned by the `as_fail` method and ending with the failure - /// returned by `find_root_cause`. + /// Returns a iterator over the causes of this error with the cause + /// of the fail as the first item and the `root_cause` as the final item. + /// + /// Use `iter_chain` to also include the fail of this error itself. pub fn iter_causes(&self) -> Causes { self.as_fail().iter_causes() } + /// Returns a iterator over all fails up the chain from the current + /// as the first item up to the `root_cause` as the final item. + /// + /// This means that the chain also includes the fail itself which + /// means that it does *not* start with `cause`. To skip the outermost + /// fail use `iter_causes` instead. + pub fn iter_chain(&self) -> Causes { + self.as_fail().iter_chain() + } + /// Attempts to downcast this `Error` to a particular `Fail` type by /// reference. /// diff --git a/src/lib.rs b/src/lib.rs index a35fff5..5b1856b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -220,13 +220,19 @@ impl Fail { find_root_cause(self) } - /// Returns a iterator over the causes of this `Fail` with itself - /// as the first item and the `root_cause` as the final item. + /// Returns a iterator over the causes of this `Fail` with the cause + /// of this fail as the first item and the `root_cause` as the final item. + pub fn iter_causes(&self) -> Causes { + Causes { fail: self.cause() } + } + + /// Returns a iterator over all fails up the chain from the current + /// as the first item up to the `root_cause` as the final item. /// - /// This means that `causes` also includes the fail itself which + /// This means that the chain also includes the fail itself which /// means that it does *not* start with `cause`. To skip the outermost - /// fail use the `skip` method (`fail.causes().skip(1)`). - pub fn iter_causes(&self) -> Causes { + /// fail use `iter_causes` instead. + pub fn iter_chain(&self) -> Causes { Causes { fail: Some(self) } } From 80a70754c3cf06afe1e09083fc5ebbb68eca1c33 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sat, 28 Jul 2018 14:16:48 +0200 Subject: [PATCH 2/2] Update deprecation notes to point to iter_chain --- src/error/mod.rs | 2 +- src/lib.rs | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/error/mod.rs b/src/error/mod.rs index 4860299..04c0303 100644 --- a/src/error/mod.rs +++ b/src/error/mod.rs @@ -173,7 +173,7 @@ impl Error { } /// Deprecated alias to `iter_causes`. - #[deprecated(since = "0.1.2", note = "please use the 'iter_causes()' method instead")] + #[deprecated(since = "0.1.2", note = "please use the 'iter_chain()' method instead")] pub fn causes(&self) -> Causes { Causes { fail: Some(self.as_fail()) } } diff --git a/src/lib.rs b/src/lib.rs index 5b1856b..1002e76 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -222,6 +222,8 @@ impl Fail { /// Returns a iterator over the causes of this `Fail` with the cause /// of this fail as the first item and the `root_cause` as the final item. + /// + /// Use `iter_chain` to also include the fail itself. pub fn iter_causes(&self) -> Causes { Causes { fail: self.cause() } } @@ -243,7 +245,7 @@ impl Fail { } /// Deprecated alias to `iter_causes`. - #[deprecated(since = "0.1.2", note = "please use the 'iter_causes()' method instead")] + #[deprecated(since = "0.1.2", note = "please use the 'iter_chain()' method instead")] pub fn causes(&self) -> Causes { Causes { fail: Some(self) } }