codas 0.7.1

Markdown-defined data that serialize to and from bytes on any platform—from web apps to robots!
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

//! Codec encoder implementations.
use crate::stream::Writes;

use super::{CodecError, DataHeader, Format};

/// A thing that encodes into
/// [`codec`](super)-compliant data.
pub trait Encodable {
    /// This thing's [`Format`].
    const FORMAT: Format;

    /// Encodes this thing's data into `writer`
    /// _without_ encoding a [`DataHeader`].
    ///
    /// In most cases, [`WritesEncodable::write_data`] should
    /// be used instead of calling this function directly.
    ///
    /// ```rust
    /// # use codas::types::Text;
    /// # use crate::codas::codec::{Encodable, Decodable, DataHeader};
    ///
    /// let data = Text::from("cupcakes!");
    ///
    /// // Encode data into a vector.
    /// let mut encoded = vec![];
    /// data.encode_header(&mut encoded).unwrap();
    /// data.encode(&mut encoded).unwrap();
    /// let mut encoded_slice = encoded.as_slice();
    ///
    /// // Decode the header.
    /// let mut decoded_header = DataHeader::default();
    /// decoded_header.decode(&mut encoded_slice, None).unwrap();
    ///
    /// // Decode the data.
    /// let mut decoded_data = Text::default();
    /// decoded_data.decode(&mut encoded_slice, Some(decoded_header)).unwrap();
    ///
    /// assert_eq!(data, decoded_data);
    /// ```
    fn encode(&self, writer: &mut (impl WritesEncodable + ?Sized)) -> Result<(), CodecError>;

    /// Encodes this thing's data _header_ into `writer`.
    ///
    /// If `Self`'s [`Encodable::FORMAT`] is not
    /// [`structured`](`Format::is_structured`),
    /// this function should be a no-op.
    #[inline(always)]
    fn encode_header(
        &self,
        writer: &mut (impl WritesEncodable + ?Sized),
    ) -> Result<(), CodecError> {
        match Self::FORMAT {
            Format::Blob(_) => Ok(()),
            Format::Data(format) => DataHeader { count: 1, format }.encode(writer),
            Format::Fluid => {
                unimplemented!("fluid formats must manually implement `encode_header`")
            }
        }
    }
}

/// A thing that [`Writes`] [`Encodable`] data.
///
/// ```rust
/// # use codas::types::Text;
/// # use crate::codas::codec::{WritesEncodable, ReadsDecodable};
///
/// let data = Text::from("cupcakes!");
///
/// // Encode data into a vector.
/// let mut encoded = vec![];
/// encoded.write_data(&data).unwrap();
///
/// // Decode the data.
/// let decoded_data: Text = encoded.as_slice().read_data().unwrap();
///
/// assert_eq!(data, decoded_data);
/// ```
///
/// This trait is automatically implemented for
/// any type that [`Writes`].
pub trait WritesEncodable: Writes {
    /// Encodes and writes a sequence of data from `data`.
    ///
    /// This function will attempt to encode and write a
    /// [`DataHeader`] if the `data`'s [`Format::is_structured`].
    fn write_data<T: Encodable + ?Sized>(&mut self, data: &T) -> Result<(), CodecError> {
        data.encode_header(self)?;
        data.encode(self)?;

        Ok(())
    }
}

impl<T: Writes + ?Sized> WritesEncodable for T {}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::codec::tests::*;

    #[test]
    fn encodes() -> Result<(), CodecError> {
        let mut bytes = Vec::new();

        // Allocate test data.
        let test_data = TestData::default();

        // Encode header.
        bytes.write_data(&DataHeader {
            count: 1,
            format: TestData::FORMAT.as_data_format(),
        })?;

        // Encode blob fields.
        bytes.write_data(&test_data.num_a)?;
        bytes.write_data(&test_data.num_b)?;

        // Encode data fields.
        bytes.write_data(&test_data.text)?;

        // Check encoding.
        let mut expected = Vec::new();
        encode_test_data(&mut expected);
        assert_eq!(expected, bytes);

        Ok(())
    }
}