mavlink_core/
peek_reader.rs

1//! This module implements a buffered/peekable reader.
2//!
3//! The purpose of the buffered/peekable reader is to allow for backtracking parsers.
4//!
5//! A reader implementing the standard library's [`std::io::BufRead`] trait seems like a good fit, but
6//! it does not allow for peeking a specific number of bytes, so it provides no way to request
7//! more data from the underlying reader without consuming the existing data.
8//!
9//! This API still tries to adhere to the [`std::io::BufRead`]'s trait philosophy.
10//!
11//! The main type `PeekReader`does not implement [`std::io::Read`] itself, as there is no added benefit
12//! in doing so.
13//!
14#[cfg(any(feature = "embedded", feature = "embedded-hal-02"))]
15use crate::embedded::Read;
16
17#[cfg(feature = "std")]
18use std::io::Read;
19
20#[cfg(doc)]
21use std::io::ErrorKind;
22
23use crate::error::MessageReadError;
24
25/// A buffered/peekable reader
26///
27/// This reader wraps a type implementing [`std::io::Read`] and adds buffering via an internal buffer.
28///
29/// It allows the user to `peek` a specified number of bytes (without consuming them),
30/// to `read` bytes (consuming them), or to `consume` them after `peek`ing.
31///
32/// NOTE: This reader is generic over the size of the buffer, defaulting to MAVLink's current largest
33/// possible message size of 280 bytes
34///
35pub struct PeekReader<R, const BUFFER_SIZE: usize = 280> {
36    // Internal buffer
37    buffer: [u8; BUFFER_SIZE],
38    // The position of the next byte to read from the buffer.
39    cursor: usize,
40    // The position of the next byte to read into the buffer.
41    top: usize,
42    // The wrapped reader.
43    reader: R,
44}
45
46impl<R: Read, const BUFFER_SIZE: usize> PeekReader<R, BUFFER_SIZE> {
47    /// Instantiates a new [`PeekReader`], wrapping the provided [`std::io::Read`]er and using the default chunk size
48    pub fn new(reader: R) -> Self {
49        Self {
50            buffer: [0; BUFFER_SIZE],
51            cursor: 0,
52            top: 0,
53            reader,
54        }
55    }
56
57    /// Peeks an exact amount of bytes from the internal buffer
58    ///
59    /// If the internal buffer does not contain enough data, this function will read
60    /// from the underlying [`std::io::Read`]er until it does, an error occurs or no more data can be read (EOF).
61    ///
62    /// If an EOF occurs and the specified amount could not be read, this function will return an [`ErrorKind::UnexpectedEof`].
63    ///
64    /// This function does not consume data from the buffer, so subsequent calls to `peek` or `read` functions
65    /// will still return the peeked data.
66    ///
67    pub fn peek_exact(&mut self, amount: usize) -> Result<&[u8], MessageReadError> {
68        let result = self.fetch(amount, false);
69        result
70    }
71
72    /// Reads a specified amount of bytes from the internal buffer
73    ///
74    /// If the internal buffer does not contain enough data, this function will read
75    /// from the underlying [`std::io::Read`]er until it does, an error occurs or no more data can be read (EOF).
76    ///
77    /// If an EOF occurs and the specified amount could not be read, this function will return an [`ErrorKind::UnexpectedEof`].
78    ///
79    /// This function consumes the data from the buffer, unless an error occurs, in which case no data is consumed.
80    ///
81    pub fn read_exact(&mut self, amount: usize) -> Result<&[u8], MessageReadError> {
82        self.fetch(amount, true)
83    }
84
85    /// Reads a byte from the internal buffer
86    ///
87    /// If the internal buffer does not contain enough data, this function will read
88    /// from the underlying [`std::io::Read`]er until it does, an error occurs or no more data can be read (EOF).
89    ///
90    /// If an EOF occurs and the specified amount could not be read, this function will return an [`ErrorKind::UnexpectedEof`].
91    ///
92    /// This function consumes the data from the buffer, unless an error occurs, in which case no data is consumed.
93    ///
94    pub fn read_u8(&mut self) -> Result<u8, MessageReadError> {
95        let buf = self.read_exact(1)?;
96        Ok(buf[0])
97    }
98
99    /// Consumes a specified amount of bytes from the buffer
100    ///
101    /// If the internal buffer does not contain enough data, this function will consume as much data as is buffered.
102    ///
103    pub fn consume(&mut self, amount: usize) -> usize {
104        let amount = amount.min(self.top - self.cursor);
105        self.cursor += amount;
106        amount
107    }
108
109    /// Returns an immutable reference to the underlying [`std::io::Read`]er
110    ///
111    /// Reading directly from the underlying reader will cause data loss
112    pub fn reader_ref(&self) -> &R {
113        &self.reader
114    }
115
116    /// Returns a mutable reference to the underlying [`std::io::Read`]er
117    ///
118    /// Reading directly from the underlying reader will cause data loss
119    pub fn reader_mut(&mut self) -> &mut R {
120        &mut self.reader
121    }
122
123    /// Internal function to fetch data from the internal buffer and/or reader
124    fn fetch(&mut self, amount: usize, consume: bool) -> Result<&[u8], MessageReadError> {
125        loop {
126            let buffered = self.top - self.cursor;
127
128            if buffered >= amount {
129                break;
130            }
131
132            // the caller requested more bytes than we have buffered, fetch them from the reader
133            let bytes_to_read = amount - buffered;
134            assert!(bytes_to_read < BUFFER_SIZE);
135
136            // Check if we need to compact the buffer first
137            if self.top + bytes_to_read > BUFFER_SIZE {
138                // Move unread data to the beginning of the buffer
139                self.buffer.copy_within(self.cursor..self.top, 0);
140                self.top = buffered;
141                self.cursor = 0;
142            }
143
144            // Now we can safely read directly into the buffer
145            let end_pos = self.top + bytes_to_read;
146
147            // read needed bytes from reader
148            let bytes_read = self.reader.read(&mut self.buffer[self.top..end_pos])?;
149
150            if bytes_read == 0 {
151                return Err(MessageReadError::eof());
152            }
153
154            self.top += bytes_read;
155        }
156
157        let result = &self.buffer[self.cursor..self.cursor + amount];
158        if consume {
159            self.cursor += amount;
160        }
161        Ok(result)
162    }
163}
164
165#[cfg(test)]
166mod tests {
167    use super::*;
168
169    use std::io::Cursor;
170    use std::io::{self};
171
172    #[test]
173    fn test_read_and_peek() {
174        let data = b"Hello, World!";
175        let cursor = Cursor::new(data);
176        let mut reader = PeekReader::<_, 280>::new(cursor);
177
178        let peeked = reader.peek_exact(5).unwrap();
179        assert_eq!(peeked, b"Hello");
180
181        let read = reader.read_exact(5).unwrap();
182        assert_eq!(read, b"Hello");
183
184        // Make sure `PeekReader::read_exact` consumed the first 5 bytes.
185        let read = reader.read_exact(8).unwrap();
186        assert_eq!(read, b", World!");
187
188        match reader.read_u8().unwrap_err() {
189            MessageReadError::Io(io_err) => {
190                assert_eq!(io_err.kind(), io::ErrorKind::UnexpectedEof);
191            }
192            _ => panic!("Expected Io error with UnexpectedEof"),
193        }
194    }
195}