Crate embedded_io_cursor

Crate embedded_io_cursor 

Source
Expand description

§embedded-io-cursor

Crates.io docs.rs CI

A no_std-compatible Cursor implementation designed for use with embedded-io.

This crate provides a Cursor type that wraps an in-memory buffer and provides Read, Write, Seek, and BufRead implementations using the embedded-io traits. Unlike the standard library’s Cursor, this implementation works in no_std environments while maintaining API compatibility where possible.

§Usage

Add this to your Cargo.toml:

[dependencies]
embedded-io-cursor = "0.1.0"

§Basic Usage

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

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

// Writing to a mutable buffer
let mut buffer = [0u8; 10];
{
    use embedded_io::Write;
    let mut cursor = Cursor::new(&mut buffer[..]);
    let data = b"test";
    let mut written = 0;
    while written < data.len() {
        written += cursor.write(&data[written..]).unwrap();
    }
}
assert_eq!(&buffer[..4], b"test");

§With alloc feature (requires alloc feature to be enabled)

use embedded_io::Write;
use embedded_io_cursor::Cursor;
extern crate alloc;
use alloc::vec::Vec;

let mut vec = Vec::new();
let mut cursor = Cursor::new(&mut vec);
let data = b"hello world";
let mut written = 0;
while written < data.len() {
    written += cursor.write(&data[written..]).unwrap();
}
assert_eq!(vec, b"hello world");

§Features

  • default: No additional features enabled
  • std: Enable standard library support (implies alloc)
  • alloc: Enable support for Vec<u8> and Box<[u8]>
  • defmt: Enable defmt formatting support

§Differences from std::io::Cursor

This implementation maintains API compatibility with std::io::Cursor where possible, but has some key differences:

  1. Uses embedded-io traits: Instead of std::io traits, this uses the embedded-io equivalents
  2. Full BufRead support: Implements embedded-io::BufRead with fill_buf() and consume()
  3. Limited buffer types in no_std: Without alloc, only basic slice types are supported
  4. Error type: Uses embedded_io::ErrorKind instead of std::io::Error

§Testing

Run tests with:

cargo test                           # All tests (includes doctests)
cargo test --no-default-features     # no_std tests only
cargo test --features alloc          # With alloc support
cargo test --features std            # With std support
cargo test --lib --tests             # Unit and integration tests only

§License

Licensed under either of

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. A no_std-compatible Cursor implementation designed for use with embedded-io.

This crate provides a Cursor type that wraps an in-memory buffer and implements the embedded-io traits (Read, Write, BufRead, and Seek). It serves as the embedded-io ecosystem’s equivalent to std::io::Cursor, optimized for embedded and no_std environments while maintaining API compatibility where possible.

Structs§

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