Struct ic_stable_structures::log::Log

pub struct Log<T: Storable, INDEX: Memory, DATA: Memory> { /* private fields */ }

Append-only list of variable-size entries stored in stable memory.

Implementations

impl<T: Storable, INDEX: Memory, DATA: Memory> Log<T, INDEX, DATA>

pub fn new(index_memory: INDEX, data_memory: DATA) -> Self

Creates a new empty growable stable log backed by the memory trait objects, overwriting the previous contents.

pub fn init(index_memory: INDEX, data_memory: DATA) -> Result<Self, InitError>

Initializes the log based on the contents of the provided memory trait objects. If the memory trait objects already contain a stable log, this function recovers it from the stable memory. Otherwise, this function allocates a new empty log.

pub fn into_memories(self) -> (INDEX, DATA)

Returns the underlying memory trait objects of the log.

pub fn is_empty(&self) -> bool

Returns true iff this log does not have any entries.

pub fn index_size_bytes(&self) -> u64

Returns the number of index memory bytes in use.

pub fn data_size_bytes(&self) -> u64

Returns the number of data memory bytes in use.

pub fn log_size_bytes(&self) -> u64

Returns the total size of all logged entries in bytes.

pub fn len(&self) -> u64

Returns the number of entries in the log.

pub fn get(&self, idx: u64) -> Option<T>

Returns the entry at the specified index. Returns None if the entry does not exist.

pub fn iter(&self) -> Iter<'_, T, INDEX, DATA>

Returns an iterator over log entries.

pub fn read_entry(&self, idx: u64, buf: &mut Vec<u8>) -> Result<(), NoSuchEntry>

Reads the contents of the entry with the specified index into a byte vector.

NOTE: if the entry exists, this function resizes buf to match the entry size.

NOTE: this function returns a Result to make the compiler emit a warning if the caller ignores the result.

pub fn append(&self, item: &T) -> Result<u64, WriteError>

Appends a new entry to the log. If successful, returns the index of the entry.

POST-CONDITION: Ok(idx) = log.append(E) ⇒ log.get(idx) = Some(E)