abomonation 0.7.3

A high performance and very unsafe serialization library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127


use std::mem::transmute;
use std::marker::PhantomData;
use std::ops::{Deref, DerefMut};

use super::{Abomonation, decode};

/// A type wrapping owned decoded abomonated data.
///
/// This type ensures that decoding and pointer correction has already happened,
/// and implements `Deref<Target=T>` using a pointer cast (transmute).
///
/// #Safety
///
/// The safety of this type, and in particular its `transute` implementation of
/// the `Deref` trait, relies on the owned bytes not being externally mutated
/// once provided. You could imagine a new type implementing `DerefMut` as required,
/// but which also retains the ability (e.g. through `RefCell`) to mutate the bytes.
/// This would be very bad, but seems hard to prevent in the type system. Please
/// don't do this.
///
/// You must also use a type `S` whose bytes have a fixed location in memory.
/// Otherwise moving an instance of `Abomonated<T, S>` may invalidate decoded
/// pointers, and everything goes badly.
///
/// #Examples
///
/// ```
/// use std::ops::Deref;
/// use abomonation::{encode, decode};
/// use abomonation::abomonated::Abomonated;
///
/// // create some test data out of abomonation-approved types
/// let vector = (0..256u64).map(|i| (i, format!("{}", i)))
///                         .collect::<Vec<_>>();
///
/// // encode a Vec<(u64, String)> into a Vec<u8>
/// let mut bytes = Vec::new();
/// unsafe { encode(&vector, &mut bytes); }
///
/// // attempt to decode `bytes` into a `&Vec<(u64, String)>`.
/// let maybe_decoded = unsafe { Abomonated::<Vec<(u64, String)>,_>::new(bytes) };
///
/// if let Some(decoded) = maybe_decoded {
///     // each `deref()` call is now just a pointer cast.
///     assert!(decoded.deref() == &vector);
/// }
/// else {
///     panic!("failed to decode");
/// }
/// ```
pub struct Abomonated<T, S: DerefMut<Target=[u8]>> {
    phantom: PhantomData<T>,
    decoded: S,
}

impl<T: Abomonation, S: DerefMut<Target=[u8]>> Abomonated<T, S> {

    /// Attempts to create decoded data from owned mutable bytes.
    ///
    /// This method will return `None` if it is unable to decode the data with
    /// type `T`.
    ///
    /// #Examples
    ///
    /// ```
    /// use std::ops::Deref;
    /// use abomonation::{encode, decode};
    /// use abomonation::abomonated::Abomonated;
    ///
    /// // create some test data out of abomonation-approved types
    /// let vector = (0..256u64).map(|i| (i, format!("{}", i)))
    ///                         .collect::<Vec<_>>();
    ///
    /// // encode a Vec<(u64, String)> into a Vec<u8>
    /// let mut bytes = Vec::new();
    /// unsafe { encode(&vector, &mut bytes); }
    ///
    /// // attempt to decode `bytes` into a `&Vec<(u64, String)>`.
    /// let maybe_decoded = unsafe { Abomonated::<Vec<(u64, String)>,_>::new(bytes) };
    ///
    /// if let Some(decoded) = maybe_decoded {
    ///     // each `deref()` call is now just a pointer cast.
    ///     assert!(decoded.deref() == &vector);
    /// }
    /// else {
    ///     panic!("failed to decode");
    /// }
    /// ```
    ///
    /// #Safety
    ///
    /// The type `S` must have its bytes at a fixed location, which will
    /// not change if the `bytes: S` instance is moved. Good examples are
    /// `Vec<u8>` whereas bad examples are `[u8; 16]`.
    pub unsafe fn new(mut bytes: S) -> Option<Self> {

        // performs the underlying pointer correction, indicates success.
        let decoded = decode::<T>(bytes.deref_mut()).is_some();

        if decoded {
            Some(Abomonated {
                phantom: PhantomData,
                decoded: bytes,
            })
        }
        else {
            None
        }
    }
}

impl<T, S: DerefMut<Target=[u8]>> Abomonated<T, S> {
    pub fn as_bytes(&self) -> &[u8] {
        &self.decoded
    }
}


impl<T, S: DerefMut<Target=[u8]>> Deref for Abomonated<T, S> {
    type Target = T;
    #[inline]
    fn deref(&self) -> &T {
        let result: &T = unsafe { transmute(self.decoded.get_unchecked(0)) };
        result
    }
}