Struct bincode::RefBox

pub struct RefBox<'a, T: 'a> { /* 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>

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

Creates a new RefBox that looks at a borrowed value.

impl<T> RefBox<'static, T>

pub 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.

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

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.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

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

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

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].

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

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

Serialize a value using an Encoder.

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

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

Deserialize a value using a Decoder.

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

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.