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}