Skip to main content

mynd_core/
sample.rs

1use core::num::NonZeroU8;
2
3use crate::{StorageError, StorageResult};
4
5/// Byte order for storage units wider than one byte.
6#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
7pub enum ByteOrder {
8    /// Least-significant byte first.
9    LittleEndian,
10    /// Most-significant byte first.
11    BigEndian,
12}
13
14/// Bit order within a byte-addressed packed sample stream.
15#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
16pub enum BitOrder {
17    /// The first sample begins at the most-significant available bit.
18    MostSignificantFirst,
19    /// The first sample begins at the least-significant available bit.
20    LeastSignificantFirst,
21}
22
23/// The numeric class carried by a sample's stored bit pattern.
24#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
25pub enum SampleClass {
26    /// An unsigned integer sample.
27    UnsignedInteger,
28    /// A two's-complement signed integer sample.
29    SignedInteger,
30    /// An IEEE-style floating-point storage domain.
31    ///
32    /// This identifies storage only. Numeric behavior is not defined until
33    /// the floating-sample contract milestone.
34    FloatingPoint,
35}
36
37/// The physical unit containing one sample.
38#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
39pub enum StorageUnit {
40    /// Samples occupy a continuous packed-bit stream.
41    Packed(BitOrder),
42    /// Each sample occupies one byte.
43    Byte,
44    /// Each sample occupies a 16-bit word.
45    Word16(ByteOrder),
46    /// Each sample occupies a 32-bit word.
47    Word32(ByteOrder),
48    /// Each sample occupies a 64-bit word.
49    Word64(ByteOrder),
50}
51
52/// A validated sample storage domain.
53///
54/// Significant bits may be narrower than an integer storage word. Packed
55/// samples occupy exactly their significant-bit width. Floating-point samples
56/// must occupy an entire 16-, 32-, or 64-bit word.
57#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
58pub struct SampleStorage {
59    class: SampleClass,
60    significant_bits: NonZeroU8,
61    unit: StorageUnit,
62}
63
64impl SampleStorage {
65    /// Validates a numeric class, significant-bit count, and physical unit.
66    ///
67    /// # Errors
68    ///
69    /// Rejects zero bits, more than 64 packed bits, significant widths larger
70    /// than a byte or word, one-bit signed samples, and floating-point storage
71    /// that is packed, byte-sized, padded, or not 16/32/64 bits wide.
72    pub fn new(class: SampleClass, significant_bits: u8, unit: StorageUnit) -> StorageResult<Self> {
73        let significant_bits =
74            NonZeroU8::new(significant_bits).ok_or(StorageError::ZeroSampleBits)?;
75        let bits = significant_bits.get();
76        let capacity = unit_capacity(unit, bits)?;
77        if bits > capacity {
78            return Err(StorageError::SampleBitsExceedStorage);
79        }
80        if class == SampleClass::SignedInteger && bits < 2 {
81            return Err(StorageError::SignedSampleNeedsValueBit);
82        }
83        if class == SampleClass::FloatingPoint
84            && (matches!(unit, StorageUnit::Packed(_) | StorageUnit::Byte) || bits != capacity)
85        {
86            return Err(StorageError::InvalidFloatingStorage);
87        }
88        Ok(Self {
89            class,
90            significant_bits,
91            unit,
92        })
93    }
94
95    /// Returns the sample's numeric class.
96    #[must_use]
97    pub const fn class(self) -> SampleClass {
98        self.class
99    }
100
101    /// Returns the number of meaningful bits in the sample.
102    #[must_use]
103    pub const fn significant_bits(self) -> u8 {
104        self.significant_bits.get()
105    }
106
107    /// Returns the physical storage unit.
108    #[must_use]
109    pub const fn unit(self) -> StorageUnit {
110        self.unit
111    }
112
113    /// Returns the number of bits charged for each stored sample.
114    #[must_use]
115    pub const fn storage_bits(self) -> u8 {
116        match self.unit {
117            StorageUnit::Packed(_) => self.significant_bits.get(),
118            StorageUnit::Byte => 8,
119            StorageUnit::Word16(_) => 16,
120            StorageUnit::Word32(_) => 32,
121            StorageUnit::Word64(_) => 64,
122        }
123    }
124
125    /// Returns the byte order when the unit is a multi-byte word.
126    #[must_use]
127    pub const fn byte_order(self) -> Option<ByteOrder> {
128        match self.unit {
129            StorageUnit::Word16(order)
130            | StorageUnit::Word32(order)
131            | StorageUnit::Word64(order) => Some(order),
132            StorageUnit::Packed(_) | StorageUnit::Byte => None,
133        }
134    }
135
136    /// Returns the packed-stream bit order, when applicable.
137    #[must_use]
138    pub const fn bit_order(self) -> Option<BitOrder> {
139        match self.unit {
140            StorageUnit::Packed(order) => Some(order),
141            StorageUnit::Byte
142            | StorageUnit::Word16(_)
143            | StorageUnit::Word32(_)
144            | StorageUnit::Word64(_) => None,
145        }
146    }
147}
148
149const fn unit_capacity(unit: StorageUnit, packed_bits: u8) -> StorageResult<u8> {
150    match unit {
151        StorageUnit::Packed(_) => {
152            if packed_bits > 64 {
153                Err(StorageError::PackedSampleTooWide)
154            } else {
155                Ok(packed_bits)
156            }
157        }
158        StorageUnit::Byte => Ok(8),
159        StorageUnit::Word16(_) => Ok(16),
160        StorageUnit::Word32(_) => Ok(32),
161        StorageUnit::Word64(_) => Ok(64),
162    }
163}