Properly document 'RawStr' 'Cow' conversions.

core/http/src/raw_str.rs

@@ -66,6 +66,16 @@ pub struct RawStrBuf(String);
 
 impl RawStrBuf {
     /// Cost-free conversion from `self` into a `String`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # extern crate rocket;
+    /// use rocket::http::RawStrBuf;
+    ///
+    /// let raw = RawStrBuf::from(format!("hello {}", "world"));
+    /// let string = raw.into_string();
+    /// ```
     pub fn into_string(self) -> String {
         self.0
     }
@@ -89,18 +99,20 @@ impl RawStr {
         RawStr::ref_cast(string.as_ref())
     }
 
-    /// Constructs an `&RawStr` from a string-like type at no cost.
+    /// Construct a `Cow<RawStr>` from a `Cow<Str>`. Does not allocate.
+    ///
+    /// See [`RawStr::into_cow_str()`] for the inverse operation.
     ///
     /// # Example
     ///
     /// ```rust
     /// # extern crate rocket;
+    /// use std::borrow::Cow;
     /// use rocket::http::RawStr;
     ///
-    /// let raw_str = RawStr::new("Hello, world!");
-    ///
-    /// // `into` can also be used; note that the type must be specified
-    /// let raw_str: &RawStr = "Hello, world!".into();
+    /// let cow_str = Cow::from("hello!");
+    /// let cow_raw = RawStr::from_cow_str(cow_str);
+    /// assert_eq!(cow_raw.as_str(), "hello!");
     /// ```
     pub fn from_cow_str<'a>(cow: Cow<'a, str>) -> Cow<'a, RawStr> {
         match cow {
@@ -109,18 +121,20 @@ impl RawStr {
         }
     }
 
-    /// Constructs an `&RawStr` from a string-like type at no cost.
+    /// Construct a `Cow<str>` from a `Cow<RawStr>`. Does not allocate.
+    ///
+    /// See [`RawStr::from_cow_str()`] for the inverse operation.
     ///
     /// # Example
     ///
     /// ```rust
     /// # extern crate rocket;
+    /// use std::borrow::Cow;
     /// use rocket::http::RawStr;
     ///
-    /// let raw_str = RawStr::new("Hello, world!");
-    ///
-    /// // `into` can also be used; note that the type must be specified
-    /// let raw_str: &RawStr = "Hello, world!".into();
+    /// let cow_raw = Cow::from(RawStr::new("hello!"));
+    /// let cow_str = RawStr::into_cow_str(cow_raw);
+    /// assert_eq!(&*cow_str, "hello!");
     /// ```
     pub fn into_cow_str<'a>(cow: Cow<'a, RawStr>) -> Cow<'a, str> {
         match cow {
@@ -129,7 +143,7 @@ impl RawStr {
         }
     }
 
-    /// Performs percent decoding.
+    /// Percent-decodes `self`.
     fn _percent_decode(&self) -> percent_encoding::PercentDecode<'_> {
         percent_encoding::percent_decode(self.as_bytes())
     }
@@ -752,7 +766,6 @@ impl RawStr {
         }
     }
 
-
     /// Returns a string slice with the prefix removed.
     ///
     /// If the string starts with the pattern `prefix`, returns substring after
@@ -815,15 +828,11 @@ impl RawStr {
     /// helps the inference algorithm understand specifically which type
     /// you're trying to parse into.
     ///
-    /// `parse` can parse any type that implements the [`FromStr`] trait.
-    ///
     /// # Errors
     ///
-    /// Will return [`Err`] if it's not possible to parse this string slice into
+    /// Will return `Err` if it's not possible to parse this string slice into
     /// the desired type.
     ///
-    /// [`Err`]: FromStr::Err
-    ///
     /// # Examples
     ///
     /// Basic usage
@@ -880,6 +889,18 @@ impl<'a> From<&'a str> for &'a RawStr {
     }
 }
 
+impl<'a> From<&'a RawStr> for Cow<'a, RawStr> {
+    fn from(raw: &'a RawStr) -> Self {
+        Cow::Borrowed(raw)
+    }
+}
+
+impl From<RawStrBuf> for Cow<'_, RawStr> {
+    fn from(raw: RawStrBuf) -> Self {
+        Cow::Owned(raw)
+    }
+}
+
 macro_rules! impl_partial {
     ($A:ty : $B:ty) => (
         impl PartialEq<$A> for $B {
@@ -933,6 +954,20 @@ impl AsRef<str> for RawStr {
     }
 }
 
+impl AsRef<RawStr> for str {
+    #[inline(always)]
+    fn as_ref(&self) -> &RawStr {
+        RawStr::new(self)
+    }
+}
+
+impl AsRef<RawStr> for RawStr {
+    #[inline(always)]
+    fn as_ref(&self) -> &RawStr {
+        self
+    }
+}
+
 impl AsRef<[u8]> for RawStr {
     #[inline(always)]
     fn as_ref(&self) -> &[u8] {