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]>,

type Trusted<'b> = TrustedSliceReader<'a, 'b> where Self: 'b

A variant of the Reader that can elide bounds checking within a given window.

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

Return up to n_bytes from the internal buffer without advancing. Implementations may read more data internally to satisfy future requests. Returns fewer than n_bytes at EOF.

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

Return exactly n_bytes without advancing.

unsafe fn consume_unchecked(&mut self, amt: usize)

Advance by exactly amt bytes without bounds checks.

fn consume(&mut self, amt: usize) -> ReadResult<()>

Advance the reader exactly amt bytes, returning an error if the source does not have enough bytes.

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<Self::Trusted<'_>>

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

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

Return exactly N bytes as &[u8; N] without advancing.

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

Zero-copy: return a borrowed slice of exactly len bytes and advance by len.

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

Zero-copy: return a borrowed mutable slice of exactly len bytes and advance by len.

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

Return a reference to the next byte without advancing.

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

Get a mutable reference to the Reader.

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

Copy and consume exactly dst.len() bytes from the Reader into dst.

fn copy_into_array<const N: usize>( &mut self, dst: &mut MaybeUninit<[u8; N]>, ) -> ReadResult<()>

Copy and consume exactly N bytes from the Reader into dst.

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

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<()>

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

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

type Trusted<'b> = TrustedSliceWriter<'b> where Self: 'b

A variant of the Writer that can elide bounds checking within a given window.

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<Self::Trusted<'_>>

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]>>

type Trusted<'b> = TrustedSliceWriter<'b> where Self: 'b

A variant of the Writer that can elide bounds checking within a given window.

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<Self::Trusted<'_>>

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]);

type Trusted<'b> = TrustedVecWriter<'b> where Self: 'b

A variant of the Writer that can elide bounds checking within a given window.

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

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

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

Finalize the writer by performing any required cleanup or flushing.

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> WriteResult<Self::Trusted<'_>>

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.

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]);

type Trusted<'b> = TrustedVecWriter<'b> where Self: 'b

A variant of the Writer that can elide bounds checking within a given window.

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

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

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

Finalize the writer by performing any required cleanup or flushing.

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> WriteResult<Self::Trusted<'_>>

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.

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.