Library guide · API index and notation
This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.
import "std/embedded/storage"
Names used in signatures
Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.
| Alias | Package | Source file |
|---|---|---|
hal |
std/embedded/hal |
storage.dodo |
mem |
core/mem |
storage.dodo |
MAX_KEY_BYTES
Constant · Source
The longest key, in bytes.
pub const MAX_KEY_BYTES: usize = 64
MAX_BLOCKS
Constant · Source
The most erase blocks a store may span.
pub const MAX_BLOCKS: u32 = 64
Error
Enum · Source
What can go wrong with a store.
pub enum Error {
// The flash device reported an error.
Flash,
// The flash device cannot be used now, as on an RP2040 or RP2350 while
// core 1 runs.
Busy,
// There is no room for the record, even after compacting.
Full,
// The key is longer than MAX_KEY_BYTES, or the value is longer than
// `max_value_len` allows.
TooLarge,
// The key is empty, or the flash has a size or layout the store cannot
// use.
InvalidInput,
// The buffer is too short for the value or key.
BufferTooSmall
}
error_name
Function · Source
pub fn error_name(error: Error) -> &str from(static)
Region
Struct · Source
lengthbytes of a flash device fromstart, as a flash device of its own whose offsets count fromstart. It owns the device, so nothing else writes there;releasegives it back.
pub struct Region<F: hal.Flash>: hal.Flash {
// Private implementation fields omitted.
}
Region.new
Function · Source
The region of
flashfromstart. InvalidInput unless both are multiples of the device’s erase size and the region lies inside it.
pub fn new(flash: F, start: u32, length: u32) -> Region<F>!hal.Error from(flash)
Region.last
Function · Source
The last
lengthbytes offlash: InvalidInput unlesslengthis a multiple of the erase size and at most the device’s capacity.
pub fn last(flash: F, length: u32) -> Region<F>!hal.Error from(flash)
Region.start
Function · Source
Where the region starts on the device.
pub fn start(&self) -> u32
Region.capacity
Function · Source
pub fn capacity(&self) -> u32
Region.erase_size
Function · Source
pub fn erase_size(&self) -> u32
Region.write_size
Function · Source
pub fn write_size(&self) -> u32
Region.read
Function · Source
pub fn read(&mut self, offset: u32, buffer: &mut[u8]) -> void!hal.Error
Region.erase
Function · Source
pub fn erase(&mut self, offset: u32, length: u32) -> void!hal.Error
Region.write
Function · Source
pub fn write(&mut self, offset: u32, bytes: &[u8]) -> void!hal.Error
Region.release
Function · Source
Give back the device.
pub fn release(self) -> F from(self)
Cursor
Struct · Source
A position in a store’s keys, for Store.next_key.
pub struct Cursor {
// Private implementation fields omitted.
}
Cursor.new
Function · Source
The position before the first key.
pub fn new() -> Cursor
Store
Struct · Source
A key-value store on a flash device or region; see the package comment. Keys are 1 to MAX_KEY_BYTES bytes of text, values any bytes up to
max_value_len.
pub struct Store<F: hal.Flash> {
// Private implementation fields omitted.
}
Store.open
Function · Source
Open the store on
flash, which must span 2 to MAX_BLOCKS erase blocks of at least 256 bytes each: a new store on erased or foreign contents, which it erases as it needs the space, or the store left there before. Finishes or undoes a compaction a power cut interrupted, which may write. InvalidInput if the flash’s layout is unusable.
pub fn open(flash: F) -> Store<F>!Error from(flash)
Store.max_value_len
Function · Source
The longest value a key of
key_lenbytes may have: what fits in an erase block beside the block and record headers and the room kept for compaction.
pub fn max_value_len(&self, key_len: usize) -> usize
Store.get
Function · Source
Copy the value of
keyinto the start ofbufferand return its length, or none if the store has no such key. BufferTooSmall if the value is longer than the buffer.
pub fn get(&mut self, key: &str, buffer: &mut[u8]) -> Option<usize>!Error
Store.len_of
Function · Source
The length of the value of
key, or none if the store has no such key.
pub fn len_of(&mut self, key: &str) -> Option<usize>!Error
Store.contains
Function · Source
pub fn contains(&mut self, key: &str) -> bool!Error
Store.set
Function · Source
Store
valueunderkey, replacing any value it had. Writes nothing if the key already has this value. TooLarge if the key or value is too long, Full if the store has no room for it.
pub fn set(&mut self, key: &str, value: &[u8]) -> void!Error
Store.remove
Function · Source
Remove
keyand its value; false if the store had no such key.
pub fn remove(&mut self, key: &str) -> bool!Error
Store.get_u32
Function · Source
A u32 value, stored as 4 little-endian bytes. InvalidInput if the key’s value is not 4 bytes long.
pub fn get_u32(&mut self, key: &str) -> Option<u32>!Error
Store.set_u32
Function · Source
pub fn set_u32(&mut self, key: &str, value: u32) -> void!Error
Store.next_key
Function · Source
The next key after
cursor, copied into the start ofkey, and advance the cursor; none after the last key. Keys come in no particular order, each once. Changing the store while going through its keys may skip or repeat some. BufferTooSmall ifkeyis shorter than the key (MAX_KEY_BYTES always suffices).
pub fn next_key(&mut self, cursor: &mut Cursor, key: &mut[u8]) -> Option<usize>!Error
Store.clear
Function · Source
Remove every key, erasing all of the store’s flash.
pub fn clear(&mut self) -> void!Error
Store.flash
Function · Source
The flash, for its own queries, such as a fake’s counters. Erasing or writing the store’s part of it corrupts the store.
pub fn flash(&mut self) -> &mut F from(self)
Store.release
Function · Source
Give back the flash. The store stays there for the next open.
pub fn release(self) -> F from(self)