pub struct Cursor<T> { /* private fields */ }
Expand description
A cursor which wraps an in-memory buffer and provides positioned reading
Cursor
is a simple wrapper that allows reading from various in-memory
data types (like &[u8]
) with a tracked position. This is useful for
parsing protocols where you need to read sequentially through a buffer.
Unlike std::io::Cursor
, this implementation is designed for no_std
environments and focuses on reading operations only.
§Examples
use mqtt_protocol_core::mqtt::common::Cursor;
let data = &b"hello world"[..];
let mut cursor = Cursor::new(data);
// Read individual bytes
assert_eq!(cursor.read_u8(), Some(b'h'));
assert_eq!(cursor.position(), 1);
// Read multiple bytes at once
let chunk = cursor.read_bytes(5).unwrap();
assert_eq!(chunk, b"ello ");
assert_eq!(cursor.position(), 6);
Implementations§
Source§impl<T> Cursor<T>
impl<T> Cursor<T>
Sourcepub fn new(inner: T) -> Self
pub fn new(inner: T) -> Self
Creates a new cursor with the provided data
The cursor starts at position 0.
§Examples
use mqtt_protocol_core::mqtt::common::Cursor;
let cursor = Cursor::new(&b"hello"[..]);
assert_eq!(cursor.position(), 0);
Sourcepub fn set_position(&mut self, pos: u64)
pub fn set_position(&mut self, pos: u64)
Source§impl Cursor<&[u8]>
impl Cursor<&[u8]>
Sourcepub fn remaining_slice(&self) -> &[u8] ⓘ
pub fn remaining_slice(&self) -> &[u8] ⓘ
Returns a slice of the remaining unread data
This returns all data from the current position to the end of the buffer. If the position is beyond the buffer length, returns an empty slice.
§Returns
&[u8]
- Slice containing all unread data from current position to end
§Examples
use mqtt_protocol_core::mqtt::common::Cursor;
let mut cursor = Cursor::new(&b"hello"[..]);
cursor.set_position(2);
assert_eq!(cursor.remaining_slice(), b"llo");
Sourcepub fn read_bytes(&mut self, count: usize) -> Option<&[u8]>
pub fn read_bytes(&mut self, count: usize) -> Option<&[u8]>
Reads exactly count
bytes from the cursor
Advances the cursor position by count
bytes and returns a slice
to the read data. Returns None
if there are not enough bytes
remaining to satisfy the request.
§Parameters
count
- Number of bytes to read
§Returns
Some(&[u8])
- Slice containing exactlycount
bytesNone
- Not enough data available to readcount
bytes
§Examples
use mqtt_protocol_core::mqtt::common::Cursor;
let mut cursor = Cursor::new(&b"hello world"[..]);
assert_eq!(cursor.read_bytes(5), Some(&b"hello"[..]));
assert_eq!(cursor.position(), 5);
assert_eq!(cursor.read_bytes(20), None); // Not enough data
Sourcepub fn read_u8(&mut self) -> Option<u8>
pub fn read_u8(&mut self) -> Option<u8>
Reads a single byte from the cursor
Advances the cursor position by 1 byte and returns the byte value.
Returns None
if there are no more bytes to read.
§Returns
Some(u8)
- The next byte from the cursorNone
- No more bytes available to read
§Examples
use mqtt_protocol_core::mqtt::common::Cursor;
let mut cursor = Cursor::new(&b"hi"[..]);
assert_eq!(cursor.read_u8(), Some(b'h'));
assert_eq!(cursor.read_u8(), Some(b'i'));
assert_eq!(cursor.read_u8(), None); // End of data
Source§impl<T: AsRef<[u8]>> Cursor<T>
impl<T: AsRef<[u8]>> Cursor<T>
Sourcepub fn read(&mut self, buf: &mut [u8]) -> Result<usize, CursorError>
pub fn read(&mut self, buf: &mut [u8]) -> Result<usize, CursorError>
Pulls some bytes from this cursor into the specified buffer
This method is compatible with std::io::Read::read()
. It reads at most
buf.len()
bytes from the cursor into the provided buffer, advancing
the cursor position accordingly.
§Parameters
buf
- Buffer to read data into
§Returns
Ok(n)
- Number of bytes read (0 tobuf.len()
)
This method currently never returns an error, but returns a Result
for compatibility with std::io::Read::read()
.
§Examples
use mqtt_protocol_core::mqtt::common::Cursor;
let mut cursor = Cursor::new(&b"hello world"[..]);
let mut buf = [0u8; 5];
let n = cursor.read(&mut buf).unwrap();
assert_eq!(n, 5);
assert_eq!(&buf, b"hello");
assert_eq!(cursor.position(), 5);
Sourcepub fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), CursorError>
pub fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), CursorError>
Reads the exact number of bytes required to fill buf
This method is compatible with std::io::Read::read_exact()
. It reads
exactly buf.len()
bytes from the cursor into the buffer, or returns
an error if not enough data is available.
§Parameters
buf
- Buffer to read data into (must be completely filled)
§Returns
Ok(())
- Successfully read exactlybuf.len()
bytesErr(CursorError::UnexpectedEof)
- Not enough data available
§Examples
use mqtt_protocol_core::mqtt::common::{Cursor, CursorError};
let mut cursor = Cursor::new(&b"hello"[..]);
let mut buf = [0u8; 3];
cursor.read_exact(&mut buf).unwrap();
assert_eq!(&buf, b"hel");
// Trying to read more than available
let mut buf2 = [0u8; 10];
assert_eq!(cursor.read_exact(&mut buf2), Err(CursorError::UnexpectedEof));