Struct BTreeMap 

pub struct BTreeMap<M, C = Lexicographic> { /* private fields */ }

A stable-memory B-tree, independent of DFINITY’s collection formats.

Exactly one live tree handle may own a memory region. The memory must not be mutated through aliases. Mutations stage touched pages, reserve capacity, then write them. Backing writes must either complete or trap in an atomic IC message; this is not a crash-safe filesystem database. See the package guide.

Implementations

impl<M: Memory, C: Comparator> BTreeMap<M, C>

pub fn create(memory: M, config: Config, order: C) -> Result<Self, Error>

Create a tree in an empty memory without overwriting an existing format.

Errors

Rejects nonempty memory, invalid limits, and refused growth.

pub fn open(memory: M, config: Config, order: C) -> Result<Self, Error>

Open a tree with its exact configuration and comparator identity.

Opening checks the header and root, not every page. Reads validate pages as visited; Self::validate performs a complete structural audit.

Errors

Rejects unknown formats, incompatible limits/order, and observed corruption.

pub const fn len(&self) -> u64

Number of live entries, persisted with each completed mutation.

pub const fn is_empty(&self) -> bool

Whether the tree contains no entries.

pub fn memory_bytes(&self) -> u64

Bytes reserved in the backing memory, including reusable free pages.

pub fn into_memory(self) -> M

Release the sole handle and return its backing memory for later reopening.

pub fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, Error>

Read one value by key.

Errors

Rejects malformed keys, oversized keys, and observed storage corruption.

pub fn contains_key(&self, key: &[u8]) -> Result<bool, Error>

Test key membership without reading the value payload.

Errors

Rejects invalid keys and observed key or tree-page corruption.

pub fn insert( &mut self, key: &[u8], value: &[u8], ) -> Result<Option<Vec<u8>>, Error>

Insert or replace a value, returning the previous value if present.

Errors

Rejects invalid keys, oversized inputs, corruption, or insufficient capacity before publishing changes. Memory traps follow the backing contract.

pub fn remove(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>, Error>

Remove a key, returning its previous value.

Errors

Rejects malformed keys and observed corruption without publishing changes.

pub fn range( &self, lower: Bound<&[u8]>, upper: Bound<&[u8]>, ) -> Result<Range<'_, M, C>, Error>

Iterate a bounded range in either direction without reading value payloads.

Bounds use the supplied comparator. Equal exclusive bounds yield an empty range. rev() and interleaved next/next_back are supported.

Errors

Rejects invalid bounds; traversal errors are yielded by the iterator.

pub fn iter(&self) -> Range<'_, M, C>

Traverse all entries in comparator order, with lazy value reads.

pub fn validate(&self) -> Result<(), Error>

Check every reachable page, key order, depth, occupancy, entry count and free-list ownership. This explicit audit is linear in allocated storage.

Errors

Returns an error on corruption, invalid encoded keys or invalid ordering.

Trait Implementations

impl<'a, M: Memory, C: Comparator> IntoIterator for &'a BTreeMap<M, C>

type Item = Result<Entry<'a, M, C>, Error>

The type of the elements being iterated over.

type IntoIter = Range<'a, M, C>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.