API referencestd/embedded

std/embedded/storage

Public declarations, types, methods, and source contracts for std/embedded/storage.

On this page

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

length bytes of a flash device from start, as a flash device of its own whose offsets count from start. It owns the device, so nothing else writes there; release gives it back.

pub struct Region<F: hal.Flash>: hal.Flash {
    // Private implementation fields omitted.
}

Region.new

Function · Source

The region of flash from start. 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 length bytes of flash: InvalidInput unless length is 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_len bytes 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 key into the start of buffer and 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 value under key, 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 key and 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 of key, 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 if key is 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)

Search every guide, reference page, and API declaration.