brec 0.5.0

A flexible binary format for storing and streaming structured data as packets with CRC protection and recoverability from corruption. Built for extensibility and robustness.
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

/// Result type representing the outcome of a read attempt.
///
/// `ReadStatus` allows distinguishing between successful reads and cases
/// where more data is required to complete the read.
pub enum ReadStatus<T> {
    /// The read operation succeeded and produced a value of type `T`.
    Success(T),

    /// The read operation failed due to insufficient data.
    ///
    /// Contains the number of additional bytes required to complete the read.
    NotEnoughData(u64),
}

impl<T> ReadStatus<T> {
    /// Maps the inner `Success` value using the provided function.
    ///
    /// If the status is `Success`, applies `mapper` to the inner value and returns
    /// a new `ReadStatus::Success`. If the status is `NotEnoughData`, it is returned unchanged.
    ///
    /// # Arguments
    /// * `mapper` - A function to apply to the `Success` value.
    ///
    /// # Returns
    /// A new `ReadStatus` with the mapped type.
    pub fn map<K, F>(self, mapper: F) -> ReadStatus<K>
    where
        F: FnOnce(T) -> K,
    {
        match self {
            ReadStatus::Success(value) => ReadStatus::Success(mapper(value)),
            ReadStatus::NotEnoughData(n) => ReadStatus::NotEnoughData(n),
        }
    }
}

/// Result type representing the outcome of a packet read attempt.
///
/// This type intentionally evolves separately from `ReadStatus` because packet-level
/// reading may need to carry additional metadata that is not relevant for block or
/// payload readers.
pub enum PacketReadStatus<T> {
    /// The packet read operation succeeded and produced a value of type `T`.
    #[cfg(not(feature = "resilient"))]
    Success(T),

    /// The packet was read successfully together with skipped unknown entities.
    #[cfg(feature = "resilient")]
    Success((T, Vec<crate::Unrecognized>)),

    /// The packet read operation failed due to insufficient data.
    ///
    /// Contains the number of additional bytes required to complete the read.
    NotEnoughData(u64),
}

impl<T> PacketReadStatus<T> {
    #[cfg(feature = "resilient")]
    pub fn success(value: T, unrecognized: Vec<crate::Unrecognized>) -> Self {
        Self::Success((value, unrecognized))
    }

    #[cfg(not(feature = "resilient"))]
    pub fn success(value: T) -> Self {
        Self::Success(value)
    }
}