commonware_cryptography/reed_solomon/
encoder_result.rs

1use crate::reed_solomon::rate::EncoderWork;
2
3// ======================================================================
4// EncoderResult - PUBLIC
5
6/// Result of encoding. Contains the generated recovery shards.
7///
8/// This struct is created by [`Encoder::encode`]
9/// and [`RateEncoder::encode`].
10///
11/// [`RateEncoder::encode`]: crate::reed_solomon::rate::RateEncoder::encode
12/// [`Encoder::encode`]: crate::reed_solomon::Encoder::encode
13pub struct EncoderResult<'a> {
14    work: &'a mut EncoderWork,
15}
16
17impl EncoderResult<'_> {
18    /// Returns recovery shard with given `index`
19    /// or `None` if `index >= recovery_count`.
20    ///
21    /// Recovery shards have indexes `0..recovery_count`
22    /// and these same indexes must be used when decoding.
23    pub fn recovery(&self, index: usize) -> Option<&[u8]> {
24        self.work.recovery(index)
25    }
26
27    /// Returns iterator over all recovery shards ordered by their indexes.
28    ///
29    /// Recovery shards have indexes `0..recovery_count`
30    /// and these same indexes must be used when decoding.
31    pub const fn recovery_iter(&self) -> Recovery<'_> {
32        Recovery::new(self.work)
33    }
34}
35
36// ======================================================================
37// EncoderResult - CRATE
38
39impl<'a> EncoderResult<'a> {
40    pub(crate) const fn new(work: &'a mut EncoderWork) -> Self {
41        Self { work }
42    }
43}
44
45// ======================================================================
46// EncoderResult - IMPL DROP
47
48impl Drop for EncoderResult<'_> {
49    fn drop(&mut self) {
50        self.work.reset_received();
51    }
52}
53
54// ======================================================================
55// Recovery - PUBLIC
56
57/// Iterator over generated recovery shards.
58///
59/// This struct is created by [`EncoderResult::recovery_iter`].
60pub struct Recovery<'a> {
61    ended: bool,
62    next_index: usize,
63    work: &'a EncoderWork,
64}
65
66// ======================================================================
67// Recovery - IMPL Iterator
68
69impl<'a> Iterator for Recovery<'a> {
70    type Item = &'a [u8];
71    fn next(&mut self) -> Option<&'a [u8]> {
72        if self.ended {
73            None
74        } else if let Some(next) = self.work.recovery(self.next_index) {
75            self.next_index += 1;
76            Some(next)
77        } else {
78            self.ended = true;
79            None
80        }
81    }
82
83    fn size_hint(&self) -> (usize, Option<usize>) {
84        let remaining = self.work.recovery_count() - self.next_index;
85        (remaining, Some(remaining))
86    }
87}
88
89// ======================================================================
90// Recovery - IMPL ExactSizeIterator
91
92impl ExactSizeIterator for Recovery<'_> {}
93
94// ======================================================================
95// Recovery - CRATE
96
97impl<'a> Recovery<'a> {
98    pub(crate) const fn new(work: &'a EncoderWork) -> Self {
99        Self {
100            ended: false,
101            next_index: 0,
102            work,
103        }
104    }
105}
106
107// ======================================================================
108// TESTS
109
110#[cfg(test)]
111mod tests {
112    use super::*;
113    use crate::reed_solomon::{test_util, Encoder};
114    #[cfg(not(feature = "std"))]
115    use alloc::vec::Vec;
116
117    #[test]
118    // EncoderResult::recovery
119    // EncoderResult::recovery_iter
120    // Recovery
121    fn encoder_result() {
122        let original = test_util::generate_original(2, 1024, 123);
123        let mut encoder = Encoder::new(2, 3, 1024).unwrap();
124
125        for original in &original {
126            encoder.add_original_shard(original).unwrap();
127        }
128
129        let result: EncoderResult<'_> = encoder.encode().unwrap();
130
131        let all = vec![
132            result.recovery(0).unwrap(),
133            result.recovery(1).unwrap(),
134            result.recovery(2).unwrap(),
135        ];
136        assert!(result.recovery(3).is_none());
137        test_util::assert_hash(all, test_util::LOW_2_3);
138
139        let mut iter: Recovery<'_> = result.recovery_iter();
140        let all = vec![
141            iter.next().unwrap(),
142            iter.next().unwrap(),
143            iter.next().unwrap(),
144        ];
145        assert!(iter.next().is_none());
146        test_util::assert_hash(all, test_util::LOW_2_3);
147    }
148
149    #[test]
150    fn encoder_result_size_hint() {
151        let original = test_util::generate_original(2, 1024, 123);
152        let mut encoder = Encoder::new(2, 3, 1024).unwrap();
153
154        for original in &original {
155            encoder.add_original_shard(original).unwrap();
156        }
157
158        let result: EncoderResult<'_> = encoder.encode().unwrap();
159
160        let mut iter: Recovery<'_> = result.recovery_iter();
161
162        assert_eq!(iter.len(), 3);
163
164        assert!(iter.next().is_some());
165        assert!(iter.next().is_some());
166        assert_eq!(iter.len(), 1);
167
168        assert!(iter.next().is_some());
169        assert_eq!(iter.len(), 0);
170
171        assert!(iter.next().is_none());
172        assert_eq!(iter.len(), 0);
173    }
174}
commonware_cryptography/reed_solomon/encoder_result.rs

commonware_cryptography/reed_solomon/
encoder_result.rs
