feat(util/full): introduce Full::into_inner() (#155)

fixes #154.

this commit introduces a `http_body_util::Full::into_inner()` method.

this allows callers to consume a `Full<D>`, and reacquire the wrapped
value. this matches the style of [many interfaces][into-inner-docs]
offered by various types provided in `core` and `std` such as `Box<T>`,
`Arc<T>`, `Mutex<T>`, as well as [many interfaces][tokio-into-inner-docs]
offered by various types in `tokio` such as `BufWriter<T>`,
`OnceCell<T>`, and so forth.

this pattern is also mirrored in other `http_body_util` types including
`Either<L, R>`.

```rust
use http_body_util::Full;
const DATA: &[u8] = b"hello";
let full = Full::new(DATA);
assert_eq!(full.into_inner(), Some("hello").map(str::as_bytes));
```

NB: an `Full::inner()` method is not provided here. other types in `std`
and `tokio` do not expose such a method. idiomatically, once a chunk
is placed into a `Full<T>` it should be thought of as a `Body` rather
than a `T`, and `inner()` would make this a leaky abstraction.

[into-inner-docs]: https://doc.rust-lang.org/stable/std/?search=into_inner
[tokio-into-inner-docs]: https://docs.rs/tokio/latest/tokio/?search=into_inner

Signed-off-by: katelyn martin <[email protected]>

Author: cratelyn

http-body-util/src/full.rs

@@ -29,6 +29,24 @@ where
     }
 }
 
+impl<D> Full<D> {
+    /// Consumes this `Full`, returning the wrapped value.
+    ///
+    /// If this body has already been polled, this returns `None`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use http_body_util::Full;
+    /// const DATA: &[u8] = b"hello";
+    /// let full = Full::new(DATA);
+    /// assert_eq!(full.into_inner(), Some("hello").map(str::as_bytes));
+    /// ```
+    pub fn into_inner(self) -> Option<D> {
+        self.data
+    }
+}
+
 impl<D> Body for Full<D>
 where
     D: Buf,
@@ -144,4 +162,27 @@ mod tests {
         assert!(Full::<&[u8]>::default().frame().await.is_none());
         assert!(Full::new(&b""[..]).frame().await.is_none());
     }
+
+    #[tokio::test]
+    async fn full_into_inner_returns_none_before_poll() {
+        const DATA: &[u8] = b"hello";
+        let full = Full::new(DATA);
+        assert_eq!(
+            full.into_inner(),
+            Some(str::as_bytes("hello")),
+            "`Full::into_inner()` returns `Some(_)` before poll"
+        );
+    }
+
+    #[tokio::test]
+    async fn full_into_inner_returns_none_after_poll() {
+        const DATA: &[u8] = b"hello";
+        let mut full = Full::new(DATA);
+        full.frame().await.expect("a result").expect("a frame");
+        assert_eq!(
+            full.into_inner(),
+            None,
+            "`Full::into_inner()` returns `None` after poll"
+        );
+    }
 }