feat: Introduce Response::error_for_status method

This method makes it possible to let users map responses with
unexpected HTTP statuses to custom errors while staying inside a chain
of results.

src/lib.rs

@@ -133,7 +133,7 @@ enum Body<'a> {
 /// decoding a string via `Response::as_string` or to a
 /// `serde`-compatible type with `Response::as_json` (if the
 /// `json`-feature is enabled).
-#[derive(Debug)]
+#[derive(Debug, PartialEq)]
 pub struct Response<T> {
     /// HTTP status code of the response.
     pub status: u32,
@@ -431,6 +431,20 @@ impl <T> Response<T> {
     pub fn is_success(&self) -> bool {
         self.status >= 200 && self.status < 300
     }
+
+    /// Check whether a request succeeded and let users provide a
+    /// closure that creates an error from the request if it did not.
+    ///
+    /// This function exists for convenience to avoid having to write
+    /// repetitive `if !response.is_success() { ... }` blocks.
+    pub fn error_for_status<F, E>(self, closure: F) -> Result<Self, E>
+    where F: FnOnce(Self) -> E {
+        if !self.is_success() {
+            return Err(closure(self))
+        }
+
+        Ok(self)
+    }
 }
 
 impl Response<Vec<u8>> {

src/tests.rs

@@ -115,3 +115,15 @@ fn test_basic_auth() {
 
     assert!(response.is_success(), "authorized request should succeed");
 }
+
+// Tests for various other features.
+
+#[test]
+fn test_error_for_status() {
+    let response = Request::new(Method::Get, "https://httpbin.org/patch")
+        .send().expect("failed to send request")
+        .error_for_status(|resp| format!("Response error code: {}", resp.status));
+
+    assert_eq!(Err("Response error code: 405".into()), response,
+               "returned error should be converted into Result::Err");
+}