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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Feeds this value into the state given, updating the hasher as necessary.

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

Feeds a slice of this type into the state provided.

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

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

This method returns an Ordering between self and other.

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>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

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> Serialize for RefBox<'a, T> where T: Serialize

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

Serializes this value into this serializer.

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

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

Deserialize this value given this Deserializer.

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