Struct serde_with::BorrowCow

pub struct BorrowCow;

Borrow Cow data during deserialization when possible.

The types Cow<'a, [u8]>, Cow<'a, [u8; N]>, and Cow<'a, str> can borrow from the input data during deserialization. serde supports this, by annotating the fields with #[serde(borrow)]. but does not support borrowing on nested types. This gap is filled by this BorrowCow adapter.

Using this adapter with Cow<'a, [u8]>/Cow<’a, [u8; N]>will serialize the value as a sequence ofu8 values. This *might* not allow to borrow the data during deserialization. For a different format, which is also more efficient, use the [Bytes] adapter, which is also implemented for Cow`.

When combined with the serde_as attribute, the #[serde(borrow)] annotation will be added automatically. If the annotation is wrong or too broad, for example because of multiple lifetime parameters, a manual annotation is required.

Examples

#[serde_as]
#[derive(Deserialize, Serialize)]
struct Data<'a, 'b, 'c> {
    #[serde_as(as = "BorrowCow")]
    str: Cow<'a, str>,
    #[serde_as(as = "BorrowCow")]
    slice: Cow<'b, [u8]>,

    #[serde_as(as = "Option<[BorrowCow; 1]>")]
    nested: Option<[Cow<'c, str>; 1]>,
}
let data = Data {
    str: "foobar".into(),
    slice: b"foobar"[..].into(),
    nested: Some(["HelloWorld".into()]),
};

// Define our expected JSON form
let j = r#"{
  "str": "foobar",
  "slice": [
    102,
    111,
    111,
    98,
    97,
    114
  ],
  "nested": [
    "HelloWorld"
  ]
}"#;
// Ensure serialization and deserialization produce the expected results
assert_eq!(j, serde_json::to_string_pretty(&data).unwrap());
assert_eq!(data, serde_json::from_str(j).unwrap());

// Cow borrows from the input data
let deserialized: Data<'_, '_, '_> = serde_json::from_str(j).unwrap();
assert!(matches!(deserialized.str, Cow::Borrowed(_)));
assert!(matches!(deserialized.nested, Some([Cow::Borrowed(_)])));
// JSON does not allow borrowing bytes, so `slice` does not borrow
assert!(matches!(deserialized.slice, Cow::Owned(_)));

Trait Implementations

impl Clone for BorrowCow

fn clone(&self) -> BorrowCow

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BorrowCow

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BorrowCow

fn default() -> BorrowCow

Returns the “default value” for a type.

impl<'de, const N: usize> DeserializeAs<'de, Cow<'de, [u8; N]>> for BorrowCow

fn deserialize_as<D>(deserializer: D) -> Result<Cow<'de, [u8; N]>, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<'de> DeserializeAs<'de, Cow<'de, [u8]>> for BorrowCow

fn deserialize_as<D>(deserializer: D) -> Result<Cow<'de, [u8]>, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<'de> DeserializeAs<'de, Cow<'de, str>> for BorrowCow

fn deserialize_as<D>(deserializer: D) -> Result<Cow<'de, str>, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<'a, const N: usize> SerializeAs<Cow<'a, [u8; N]>> for BorrowCow

fn serialize_as<S>(
    value: &Cow<'a, [u8; N]>,
    serializer: S
) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<'a> SerializeAs<Cow<'a, [u8]>> for BorrowCow

fn serialize_as<S>(
    value: &Cow<'a, [u8]>,
    serializer: S
) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<'a> SerializeAs<Cow<'a, str>> for BorrowCow

fn serialize_as<S>(
    source: &Cow<'a, str>,
    serializer: S
) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl Copy for BorrowCow