Struct ic_cdk::api::stable::StableIO

pub struct StableIO<M: StableMemory = CanisterStableMemory, A: AddressSize = u32> { /* private fields */ }

Performs generic IO (read, write, and seek) on stable memory.

Warning: When using write functionality, this will overwrite any existing data in stable memory as it writes, so ensure you set the offset value accordingly if you wish to preserve existing data.

Will attempt to grow the memory as it writes, and keep offsets and total capacity.

Implementations

impl<M: StableMemory_<u32> + StableMemory> StableIO<M, u32>

pub fn with_memory(memory: M, offset: u32) -> Self

Creates a new StableIO which writes to the selected memory

pub fn offset(&self) -> u32

Returns the offset of the writer

pub fn grow(&mut self, new_pages: u32) -> Result<(), StableMemoryError>

Attempts to grow the memory by adding new pages.

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

Writes a byte slice to the buffer.

The only condition where this will error out is if it cannot grow the memory.

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

Reads data from the stable memory location specified by an offset.

Note: The stable memory size is cached on creation of the StableReader. Therefore, in following scenario, it will get an OutOfBounds error:

1. Create a StableReader
2. Write some data to the stable memory which causes it grow
3. call read() to read the newly written bytes

impl<M: StableMemory_<u64> + StableMemory> StableIO<M, u64>

pub fn with_memory(memory: M, offset: u64) -> Self

Creates a new StableIO which writes to the selected memory

pub fn offset(&self) -> u64

Returns the offset of the writer

pub fn grow(&mut self, new_pages: u64) -> Result<(), StableMemoryError>

Attempts to grow the memory by adding new pages.

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

Writes a byte slice to the buffer.

The only condition where this will error out is if it cannot grow the memory.

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

Reads data from the stable memory location specified by an offset.

Note: The stable memory size is cached on creation of the StableReader. Therefore, in following scenario, it will get an OutOfBounds error:

1. Create a StableReader
2. Write some data to the stable memory which causes it grow
3. call read() to read the newly written bytes

Trait Implementations

impl<M: Debug + StableMemory, A: Debug + AddressSize> Debug for StableIO<M, A>

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

Formats the value using the given formatter.

impl Default for StableIO

fn default() -> Self

Returns the “default value” for a type.

impl<M: StableMemory> From<StableIO<M>> for StableReader<M>

fn from(io: StableIO<M>) -> Self

Converts to this type from the input type.

impl<M: StableMemory> From<StableIO<M>> for StableWriter<M>

fn from(io: StableIO<M>) -> Self

Converts to this type from the input type.

impl<M: StableMemory_<u32> + StableMemory> Read for StableIO<M, u32>

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

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

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

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

Read the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<M: StableMemory_<u64> + StableMemory> Read for StableIO<M, u64>

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

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

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

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

Read the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<M: StableMemory_<u32> + StableMemory> Seek for StableIO<M, u32>

fn seek(&mut self, offset: SeekFrom) -> Result<u64>

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

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

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

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

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

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

🔬This is a nightly-only experimental API. (seek_seek_relative)

Seeks relative to the current position.

impl<M: StableMemory_<u64> + StableMemory> Seek for StableIO<M, u64>

fn seek(&mut self, offset: SeekFrom) -> Result<u64>

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

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

Rewind to the beginning of a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬This is a nightly-only experimental API. (seek_stream_len)

Returns the length of this stream (in bytes).

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

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

fn seek_relative(&mut self, offset: i64) -> Result<(), Error>

🔬This is a nightly-only experimental API. (seek_seek_relative)

Seeks relative to the current position.

impl<M: StableMemory_<u32> + StableMemory> Write for StableIO<M, u32>

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

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

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

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

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

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

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

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

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<M: StableMemory_<u64> + StableMemory> Write for StableIO<M, u64>

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

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

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

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

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

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

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

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

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.