pub struct StableIO<M: StableMemory = CanisterStableMemory, A: AddressSize = u32> { /* private fields */ }
Expand description
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
sourceimpl<M: StableMemory_<u32> + StableMemory> StableIO<M, u32>
impl<M: StableMemory_<u32> + StableMemory> StableIO<M, u32>
sourcepub fn with_memory(memory: M, offset: u32) -> Self
pub fn with_memory(memory: M, offset: u32) -> Self
Creates a new StableIO
which writes to the selected memory
sourcepub fn grow(&mut self, new_pages: u32) -> Result<(), StableMemoryError>
pub fn grow(&mut self, new_pages: u32) -> Result<(), StableMemoryError>
Attempts to grow the memory by adding new pages.
sourcepub fn write(&mut self, buf: &[u8]) -> Result<usize, StableMemoryError>
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.
sourcepub fn read(&mut self, buf: &mut [u8]) -> Result<usize, StableMemoryError>
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:
- Create a StableReader
- Write some data to the stable memory which causes it grow
- call
read()
to read the newly written bytes
sourceimpl<M: StableMemory_<u64> + StableMemory> StableIO<M, u64>
impl<M: StableMemory_<u64> + StableMemory> StableIO<M, u64>
sourcepub fn with_memory(memory: M, offset: u64) -> Self
pub fn with_memory(memory: M, offset: u64) -> Self
Creates a new StableIO
which writes to the selected memory
sourcepub fn grow(&mut self, new_pages: u64) -> Result<(), StableMemoryError>
pub fn grow(&mut self, new_pages: u64) -> Result<(), StableMemoryError>
Attempts to grow the memory by adding new pages.
sourcepub fn write(&mut self, buf: &[u8]) -> Result<usize, StableMemoryError>
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.
sourcepub fn read(&mut self, buf: &mut [u8]) -> Result<usize, StableMemoryError>
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:
- Create a StableReader
- Write some data to the stable memory which causes it grow
- call
read()
to read the newly written bytes
Trait Implementations
sourceimpl<M: StableMemory> From<StableIO<M, u32>> for StableReader<M>
impl<M: StableMemory> From<StableIO<M, u32>> for StableReader<M>
sourceimpl<M: StableMemory> From<StableIO<M, u32>> for StableWriter<M>
impl<M: StableMemory> From<StableIO<M, u32>> for StableWriter<M>
sourceimpl<M: StableMemory_<u32> + StableMemory> Read for StableIO<M, u32>
impl<M: StableMemory_<u32> + StableMemory> Read for StableIO<M, u32>
sourcefn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
1.36.0 · sourcefn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
read
, except that it reads into a slice of buffers. Read moresourcefn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)1.0.0 · sourcefn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
buf
. Read more1.0.0 · sourcefn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · sourcefn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moresourcefn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)sourcefn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · sourcefn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Read
. Read moresourceimpl<M: StableMemory_<u64> + StableMemory> Read for StableIO<M, u64>
impl<M: StableMemory_<u64> + StableMemory> Read for StableIO<M, u64>
sourcefn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>
1.36.0 · sourcefn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
read
, except that it reads into a slice of buffers. Read moresourcefn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)1.0.0 · sourcefn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
buf
. Read more1.0.0 · sourcefn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
buf
. Read more1.6.0 · sourcefn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
buf
. Read moresourcefn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)sourcefn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>
read_buf
)cursor
. Read more1.0.0 · sourcefn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Read
. Read moresourceimpl<M: StableMemory_<u32> + StableMemory> Seek for StableIO<M, u32>
impl<M: StableMemory_<u32> + StableMemory> Seek for StableIO<M, u32>
sourcefn seek(&mut self, offset: SeekFrom) -> Result<u64>
fn seek(&mut self, offset: SeekFrom) -> Result<u64>
1.55.0 · sourcefn rewind(&mut self) -> Result<(), Error>
fn rewind(&mut self) -> Result<(), Error>
sourceimpl<M: StableMemory_<u64> + StableMemory> Seek for StableIO<M, u64>
impl<M: StableMemory_<u64> + StableMemory> Seek for StableIO<M, u64>
sourcefn seek(&mut self, offset: SeekFrom) -> Result<u64>
fn seek(&mut self, offset: SeekFrom) -> Result<u64>
1.55.0 · sourcefn rewind(&mut self) -> Result<(), Error>
fn rewind(&mut self) -> Result<(), Error>
sourceimpl<M: StableMemory_<u32> + StableMemory> Write for StableIO<M, u32>
impl<M: StableMemory_<u32> + StableMemory> Write for StableIO<M, u32>
sourcefn write(&mut self, buf: &[u8]) -> Result<usize, Error>
fn write(&mut self, buf: &[u8]) -> Result<usize, Error>
sourcefn flush(&mut self) -> Result<(), Error>
fn flush(&mut self) -> Result<(), Error>
sourcefn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · sourcefn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
sourcefn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)sourceimpl<M: StableMemory_<u64> + StableMemory> Write for StableIO<M, u64>
impl<M: StableMemory_<u64> + StableMemory> Write for StableIO<M, u64>
sourcefn write(&mut self, buf: &[u8]) -> Result<usize, Error>
fn write(&mut self, buf: &[u8]) -> Result<usize, Error>
sourcefn flush(&mut self) -> Result<(), Error>
fn flush(&mut self) -> Result<(), Error>
sourcefn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)1.0.0 · sourcefn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
sourcefn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)Auto Trait Implementations
impl<M, A> RefUnwindSafe for StableIO<M, A>where
A: RefUnwindSafe,
M: RefUnwindSafe,
impl<M, A> Send for StableIO<M, A>where
A: Send,
M: Send,
impl<M, A> Sync for StableIO<M, A>where
A: Sync,
M: Sync,
impl<M, A> Unpin for StableIO<M, A>where
A: Unpin,
M: Unpin,
impl<M, A> UnwindSafe for StableIO<M, A>where
A: UnwindSafe,
M: UnwindSafe,
Blanket Implementations
impl<R> BinReaderExt for Rwhere
R: Read + Seek,
impl<R> BinReaderExt for Rwhere
R: Read + Seek,
fn read_type<T>(&mut self, endian: Endian) -> Result<T, Error>where
T: BinRead,
fn read_type<T>(&mut self, endian: Endian) -> Result<T, Error>where
T: BinRead,
fn read_be<T>(&mut self) -> Result<T, Error>where
T: BinRead,
fn read_be<T>(&mut self) -> Result<T, Error>where
T: BinRead,
fn read_le<T>(&mut self) -> Result<T, Error>where
T: BinRead,
fn read_le<T>(&mut self) -> Result<T, Error>where
T: BinRead,
fn read_ne<T>(&mut self) -> Result<T, Error>where
T: BinRead,
fn read_ne<T>(&mut self) -> Result<T, Error>where
T: BinRead,
fn read_type_args<T>(
&mut self,
endian: Endian,
args: <T as BinRead>::Args
) -> Result<T, Error>where
T: BinRead,
fn read_type_args<T>(
&mut self,
endian: Endian,
args: <T as BinRead>::Args
) -> Result<T, Error>where
T: BinRead,
T
from the reader with the given byte order and arguments.fn read_be_args<T>(&mut self, args: <T as BinRead>::Args) -> Result<T, Error>where
T: BinRead,
fn read_be_args<T>(&mut self, args: <T as BinRead>::Args) -> Result<T, Error>where
T: BinRead,
T
from the reader, assuming big-endian byte order, using the
given arguments. Read morefn read_le_args<T>(&mut self, args: <T as BinRead>::Args) -> Result<T, Error>where
T: BinRead,
fn read_le_args<T>(&mut self, args: <T as BinRead>::Args) -> Result<T, Error>where
T: BinRead,
T
from the reader, assuming little-endian byte order, using the
given arguments. Read morefn read_ne_args<T>(&mut self, args: <T as BinRead>::Args) -> Result<T, Error>where
T: BinRead,
fn read_ne_args<T>(&mut self, args: <T as BinRead>::Args) -> Result<T, Error>where
T: BinRead,
T
from the reader, assuming native-endian byte order, using the
given arguments. Read moresourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<R> ReadBytesExt for Rwhere
R: Read + ?Sized,
impl<R> ReadBytesExt for Rwhere
R: Read + ?Sized,
fn read_u8(&mut self) -> Result<u8, Error>
fn read_u8(&mut self) -> Result<u8, Error>
fn read_i8(&mut self) -> Result<i8, Error>
fn read_i8(&mut self) -> Result<i8, Error>
fn read_u16<T>(&mut self) -> Result<u16, Error>where
T: ByteOrder,
fn read_u16<T>(&mut self) -> Result<u16, Error>where
T: ByteOrder,
fn read_i16<T>(&mut self) -> Result<i16, Error>where
T: ByteOrder,
fn read_i16<T>(&mut self) -> Result<i16, Error>where
T: ByteOrder,
fn read_u24<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
fn read_u24<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
fn read_i24<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
fn read_i24<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
fn read_u32<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
fn read_u32<T>(&mut self) -> Result<u32, Error>where
T: ByteOrder,
fn read_i32<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
fn read_i32<T>(&mut self) -> Result<i32, Error>where
T: ByteOrder,
fn read_u48<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
fn read_u48<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
fn read_i48<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
fn read_i48<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
fn read_u64<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
fn read_u64<T>(&mut self) -> Result<u64, Error>where
T: ByteOrder,
fn read_i64<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
fn read_i64<T>(&mut self) -> Result<i64, Error>where
T: ByteOrder,
fn read_u128<T>(&mut self) -> Result<u128, Error>where
T: ByteOrder,
fn read_u128<T>(&mut self) -> Result<u128, Error>where
T: ByteOrder,
fn read_i128<T>(&mut self) -> Result<i128, Error>where
T: ByteOrder,
fn read_i128<T>(&mut self) -> Result<i128, Error>where
T: ByteOrder,
fn read_uint<T>(&mut self, nbytes: usize) -> Result<u64, Error>where
T: ByteOrder,
fn read_uint<T>(&mut self, nbytes: usize) -> Result<u64, Error>where
T: ByteOrder,
fn read_int<T>(&mut self, nbytes: usize) -> Result<i64, Error>where
T: ByteOrder,
fn read_int<T>(&mut self, nbytes: usize) -> Result<i64, Error>where
T: ByteOrder,
fn read_uint128<T>(&mut self, nbytes: usize) -> Result<u128, Error>where
T: ByteOrder,
fn read_uint128<T>(&mut self, nbytes: usize) -> Result<u128, Error>where
T: ByteOrder,
fn read_int128<T>(&mut self, nbytes: usize) -> Result<i128, Error>where
T: ByteOrder,
fn read_int128<T>(&mut self, nbytes: usize) -> Result<i128, Error>where
T: ByteOrder,
fn read_f32<T>(&mut self) -> Result<f32, Error>where
T: ByteOrder,
fn read_f32<T>(&mut self) -> Result<f32, Error>where
T: ByteOrder,
fn read_f64<T>(&mut self) -> Result<f64, Error>where
T: ByteOrder,
fn read_f64<T>(&mut self) -> Result<f64, Error>where
T: ByteOrder,
fn read_u16_into<T>(&mut self, dst: &mut [u16]) -> Result<(), Error>where
T: ByteOrder,
fn read_u16_into<T>(&mut self, dst: &mut [u16]) -> Result<(), Error>where
T: ByteOrder,
fn read_u32_into<T>(&mut self, dst: &mut [u32]) -> Result<(), Error>where
T: ByteOrder,
fn read_u32_into<T>(&mut self, dst: &mut [u32]) -> Result<(), Error>where
T: ByteOrder,
fn read_u64_into<T>(&mut self, dst: &mut [u64]) -> Result<(), Error>where
T: ByteOrder,
fn read_u64_into<T>(&mut self, dst: &mut [u64]) -> Result<(), Error>where
T: ByteOrder,
fn read_u128_into<T>(&mut self, dst: &mut [u128]) -> Result<(), Error>where
T: ByteOrder,
fn read_u128_into<T>(&mut self, dst: &mut [u128]) -> Result<(), Error>where
T: ByteOrder,
fn read_i8_into(&mut self, dst: &mut [i8]) -> Result<(), Error>
fn read_i8_into(&mut self, dst: &mut [i8]) -> Result<(), Error>
fn read_i16_into<T>(&mut self, dst: &mut [i16]) -> Result<(), Error>where
T: ByteOrder,
fn read_i16_into<T>(&mut self, dst: &mut [i16]) -> Result<(), Error>where
T: ByteOrder,
fn read_i32_into<T>(&mut self, dst: &mut [i32]) -> Result<(), Error>where
T: ByteOrder,
fn read_i32_into<T>(&mut self, dst: &mut [i32]) -> Result<(), Error>where
T: ByteOrder,
fn read_i64_into<T>(&mut self, dst: &mut [i64]) -> Result<(), Error>where
T: ByteOrder,
fn read_i64_into<T>(&mut self, dst: &mut [i64]) -> Result<(), Error>where
T: ByteOrder,
fn read_i128_into<T>(&mut self, dst: &mut [i128]) -> Result<(), Error>where
T: ByteOrder,
fn read_i128_into<T>(&mut self, dst: &mut [i128]) -> Result<(), Error>where
T: ByteOrder,
fn read_f32_into<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
fn read_f32_into<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
fn read_f32_into_unchecked<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
fn read_f32_into_unchecked<T>(&mut self, dst: &mut [f32]) -> Result<(), Error>where
T: ByteOrder,
read_f32_into
instead