Struct bincode::RefBox

pub struct RefBox<'a, T: 'a> {
    // some fields omitted
}

A struct for encoding nested reference types.

Encoding large objects by reference is really handy. For example, encode(&large_hashmap, ...) encodes the large structure without having to own the hashmap. However, it is impossible to serialize a reference if that reference is inside of a struct.

// Not possible, rustc can not decode the reference.
#[derive(RustcEncoding, RustcDecoding)]
struct Message<'a>  {
  big_map: &'a HashMap<u32, u32>,
  message_type: String,
}

This is because on the decoding side, you can't create the Message struct because it needs to have a reference to a HashMap, which is impossible because during deserialization, all members need to be owned by the deserialized object.

This is where RefBox comes in. During serialization, it serializs a reference, but during deserialization, it puts that sub-object into a box!

// This works!
#[derive(RustcEncoding, RustcDecoding)]
struct Message<'a> {
    big_map: RefBox<'a, HashMap<u32, u32>>,
    message_type: String
}

Now we can write

let my_map = HashMap::new();
let my_msg = Message {
    big_map: RefBox::new(&my_map),
    message_type: "foo".to_string()
};

let encoded = encode(&my_msg, ...).unwrap();
let decoded: Message<'static> = decode(&encoded[]).unwrap();

Notice that we managed to encode and decode a struct with a nested reference and that the decoded message has the lifetime 'static which shows us that the message owns everything inside it completely.

Please don't stick RefBox inside deep data structures. It is much better suited in the outermost layer of whatever it is that you are encoding.

Methods

impl<'a, T> RefBox<'a, T>

fn new(v: &'a T) -> RefBox<'a, T>

Creates a new RefBox that looks at a borrowed value.

impl<T> RefBox<'static, T>

fn take(self) -> Box<T>

Takes the value out of this refbox.

Fails if this refbox was not created out of a deserialization.

Unless you are doing some really weird things with static references, this function will never fail.

fn try_take(self) -> Result<Box<T>, RefBox<'static, T>>

Tries to take the value out of this refbox.

Trait Implementations

impl<'a, T: Encodable> Encodable for RefBox<'a, T>

fn encode<S: Encoder>(&self, s: &mut S) -> Result<(), S::Error>

impl<T: Decodable> Decodable for RefBox<'static, T>

fn decode<D: Decoder>(d: &mut D) -> Result<RefBox<'static, T>, D::Error>

impl<'a, T> Serialize for RefBox<'a, T> where T: Serialize

fn serialize<S>(&self, serializer: &mut S) -> Result<(), S::Error> where S: Serializer

impl<T: Deserialize> Deserialize for RefBox<'static, T>

fn deserialize<D>(deserializer: &mut D) -> Result<Self, D::Error> where D: Deserializer

impl<'a, T> Deref for RefBox<'a, T>

type Target = T

fn deref(&self) -> &T

Derived Implementations

impl<'a, T: Clone + 'a> Clone for RefBox<'a, T>

fn clone(&self) -> RefBox<'a, T>

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

impl<'a, T: Hash + 'a> Hash for RefBox<'a, T>

fn hash<__H: Hasher>(&self, __arg_0: &mut __H)

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher

impl<'a, T: Ord + 'a> Ord for RefBox<'a, T>

fn cmp(&self, __arg_0: &RefBox<'a, T>) -> Ordering

impl<'a, T: Eq + 'a> Eq for RefBox<'a, T>

impl<'a, T: PartialOrd + 'a> PartialOrd for RefBox<'a, T>

fn partial_cmp(&self, __arg_0: &RefBox<'a, T>) -> Option<Ordering>

fn lt(&self, __arg_0: &RefBox<'a, T>) -> bool

fn le(&self, __arg_0: &RefBox<'a, T>) -> bool

fn gt(&self, __arg_0: &RefBox<'a, T>) -> bool

fn ge(&self, __arg_0: &RefBox<'a, T>) -> bool

impl<'a, T: PartialEq + 'a> PartialEq for RefBox<'a, T>

fn eq(&self, __arg_0: &RefBox<'a, T>) -> bool

fn ne(&self, __arg_0: &RefBox<'a, T>) -> bool

impl<'a, T: Debug + 'a> Debug for RefBox<'a, T>

fn fmt(&self, __arg_0: &mut Formatter) -> Result