Struct kserd::encode::Decoder

pub struct Decoder<'de>(pub Kserd<'de>);

Decoder to pass to Deserialize::deserialize to decode a Kserd into a type.

Decoder consumes the Kserd structure. It is important to understand how this interacts with the Deserialize implementor. Because Kserd tries to reduce copying, using clone-on-write pointers for strings and byte arrays, there are extra cases to be handled to achieve the minimal amount of copying data. The Decoder was designed to leverage movement of data as much as possible, however this presents a unique case when decoding back to a type that contains borrowed data.

The table below captures different memory operations using Decoder:

Kserd ownership	Rust type	Data transfer
Owned	Owned	move
Borrowed	Owned	copy
Borrowed	Borrowed	move (ptr)
Owned	Borrowed	unique

As the Kserd is consumed, owned data can be directly moved, whilst borrowed data can be cloned if needing to be come owned, or the pointer can be moved. The only case where this breaks is if the Kserd is owned and an attempt is made to decode it back into borrowed data. The failing occurs because the owned data will be dropped after the deserialize call.

If borrowed data is required, the solution is to decode a Kserd which itself is a reference to the owned Kserd. The method .mk_brw() does this. There is small overhead as nested structures have to be reallocated, but strings and byte arrays are made to point to the original Kserd structure. The 'borrowed' Kserd does not really differ that much, expect that it is gauranteed to not contain owned data. This makes the fourth case not possible and the decoding to succeed.

It is worth noting that it may increase the amount of copying occurring, as previously owned data is now borrowed. It is therefore recommended to not borrow the Kserd unless necessary.

Kserd::decode can be used for conveniance.

Examples

Kserds containing borrowed data can decode into borrowed or owned types.

use kserd::encode::Decoder;
use serde::Deserialize;

let string = String::from("Hello, world!");

// decode into borrowed type
let kserd = Kserd::new_str(&string);
let decoder = Decoder(kserd);
let s = <&str>::deserialize(decoder).unwrap();
assert_eq!(s, "Hello, world!");

// decode into owned type
let kserd = Kserd::new_str(&string);
let decoder = Decoder(kserd);
let s = <String>::deserialize(decoder).unwrap();
assert_eq!(s, string);

Kserds which own their data can decode into owned types, but error on borrowed types.

use kserd::encode::Decoder;
use serde::Deserialize;

// decode into owned type works
let kserd = Kserd::new_string(String::from("Hello, world!"));
let decoder = Decoder(kserd);
let s = <String>::deserialize(decoder).unwrap();
assert_eq!(s, "Hello, world!".to_string());

// decode into borrowed type fails
let kserd = Kserd::new_string(String::from("Hello, world!"));
let decoder = Decoder(kserd);
let r = <&str>::deserialize(decoder);
assert_eq!(r.is_err(), true);

Borrowing the Kserd beforehand extends the lifetime.

use kserd::encode::Decoder;
use serde::Deserialize;

let kserd = Kserd::new_string(String::from("Hello, world!"));
let decoder = Decoder(kserd.mk_brw());
let s = <&str>::deserialize(decoder).unwrap();
assert_eq!(s, "Hello, world!");

Trait Implementations

impl<'de> Deserializer<'de> for Decoder<'de>

type Error = Error

The error type that can be returned if some error occurs during deserialization.

fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, Error> where
    V: Visitor<'de>, 

Require the Deserializer to figure out how to drive the visitor based on what data type is in the input.

fn deserialize_bool<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a bool value.

fn deserialize_i8<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting an i8 value.

fn deserialize_i16<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting an i16 value.

fn deserialize_i32<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting an i32 value.

fn deserialize_i64<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting an i64 value.

fn deserialize_i128<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting an i128 value.

fn deserialize_u8<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a u8 value.

fn deserialize_u16<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a u16 value.

fn deserialize_u32<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a u32 value.

fn deserialize_u64<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a u64 value.

fn deserialize_u128<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting an u128 value.

fn deserialize_f32<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a f32 value.

fn deserialize_f64<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a f64 value.

fn deserialize_str<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a string value and does not benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_string<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a string value and would benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_bytes<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a byte array and does not benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_byte_buf<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a byte array and would benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_option<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting an optional value.

fn deserialize_unit<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a unit value.

fn deserialize_unit_struct<V>(
    self,
    name: &'static str,
    visitor: V
) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a unit struct with a particular name.

fn deserialize_newtype_struct<V>(
    self,
    name: &'static str,
    visitor: V
) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a newtype struct with a particular name.

fn deserialize_seq<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a sequence of values.

fn deserialize_tuple<V>(
    self,
    len: usize,
    visitor: V
) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a sequence of values and knows how many values there are without looking at the serialized data.

fn deserialize_tuple_struct<V>(
    self,
    name: &'static str,
    len: usize,
    visitor: V
) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a tuple struct with a particular name and number of fields.

fn deserialize_map<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a map of key-value pairs.

fn deserialize_struct<V>(
    self,
    name: &'static str,
    fields: &'static [&'static str],
    visitor: V
) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting a struct with a particular name and fields.

fn deserialize_identifier<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type is expecting the name of a struct field or the discriminant of an enum variant.

fn deserialize_ignored_any<V>(self, visitor: V) -> Result<V::Value, Self::Error> where
    V: Visitor<'de>, 

Hint that the Deserialize type needs to deserialize a value whose type doesn't matter because it is ignored.

fn deserialize_char<V: Visitor<'de>>(
    self,
    visitor: V
) -> Result<V::Value, Error>

Hint that the Deserialize type is expecting a char value.

fn deserialize_enum<V: Visitor<'de>>(
    self,
    _name: &'static str,
    _variants: &'static [&'static str],
    visitor: V
) -> Result<V::Value, Error>

Hint that the Deserialize type is expecting an enum value with a particular name and possible variants.

fn is_human_readable(&self) -> bool

Determine whether Deserialize implementations should expect to deserialize their human-readable form.

impl<'de> EnumAccess<'de> for Decoder<'de>

type Error = Error

The error type that can be returned if some error occurs during deserialization.

type Variant = Decoder<'de>

The Visitor that will be used to deserialize the content of the enum variant.

fn variant_seed<V>(self, seed: V) -> Result<(V::Value, Self::Variant), Error> where
    V: DeserializeSeed<'de>, 

variant is called to identify which variant to deserialize.

fn variant<V>(self) -> Result<(V, Self::Variant), Self::Error> where
    V: Deserialize<'de>, 

variant is called to identify which variant to deserialize.

impl<'de> VariantAccess<'de> for Decoder<'de>

type Error = Error

The error type that can be returned if some error occurs during deserialization. Must match the error type of our EnumAccess.

fn unit_variant(self) -> Result<(), Error>

Called when deserializing a variant with no values.

fn newtype_variant_seed<T>(self, seed: T) -> Result<T::Value, Error> where
    T: DeserializeSeed<'de>, 

Called when deserializing a variant with a single value.

fn tuple_variant<V>(self, len: usize, visitor: V) -> Result<V::Value, Error> where
    V: Visitor<'de>, 

Called when deserializing a tuple-like variant.

fn struct_variant<V>(
    self,
    _fields: &'static [&'static str],
    visitor: V
) -> Result<V::Value, Error> where
    V: Visitor<'de>, 

Called when deserializing a struct-like variant.

fn newtype_variant<T>(self) -> Result<T, Self::Error> where
    T: Deserialize<'de>, 

Called when deserializing a variant with a single value.