Struct Cursor 

pub struct Cursor<T> { /* private fields */ }

A Cursor wraps an in-memory buffer and provides embedded-io trait implementations.

This is the embedded-io equivalent of std::io::Cursor, designed for no_std environments. It implements the embedded-io traits (Read, Write, BufRead, and Seek) for various buffer types.

Cursors are used with in-memory buffers (anything implementing [AsRef<[u8]>]) to allow them to implement embedded-io traits, making these buffers usable anywhere you need an embedded-io reader, writer, or seeker.

Supported buffer types include &[u8], [u8; N], &mut [u8], and with the alloc feature: Vec<u8> and Box<[u8]>.

Examples

Examples of using the Cursor for writing and reading can be found in the comprehensive test suite in the tests/ directory.

Reading from a buffer using embedded-io traits:

use embedded_io::Read;
use embedded_io_cursor::Cursor;

let mut cursor = Cursor::new(&b"hello world"[..]);
let mut buf = [0u8; 5];
cursor.read_exact(&mut buf).unwrap();
assert_eq!(&buf, b"hello");

Implementations

impl<T> Cursor<T>

pub const fn new(inner: T) -> Cursor<T>

Creates a new cursor wrapping the provided underlying in-memory buffer.

Cursor initial position is 0 even if underlying buffer (e.g., Vec) is not empty. So writing to cursor starts with overwriting Vec content, not with appending to it.

Examples

use embedded_io_cursor::Cursor;

let cursor = Cursor::new(Vec::<u8>::new());

pub fn into_inner(self) -> T

Consumes this cursor, returning the underlying value.

Examples

use embedded_io_cursor::Cursor;

let buff = Cursor::new(Vec::<u8>::new());
let vec = buff.into_inner();

pub const fn get_ref(&self) -> &T

Gets a reference to the underlying value in this cursor.

Examples

use embedded_io_cursor::Cursor;

let buff = Cursor::new(Vec::<u8>::new());
let reference = buff.get_ref();

pub fn get_mut(&mut self) -> &mut T

Gets a mutable reference to the underlying value in this cursor.

Care should be taken to avoid modifying the internal I/O state of the underlying value as it may corrupt this cursor’s position.

Examples

use embedded_io_cursor::Cursor;

let mut buff = Cursor::new(Vec::<u8>::new());
let reference = buff.get_mut();

pub const fn position(&self) -> u64

Returns the current position of this cursor.

Examples

use embedded_io::{Seek, SeekFrom};
use embedded_io_cursor::Cursor;

let mut buff = Cursor::new(&[1u8, 2, 3, 4, 5][..]);
assert_eq!(buff.position(), 0);

buff.seek(SeekFrom::Current(2)).unwrap();
assert_eq!(buff.position(), 2);

buff.seek(SeekFrom::Current(-1)).unwrap();
assert_eq!(buff.position(), 1);

pub fn set_position(&mut self, pos: u64)

Sets the position of this cursor.

Examples

use embedded_io_cursor::Cursor;

let mut buff = Cursor::new(&[1u8, 2, 3, 4, 5][..]);
assert_eq!(buff.position(), 0);

buff.set_position(2);
assert_eq!(buff.position(), 2);

buff.set_position(4);
assert_eq!(buff.position(), 4);

impl<T> Cursor<T>

where T: AsRef<[u8]>,

pub fn remaining_slice(&self) -> &[u8]

Returns the remaining slice from the current position.

This method returns the portion of the underlying buffer that can still be read from the current cursor position.

Examples

use embedded_io_cursor::Cursor;

let mut cursor = Cursor::new(&[1u8, 2, 3, 4, 5][..]);
assert_eq!(cursor.remaining_slice(), &[1, 2, 3, 4, 5]);

cursor.set_position(2);
assert_eq!(cursor.remaining_slice(), &[3, 4, 5]);

cursor.set_position(10);
assert_eq!(cursor.remaining_slice(), &[]);

pub fn is_empty(&self) -> bool

Returns true if there are no more bytes to read from the cursor.

This is equivalent to checking if remaining_slice().is_empty().

Examples

use embedded_io_cursor::Cursor;

let mut cursor = Cursor::new(&[1u8, 2, 3][..]);
assert!(!cursor.is_empty());

cursor.set_position(3);
assert!(cursor.is_empty());

cursor.set_position(10);
assert!(cursor.is_empty());

Trait Implementations

impl<T> BufRead for Cursor<T>

where T: AsRef<[u8]>,

fn fill_buf(&mut self) -> Result<&[u8], Self::Error>

Return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(&mut self, amt: usize)

Tell this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to fill_buf.

impl<T> Clone for Cursor<T>

where T: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, other: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Cursor<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Cursor<T>

fn default() -> Cursor<T>

Returns the “default value” for a type.

impl<T> ErrorType for Cursor<T>

type Error = ErrorKind

Error type of all the IO operations on this type.

impl<T: PartialEq> PartialEq for Cursor<T>

fn eq(&self, other: &Cursor<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Read for Cursor<T>

where T: AsRef<[u8]>,

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>

Read some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_exact( &mut self, buf: &mut [u8], ) -> Result<(), ReadExactError<Self::Error>>

Read the exact number of bytes required to fill buf.

impl<T> Seek for Cursor<T>

where T: AsRef<[u8]>,

fn seek(&mut self, style: SeekFrom) -> Result<u64, Self::Error>

Seek to an offset, in bytes, in a stream.

fn rewind(&mut self) -> Result<(), Self::Error>

Rewind to the beginning of a stream.

fn stream_position(&mut self) -> Result<u64, Self::Error>

Returns the current seek position from the start of the stream.

impl Write for Cursor<&mut [u8]>

fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, blocking until all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error>

Write an entire buffer into this writer.

fn write_fmt( &mut self, fmt: Arguments<'_>, ) -> Result<(), WriteFmtError<Self::Error>>

Write a formatted string into this writer, returning any error encountered.

impl<const N: usize> Write for Cursor<&mut [u8; N]>

fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, blocking until all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error>

Write an entire buffer into this writer.

fn write_fmt( &mut self, fmt: Arguments<'_>, ) -> Result<(), WriteFmtError<Self::Error>>

Write a formatted string into this writer, returning any error encountered.

impl<const N: usize> Write for Cursor<[u8; N]>

fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, blocking until all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error>

Write an entire buffer into this writer.

fn write_fmt( &mut self, fmt: Arguments<'_>, ) -> Result<(), WriteFmtError<Self::Error>>

Write a formatted string into this writer, returning any error encountered.

impl<T: Eq> Eq for Cursor<T>

impl<T> StructuralPartialEq for Cursor<T>