Struct Cursor 

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

Cursor wraps an in-memory buffer, providing Reader and Writer functionality for types implementing AsRef<[u8]>.

This can be especially useful for wrapping Readers and Writers that are consumed by reading or writing like &[u8] or &mut [MaybeUninit<u8>], making them reusable.

Examples

Using Cursor to write to a MaybeUninit<[u8; N]>.

use wincode::io::{Cursor, Reader, Writer};

fn rand_bytes() -> [u8; 8] {
    random::<u64>().to_le_bytes()
}

let mut data = MaybeUninit::<[u8; 8]>::uninit();

let mut cursor = Cursor::new(&mut data);
let bytes = rand_bytes();
cursor.write(&bytes).unwrap();
assert_eq!(unsafe { data.assume_init() }, bytes);

// We can write over the same buffer multiple times with a new Cursor.
let mut cursor = Cursor::new(&mut data);
let bytes = rand_bytes();
cursor.write(&bytes).unwrap();
assert_eq!(unsafe { data.assume_init() }, bytes);

Using Cursor to write to a Vec’s spare capacity.

use wincode::io::{Cursor, Reader, Writer};

let mut data = Vec::with_capacity(8);

let mut cursor = Cursor::new(&mut data);
let bytes = rand_bytes();
cursor.write(&bytes).unwrap();
assert_eq!(data, bytes);

// We can write over the same buffer multiple times with a new Cursor.
let mut cursor = Cursor::new(&mut data);
let bytes = rand_bytes();
cursor.write(&bytes).unwrap();
assert_eq!(data, bytes);

Implementations

impl<T> Cursor<T>

pub const fn new(inner: T) -> Self

pub const fn new_at(inner: T, pos: usize) -> Self

Creates a new cursor at the given position.

pub const fn set_position(&mut self, pos: usize)

Sets the position of the cursor.

pub fn into_inner(self) -> T

Consumes the cursor and returns the inner value.

pub const fn position(&self) -> usize

Returns the current position of the cursor.

Trait Implementations

impl<'a, T> Reader<'a> for Cursor<T>

where T: AsRef<[u8]>,

const BORROW_KINDS: u8

Borrow capabilities of this reader.

fn copy_into_slice(&mut self, dst: &mut [u8]) -> ReadResult<()>

Attempts to copy and consume exactly dst.len() bytes.

fn copy_into_uninit_slice( &mut self, dst: &mut [MaybeUninit<u8>], ) -> ReadResult<()>

Attempts to copy and consume exactly dst.len() bytes into potentially uninitialized storage.

fn take_array<const N: usize>(&mut self) -> ReadResult<[u8; N]>

Return exactly N bytes as [u8; N] and advance by N.

fn take_scoped(&mut self, len: usize) -> ReadResult<&[u8]>

Return a call-site scoped slice of exactly len bytes and advance by len.

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<impl Reader<'a>>

Advance the parent by n_bytes and return a Reader that can elide bounds checks within that n_bytes window.

fn supports_borrow(&self, kind: BorrowKind) -> bool

Checks if this reader supports the given borrow kind.

fn take_byte(&mut self) -> ReadResult<u8>

Return the next byte and advance by 1.

fn take_borrowed(&mut self, len: usize) -> ReadResult<&'a [u8]>

Return a borrowed slice of exactly len bytes and advance the reader by len.

fn take_borrowed_mut(&mut self, len: usize) -> ReadResult<&'a mut [u8]>

Return a mutably borrowed slice of exactly len bytes and advance the reader by len.

unsafe fn as_trusted_for_seq( &mut self, len: usize, size: usize, ) -> Result<impl Reader<'a>, ReadError>

Construct a trusted window for a sequence of length len and serialized element size size.

fn by_ref(&mut self) -> impl Reader<'a>

Get a mutable reference to the Reader.

unsafe fn copy_into_t<T>(&mut self, dst: &mut MaybeUninit<T>) -> ReadResult<()>

Attempts to copy and consume exactly size_of::<T>() bytes from the Reader into dst.

unsafe fn copy_into_slice_t<T>( &mut self, dst: &mut [MaybeUninit<T>], ) -> ReadResult<()>

Attempts to copy and consume exactly dst.len() * size_of::<T>() bytes from the Reader into dst.

impl Writer for Cursor<&mut [MaybeUninit<u8>]>

fn write(&mut self, src: &[u8]) -> WriteResult<()>

Write exactly src.len() bytes from the given src into the writer.

unsafe fn as_trusted_for(&mut self, n_bytes: usize) -> WriteResult<impl Writer>

Advance the parent by n_bytes and return a Writer that can elide bounds checks within that n_bytes window.

fn by_ref(&mut self) -> impl Writer

Get a mutable reference to the Writer.

fn finish(&mut self) -> WriteResult<()>

Finalize the writer by performing any required cleanup or flushing.

