aversion 0.2.1

Versioned data structures with auto-upgrading
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174

use crate::group::GroupHeader;
use crate::{MessageId, Versioned};
use byteorder::{BigEndian, ReadBytesExt, WriteBytesExt};
use std::io::{self, Read, Write};

/// A header that can be serialized into a fixed-size buffer.
///
/// This header does not use serde; it serializes to a binary
/// (big-endian) array of 4 bytes.
#[derive(Debug, Clone, Copy)]
pub struct TinyHeader {
    /// The message id.
    pub msg_id: u16,
    /// The message version.
    pub msg_ver: u16,
}

impl TinyHeader {
    /// Create a new `TinyHeader`
    pub fn new(msg_id: u16, msg_ver: u16) -> Self {
        TinyHeader { msg_id, msg_ver }
    }

    /// Create a new `TinyHeader` that corresponds to a type.
    ///
    /// The version and message id values will be filled in from
    /// the type's [`Versioned`] and [`MessageId`] associated
    /// constants.
    pub fn for_msg<T>(_msg: &T) -> Self
    where
        T: Versioned,
        T::Base: MessageId,
    {
        TinyHeader {
            msg_id: T::Base::MSG_ID,
            msg_ver: T::VER,
        }
    }

    /// Deserialize a header from a `Read` stream.
    pub fn deserialize_from(r: &mut impl Read) -> Result<Self, io::Error> {
        let msg_id = r.read_u16::<BigEndian>()?;
        let msg_ver = r.read_u16::<BigEndian>()?;
        Ok(TinyHeader { msg_id, msg_ver })
    }

    /// Deserialize a header from a 4-byte slice.
    pub fn deserialize(buf: impl AsRef<[u8; 4]>) -> Self {
        // Use a &[u8] as the Read stream.
        let mut buf: &[u8] = buf.as_ref();
        // No io::Error is possible, since we're doing no actual IO.
        Self::deserialize_from(&mut buf).unwrap()
    }

    /// Serialize a header into a `Write` stream.
    pub fn serialize_into(self, w: &mut impl Write) -> Result<(), io::Error> {
        w.write_u16::<BigEndian>(self.msg_id)?;
        w.write_u16::<BigEndian>(self.msg_ver)?;
        Ok(())
    }

    /// Serialize a header into a 4-byte array.
    pub fn serialize(self) -> [u8; 4] {
        let mut buf = [0u8; 4];
        // Use a &[u8] as the Write stream.
        let mut cursor: &mut [u8] = buf.as_mut();
        // No io::Error is possible, since we're doing no actual IO.
        self.serialize_into(&mut cursor).unwrap();
        buf
    }
}

impl GroupHeader for TinyHeader {
    fn msg_id(&self) -> u16 {
        self.msg_id
    }

    fn msg_ver(&self) -> u16 {
        self.msg_ver
    }
}

/// A header that can be serialized into a fixed-size buffer.
///
/// This header does not use serde; it serializes to a binary
/// (big-endian) array of 8 bytes.
///
/// Unlike [`TinyHeader`], this header includes a message length
/// value, which may make deserialization easier or more efficient.
#[derive(Debug, Clone, Copy)]
pub struct BasicHeader {
    /// The message id.
    pub msg_id: u16,
    /// The message version.
    pub msg_ver: u16,
    /// The length of the message when serialized.
    pub msg_len: u32,
}

impl BasicHeader {
    /// Create a new `BasicHeader`.
    pub fn new(msg_id: u16, msg_ver: u16, msg_len: u32) -> Self {
        BasicHeader {
            msg_id,
            msg_ver,
            msg_len,
        }
    }

    /// Create a new `BasicHeader` that corresponds to a type.
    ///
    /// The version and message id values will be filled in from
    /// the type's [`Versioned`] and [`MessageId`] associated
    /// constants.
    pub fn for_msg<T>(_msg: &T, msg_len: u32) -> Self
    where
        T: Versioned,
        T::Base: MessageId,
    {
        BasicHeader {
            msg_id: T::Base::MSG_ID,
            msg_ver: T::VER,
            msg_len,
        }
    }

    /// Deserialize a header from a `Read` stream.
    pub fn deserialize_from(r: &mut impl Read) -> Result<Self, io::Error> {
        let msg_id = r.read_u16::<BigEndian>()?;
        let msg_ver = r.read_u16::<BigEndian>()?;
        let msg_len = r.read_u32::<BigEndian>()?;
        Ok(BasicHeader {
            msg_id,
            msg_ver,
            msg_len,
        })
    }

    /// Deserialize a header from a 4-byte slice.
    pub fn deserialize(buf: impl AsRef<[u8; 4]>) -> Self {
        // Use a &[u8] as the Read stream.
        let mut buf: &[u8] = buf.as_ref();
        // No io::Error is possible, since we're doing no actual IO.
        Self::deserialize_from(&mut buf).unwrap()
    }

    /// Serialize a header into a `Write` stream.
    pub fn serialize_into(self, w: &mut impl Write) -> Result<(), io::Error> {
        w.write_u16::<BigEndian>(self.msg_id)?;
        w.write_u16::<BigEndian>(self.msg_ver)?;
        w.write_u32::<BigEndian>(self.msg_len)?;
        Ok(())
    }

    /// Serialize a header into a 4-byte array.
    pub fn serialize(self) -> [u8; 4] {
        let mut buf = [0u8; 4];
        // Use a &[u8] as the Write stream.
        let mut cursor: &mut [u8] = buf.as_mut();
        // No io::Error is possible, since we're doing no actual IO.
        self.serialize_into(&mut cursor).unwrap();
        buf
    }
}

impl GroupHeader for BasicHeader {
    fn msg_id(&self) -> u16 {
        self.msg_id
    }

    fn msg_ver(&self) -> u16 {
        self.msg_ver
    }
}