fef 0.2.3

Rust implementation of a parser of the FEF format
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

use std::io::{Read, Write};

use crate::{
    common::traits::private::Sealed,
    v0::{
        config::Config,
        metadata::{
            error::{
                MetadataIdentifierOutOfRangeError, MetadataRecordReadError,
                MetadataRecordWriteError,
            },
            traits::MetadataRecordObj,
        },
        raw::VariableLengthEnum,
        tokens::{error::MetadataTokenError, MetadataToken},
        traits::{ReadFrom, WriteTo},
    },
};

use super::ReservedMetadataRecord;
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
/// Metadata record with identifier reserved for custom use by any implementor.
///
/// # Example
///
/// Creating a custom metadata record:
/// ```rust
/// # use fef::v0::metadata::CustomReservedMetadataRecordObj;
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let record = CustomReservedMetadataRecordObj::new(0x100100, vec![0x12, 0x34])?;
///
/// assert_eq!(record.identifier(), 0x100100);
/// assert_eq!(record.data(), &[0x12, 0x34]);
/// # Ok(())
/// # }
/// ```
pub struct CustomReservedMetadataRecordObj {
    pub(crate) identifier: u32,
    data: Vec<u8>,
}

impl Sealed for CustomReservedMetadataRecordObj {}

impl MetadataRecordObj for CustomReservedMetadataRecordObj {
    fn token(&self) -> Result<MetadataToken, MetadataTokenError> {
        Ok(MetadataToken::ReservedOfficial(self.identifier))
    }
    fn byte_length(&self) -> usize {
        self.data.len()
    }
}

impl CustomReservedMetadataRecordObj {
    /// Reads a custom reserved metadata record from a reader.
    ///
    /// This method expects the identifier for this record is already read (it must be in order to know which type of record to read), but requires this identifier to be passed as an argument.
    pub(crate) fn read_from<C: ?Sized + Config, R: ?Sized + Read>(
        reader: &mut R,
        configuration: &C,
        identifier: u32,
    ) -> Result<Self, MetadataRecordReadError> {
        let length: usize = VariableLengthEnum::read_from(reader, configuration)?.try_into()?;
        let mut data = Vec::with_capacity(length);
        reader.take(length as u64).read_to_end(&mut data)?;
        Ok(Self { identifier, data })
    }
}

impl<W: ?Sized + Write> WriteTo<W> for CustomReservedMetadataRecordObj {
    type WriteError = MetadataRecordWriteError;
    /// Writes the custom reserved metadata record to a writer.
    ///
    /// This method writes the length of the data and then the data itself. It does not write the identifier.
    ///
    /// # Example
    /// ```rust
    /// # use fef::v0::metadata::CustomReservedMetadataRecordObj;
    /// # use fef::v0::config::DEFAULT_CONFIG;
    /// # use fef::v0::traits::WriteTo;
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let record = CustomReservedMetadataRecordObj::new(0x100100, vec![0x12, 0x34])?;
    /// let mut writer: Vec<u8> = Vec::new();
    /// record.write_to(&mut writer, &DEFAULT_CONFIG)?;
    /// assert_eq!(writer, vec![0x02, 0x12, 0x34]);
    /// # Ok(())
    /// # }
    /// ```
    fn write_to<C: ?Sized + Config>(
        &self,
        writer: &mut W,
        configuration: &C,
    ) -> Result<(), Self::WriteError> {
        VariableLengthEnum::from(self.data.len()).write_to(writer, configuration)?;
        writer.write_all(&self.data)?;
        Ok(())
    }
}

impl CustomReservedMetadataRecordObj {
    /// Creates a new custom reserved metadata record.
    ///
    /// Checks, if the identifier is in the reserved range for custom records.
    /// If the identifier is out of range, returns an error.
    ///
    /// # Example
    ///
    /// Correctly creating a custom reserved metadata record:
    /// ```rust
    /// # use fef::v0::metadata::CustomReservedMetadataRecordObj;
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let record = CustomReservedMetadataRecordObj::new(0x100100, vec![0x12, 0x34]);
    /// assert!(record.is_ok());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// Incorrectly creating a custom reserved metadata record with out of range identifier:
    /// ```rust
    /// # use fef::v0::metadata::CustomReservedMetadataRecordObj;
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let record = CustomReservedMetadataRecordObj::new(0x01, vec![0x12, 0x34]);
    /// assert!(record.is_err());
    /// # Ok(())
    /// # }
    pub fn new(identifier: u32, data: Vec<u8>) -> Result<Self, MetadataIdentifierOutOfRangeError> {
        if !(0x100000u32..0x1FFFFFu32).contains(&identifier) {
            return Err(MetadataIdentifierOutOfRangeError::custom_key(identifier));
        }
        Ok(Self { identifier, data })
    }

    /// Returns the identifier of the custom reserved metadata record.
    pub fn identifier(&self) -> u32 {
        self.identifier
    }

    /// Returns the data of the custom reserved metadata record.
    pub fn data(&self) -> &[u8] {
        &self.data
    }
}

impl Into<ReservedMetadataRecord> for CustomReservedMetadataRecordObj {
    fn into(self) -> ReservedMetadataRecord {
        ReservedMetadataRecord::Custom(self)
    }
}