unsafe fn write_t<T: ?Sized>(&mut self, src: &T) -> WriteResult<()>

Write T as bytes into the source.

unsafe fn write_slice_t<T>(&mut self, src: &[T]) -> WriteResult<()>

Write [T] as bytes into the source.

impl Writer for Cursor<&mut [u8]>

fn write(&mut self, src: &[u8]) -> WriteResult<()>

Write exactly src.len() bytes from the given src into the writer.

unsafe fn as_trusted_for(&mut self, n_bytes: usize) -> WriteResult<impl Writer>

Advance the parent by n_bytes and return a Writer that can elide bounds checks within that n_bytes window.

fn by_ref(&mut self) -> impl Writer

Get a mutable reference to the Writer.

fn finish(&mut self) -> WriteResult<()>

Finalize the writer by performing any required cleanup or flushing.

unsafe fn write_t<T: ?Sized>(&mut self, src: &T) -> WriteResult<()>

Write T as bytes into the source.

unsafe fn write_slice_t<T>(&mut self, src: &[T]) -> WriteResult<()>

Write [T] as bytes into the source.

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

fn write(&mut self, src: &[u8]) -> WriteResult<()>

Write exactly src.len() bytes from the given src into the writer.

unsafe fn as_trusted_for(&mut self, n_bytes: usize) -> WriteResult<impl Writer>

Advance the parent by n_bytes and return a Writer that can elide bounds checks within that n_bytes window.

fn by_ref(&mut self) -> impl Writer

Get a mutable reference to the Writer.

fn finish(&mut self) -> WriteResult<()>

Finalize the writer by performing any required cleanup or flushing.

unsafe fn write_t<T: ?Sized>(&mut self, src: &T) -> WriteResult<()>

Write T as bytes into the source.

unsafe fn write_slice_t<T>(&mut self, src: &[T]) -> WriteResult<()>

Write [T] as bytes into the source.

impl Writer for Cursor<&mut Vec<u8>>

Available on crate feature alloc only.

Writer implementation for &mut Vec<u8> that overwrites the underlying vector’s memory. The vector will grow as needed.

Examples

Overwriting an existing vector.

let mut vec = vec![0; 3];
let mut cursor = Cursor::new(&mut vec);
let bytes = [1, 2, 3, 4];
cursor.write(&bytes).unwrap();
assert_eq!(&vec, &[1, 2, 3, 4]);

Growing a vector.

let mut vec = vec![];
let mut cursor = Cursor::new(&mut vec);
let bytes = [1, 2, 3];
cursor.write(&bytes).unwrap();
assert_eq!(&vec, &[1, 2, 3]);

fn write(&mut self, src: &[u8]) -> WriteResult<()>

Write exactly src.len() bytes from the given src into the writer.

unsafe fn as_trusted_for(&mut self, n_bytes: usize) -> WriteResult<impl Writer>

Advance the parent by n_bytes and return a Writer that can elide bounds checks within that n_bytes window.

fn by_ref(&mut self) -> impl Writer

Get a mutable reference to the Writer.

fn finish(&mut self) -> WriteResult<()>

Finalize the writer by performing any required cleanup or flushing.

unsafe fn write_t<T: ?Sized>(&mut self, src: &T) -> WriteResult<()>

Write T as bytes into the source.

unsafe fn write_slice_t<T>(&mut self, src: &[T]) -> WriteResult<()>

Write [T] as bytes into the source.

impl Writer for Cursor<Vec<u8>>

Available on crate feature alloc only.

Writer implementation for Vec<u8> that overwrites the underlying vector’s memory. The vector will grow as needed.

Examples

Overwriting an existing vector.

let mut cursor = Cursor::new(vec![0; 3]);
let bytes = [1, 2, 3, 4];
cursor.write(&bytes).unwrap();
assert_eq!(cursor.into_inner(), &[1, 2, 3, 4]);

Growing a vector.

let mut cursor = Cursor::new(vec![]);
let bytes = [1, 2, 3];
cursor.write(&bytes).unwrap();
assert_eq!(cursor.into_inner(), &[1, 2, 3]);

fn write(&mut self, src: &[u8]) -> WriteResult<()>

Write exactly src.len() bytes from the given src into the writer.

unsafe fn as_trusted_for(&mut self, n_bytes: usize) -> WriteResult<impl Writer>

Advance the parent by n_bytes and return a Writer that can elide bounds checks within that n_bytes window.

fn by_ref(&mut self) -> impl Writer

Get a mutable reference to the Writer.

fn finish(&mut self) -> WriteResult<()>

Finalize the writer by performing any required cleanup or flushing.

unsafe fn write_t<T: ?Sized>(&mut self, src: &T) -> WriteResult<()>

Write T as bytes into the source.

unsafe fn write_slice_t<T>(&mut self, src: &[T]) -> WriteResult<()>

Write [T] as bytes into the source.