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: Debug + 'a> Debug for RefBox<'a, T>

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

Formats the value using the given formatter.

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> Deref for RefBox<'a, T>

type Target = T

The resulting type after dereferencing

fn deref(&self) -> &T

The method called to dereference a value