ordcode/
buf.rs

1//! Types and traits for working with serialization and deserialization buffers
2//!
3use crate::{Result, Error};
4
5/// Simple byte reader from buffer
6///
7/// If you need to read from `&[u8]`, you may use [`DeBytesReader`] provided by this crate.
8pub trait ReadBytes {
9    /// Peek `n` bytes from head
10    fn peek<F, R>(&mut self, n: usize, f: F) -> Result<R> where F: FnOnce(&[u8]) -> Result<R>;
11
12    /// Advance buffer head by `n` bytes. `n` should be smaller than remaining buffer size.
13    fn advance(&mut self, n: usize);
14
15    /// Get `n` bytes from the beginning of buffer, advance by `n` bytes
16    fn read<F, R>(&mut self, n: usize, f: F) -> Result<R> where F: FnOnce(&[u8]) -> Result<R> {
17        let r = self.peek(n, f)?;
18        self.advance(n);
19        Ok(r)
20    }
21    /// Returns view into remaining buffer
22    fn remaining_buffer(&mut self) -> &'_[u8];
23
24    /// Check if buffer is fully consumed (empty)
25    fn is_complete(&mut self) -> Result {
26        if self.remaining_buffer().is_empty() {
27            Ok(())
28        } else {
29            Err(Error::BufferUnderflow)
30        }
31    }
32}
33
34/// Trait for reading from the tail of byte buffer
35pub trait TailReadBytes: ReadBytes {
36    fn peek_tail<F, R>(&mut self, n: usize, f: F) -> Result<R> where F: FnOnce(&[u8]) -> Result<R>;
37
38    /// Advance buffer head by `n` bytes. `n` should be smaller than remaining buffer size.
39    fn advance_tail(&mut self, n: usize);
40
41    /// Get `n` bytes from the beginning of buffer, advance by `n` bytes
42    fn read_tail<F, R>(&mut self, n: usize, f: F) -> Result<R> where F: FnOnce(&[u8]) -> Result<R> {
43        let r = self.peek_tail(n, f)?;
44        self.advance_tail(n);
45        Ok(r)
46    }
47}
48
49// forwarding for being able to use `&mut ReadBytes` in place of `ReadBytes`
50impl<'a, T> ReadBytes for &'a mut T where T: ReadBytes  {
51    fn peek<F, R>(&mut self, n: usize, f: F) -> Result<R> where F: FnOnce(&[u8]) -> Result<R> {
52        (*self).peek(n, f)
53    }
54    fn advance(&mut self, n: usize) {
55        (*self).advance(n)
56    }
57    fn remaining_buffer(&mut self) -> &'_[u8] { (*self).remaining_buffer() }
58}
59
60// forwarding for being able to use `&mut ReadBytes` in place of `ReadBytes`
61impl<'a, T> TailReadBytes for &'a mut T where T: TailReadBytes  {
62    fn peek_tail<F, R>(&mut self, n: usize, f: F) -> Result<R> where F: FnOnce(&[u8]) -> Result<R> {
63        (*self).peek_tail(n, f)
64    }
65    fn advance_tail(&mut self, n: usize) {
66        (*self).advance_tail(n)
67    }
68}
69
70/// Adapter type which implements double-ended read buffer over byte slice
71///
72/// Implements [`ReadBytes`], [`TailReadBytes`] traits and intended to be used as input to [`Deserializer`](crate::Deserializer).
73pub struct DeBytesReader<'a> {
74    buf: &'a [u8],
75}
76
77impl<'a> DeBytesReader<'a> {
78    /// Constructs reader from provided byte slice
79    #[must_use] pub fn new(buf: &'a [u8]) -> Self { Self { buf } }
80}
81
82impl <'a> ReadBytes for DeBytesReader<'a> {
83    fn peek<F, R>(&mut self, n: usize, f: F) -> Result<R>
84        where F: FnOnce(&[u8]) -> Result<R>,
85    {
86        if n <= self.buf.len() {
87            f(&self.buf[..n])
88        } else {
89            Err(Error::PrematureEndOfInput)
90        }
91    }
92    fn advance(&mut self, n: usize) {
93        self.buf = &self.buf[n..];
94        //println!("after advance {} len={}", n, self.buf.len());
95
96    }
97    fn remaining_buffer(&mut self) -> &'_[u8] { self.buf }
98}
99
100impl<'a> TailReadBytes for DeBytesReader<'a> {
101    fn peek_tail<F, R>(&mut self, n: usize, f: F) -> Result<R>
102        where F: FnOnce(&[u8]) -> Result<R>,
103    {
104        if n <= self.buf.len() {
105            f(&self.buf[(self.buf.len() - n)..])
106        } else {
107            Err(Error::PrematureEndOfInput)
108        }
109    }
110    fn advance_tail(&mut self, n: usize) {
111        self.buf = &self.buf[..self.buf.len() - n];
112        //println!("after advance_tail {} len={}", n, self.buf.len());
113    }
114}
115
116/// Adapter which implements [`ReadBytes`] for reading from the end of the buffer.
117/// ```
118/// # use ordcode::{ DeBytesReader, ReadFromTail, params, primitives::SerializableValue };
119/// let buf = vec![11, 22, 33, 44, 55, 0, 1];
120/// let mut reader = DeBytesReader::new(&buf);
121/// assert_eq!(<u16>::from_reader(ReadFromTail(&mut reader), params::AscendingOrder).unwrap(), 1);
122/// ```
123pub struct ReadFromTail<'a, R>(pub &'a mut R) where R: TailReadBytes;
124
125impl <'a, R> ReadBytes for ReadFromTail<'a, R>
126    where R: TailReadBytes,
127{
128    fn peek<F, RV>(&mut self, n: usize, f: F) -> Result<RV>
129        where F: FnOnce(&[u8]) -> Result<RV>,
130    {
131        self.0.peek_tail(n, f)
132    }
133    fn advance(&mut self, n: usize) {
134        self.0.advance_tail(n)
135    }
136    fn remaining_buffer(&mut self) -> &'_[u8] { self.0.remaining_buffer() }
137}
138
139#[cfg(feature="std")]
140impl std::io::Read for DeBytesReader<'_> {
141    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
142        self.buf.read(buf)
143    }
144}
145
146/// Trait for writer to the byte buffer
147pub trait WriteBytes {
148    /// Write to the byte buffer
149    fn write(&mut self, value: &[u8]) -> Result;
150}
151
152/// Trait for writer to the tail of byte buffer
153pub trait TailWriteBytes: WriteBytes {
154    /// Write to the tail of byte buffer
155    fn write_tail(&mut self, value: &[u8]) -> Result;
156}
157
158/// Adapter type which implements double-ended write byte buffer over mutable byte slice
159///
160/// [`DeBytesWriter`] implements [`WriteBytes`] and [`TailWriteBytes`], and can be used with [`Serializer`](crate::Serializer).
161pub struct DeBytesWriter<'a> {
162    buf: &'a mut [u8],
163    head: usize,
164    tail: usize,
165}
166
167impl<'a> DeBytesWriter<'a> {
168    /// Use provided byte slice as buffer
169    pub fn new(buf: &'a mut [u8]) -> Self {
170        let tail = buf.len();
171        Self { buf, head: 0, tail }
172    }
173    /// Finalize by collapsing extra space in internal buffer
174    ///
175    /// Returns data length, which is smaller or equal to the original buffer size.
176    pub fn finalize(&mut self) -> Result<usize> {
177        if self.head == self.tail {
178            Ok(self.buf.len())
179        } else {
180            self.buf.copy_within(self.tail.., self.head);
181            let len = self.buf.len() - (self.tail - self.head);
182            self.head = self.tail;
183            Ok(len)
184        }
185    }
186    /// Checks if buffer completely filled
187    pub fn is_complete(&self) -> Result {
188        if self.head == self.tail {
189            Ok(())
190        } else {
191            Err(Error::BufferUnderflow)
192        }
193    }
194}
195
196impl<'a> WriteBytes for DeBytesWriter<'a> {
197    fn write(&mut self, value: &[u8]) -> Result {
198        if (self.head + value.len()) > self.tail {
199            Err(Error::BufferOverflow)
200        } else {
201            self.buf[self.head..(self.head + value.len())].copy_from_slice(value);
202            self.head += value.len();
203            Ok(())
204        }
205    }
206}
207
208impl<'a> TailWriteBytes for DeBytesWriter<'a> {
209    fn write_tail(&mut self, value: &[u8]) -> Result {
210        if (self.head + value.len()) > self.tail {
211            Err(Error::BufferOverflow)
212        } else {
213            let end_offs = self.tail - value.len();
214            self.buf[end_offs..self.tail].copy_from_slice(value);
215            self.tail = end_offs;
216            Ok(())
217        }
218    }
219}
220
221/// Adapter which implements `WriteBytes` for writing to the end of double-ended buffer
222/// ```
223/// # use ordcode::{ DeBytesWriter, WriteToTail, params, primitives::SerializableValue };
224/// let mut buf = vec![0_u8; 100];
225/// let mut writer = DeBytesWriter::new(&mut buf);
226/// 1u16.to_writer(WriteToTail(&mut writer), params::AscendingOrder).unwrap();
227/// assert_eq!(&buf[98..100], &[0, 1]);
228/// ```
229pub struct WriteToTail<'a, W>(pub &'a mut W) where W: TailWriteBytes;
230
231impl<'a, W> WriteBytes for WriteToTail<'a, W>
232    where W: TailWriteBytes
233{
234    fn write(&mut self, value: &[u8]) -> Result {
235        self.0.write_tail(value)
236    }
237}
238
239// forwarding for being able to use `&mut WriteBytes` in place of `WriteBytes`
240impl<T> WriteBytes for &mut T where T: WriteBytes {
241    fn write(&mut self, buf: &[u8]) -> Result { (*self).write(buf) }
242}
243
244impl<T> TailWriteBytes for &mut T where T: TailWriteBytes {
245    fn write_tail(&mut self, buf: &[u8]) -> Result { (*self).write_tail(buf) }
246}
247
248/// Pushes data to the vector
249#[cfg(feature="std")]
250impl WriteBytes for Vec<u8> {
251    fn write(&mut self, buf: &[u8]) -> Result {
252        self.extend_from_slice(buf);
253        Ok(())
254    }
255}
256
257/// Pushes data to the vector, same as `write()`
258///
259/// This means that `Serializer` can write to `Vec<u8>` buffer directly and grow it as needed,
260/// however in this case lexicographic ordering property will not be preserved.
261#[cfg(feature="std")]
262impl TailWriteBytes for Vec<u8> {
263    fn write_tail(&mut self, buf: &[u8]) -> Result {
264        self.extend_from_slice(buf);
265        Ok(())
266    }
267}
268
269/// Adapter for always writing to buffer head, even for `write_tail()`
270///
271/// Useful e.g. for appending serialized suffix to the buffer
272pub struct WriteToHead<'a, W>(pub &'a mut W) where W: WriteBytes;
273
274impl<'a, W> WriteBytes for WriteToHead<'a, W>
275    where W: TailWriteBytes
276{
277    fn write(&mut self, value: &[u8]) -> Result {
278        self.0.write(value)
279    }
280}
281
282impl<'a, W> TailWriteBytes for WriteToHead<'a, W>
283    where W: TailWriteBytes
284{
285    fn write_tail(&mut self, value: &[u8]) -> Result {
286        self.0.write(value)
287    }
288}
289
290#[test]
291fn test_debuffer() {
292    let mut byte_buf = [0_u8; 7];
293    let mut bib = DeBytesWriter::new(byte_buf.as_mut());
294    bib.write(b"aa").unwrap();
295    bib.write_tail(b"1").unwrap();
296    bib.write(b"bb").unwrap();
297    bib.write_tail(b"2").unwrap();
298    bib.write(b"d").unwrap();
299    bib.is_complete().unwrap();
300    assert_eq!(byte_buf.as_ref(), b"aabbd21");
301    let mut rb = DeBytesReader::new(byte_buf.as_mut());
302    assert_eq!(rb.read(3, |b| Ok(b == b"aab")).unwrap(), true);
303    assert_eq!(rb.read_tail(1, |b| Ok(b == b"1")).unwrap(), true);
304    assert_eq!(rb.read_tail(1, |b| Ok(b == b"2")).unwrap(), true);
305    assert_eq!(rb.read(2, |b| Ok(b == b"bd")).unwrap(), true);
306    rb.is_complete().unwrap();
307}
ordcode/buf.rs

ordcode/
buf.rs
