Struct SmallMap 

pub struct SmallMap<K, V, const N: usize> { /* private fields */ }

A map that lives on the stack for N items, then automatically spills to the heap.

Overview

• Stack State: Zero allocations. Extremely fast FNV hashing. Data is stored inline.
• Heap State: Standard HashMap performance. Data is stored on the heap.
• Spill: Occurs automatically when the stack capacity N is exceeded. This is a “Zero-Allocation Move”—keys/values are moved, not cloned.

Capacity Constraints (N)

Due to the underlying heapless implementation constraints:

• N must be a power of two (e.g., 2, 4, 8, 16, 32).
• N must be greater than 1.

Compilation will fail if these constraints are not met.

Implementations

impl<K, V, const N: usize> SmallMap<K, V, N>

where K: Eq + Hash,

pub const MAX_STACK_SIZE: usize

The maximum allowed stack size in bytes (16 KB).

Because SmallMap stores data inline, a large N or large Key/Value types can easily exceed the thread stack size. This limit prevents that.

pub fn new() -> Self

Creates a new empty map on the stack.

Compile-Time Safety Check

This function enforces a strict size limit of 16 KB (MAX_STACK_SIZE).

Because the map size is known at compile time, the compiler will fail to build if the total size of SmallMap<K, V, N> exceeds this limit. This prevents accidental Stack Overflows (Segfaults).

How to fix the build error

If your code fails to compile pointing to this assertion, you have two options:

1. Reduce N: If you don’t need that many items on the stack.
2. Box the Value: Change SmallMap<K, V, N> to SmallMap<K, Box<V>, N>. This moves the bulk of the data to the heap immediately, keeping the stack footprint small.

pub fn is_on_stack(&self) -> bool

Returns true if the map is currently storing data on the stack. Returns false if it has spilled to the heap.

pub fn len(&self) -> usize

Returns the number of elements in the map.

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

pub fn clear(&mut self)

Clears the map, removing all key-value pairs.

• Stack: Resets the index to 0.
• Heap: Clears the map but keeps the allocated memory for reuse.

pub fn insert(&mut self, key: K, value: V) -> Option<V>

Inserts a key-value pair into the map.

If the map is on the stack and full, this triggers a Spill to Heap. This implementation explicitly checks capacity constraints before insertion, ensuring a clean separation between the “Spill Decision” and the “Insert Action”.

pub fn get<Q>(&self, key: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Retrieves a reference to the value corresponding to the key.

This method is generic over the key type Q. This allows you to lookup values using a reference (like &str) without allocating a new owned key (like String).

How it works (The Borrow Trait)

If the map stores keys of type K (e.g., String), you can pass a query key of type Q (e.g., str) as long as:

1. K implements Borrow<Q> (meaning String can be viewed as str).
2. Q implements Hash and Eq.
3. The hash of the borrowed K is identical to the hash of Q.

Example

// Assuming generic import for doc test
use small_collections::SmallMap;

let mut map = SmallMap::<String, i32, 4>::new();
map.insert("Apple".to_string(), 10);

// Works efficiently without allocating a new String for the lookup:
assert_eq!(map.get("Apple"), Some(&10));

pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Retrieves a mutable reference to the value corresponding to the key.

pub fn remove<Q>(&mut self, key: &Q) -> Option<V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Removes a key from the map, returning the value at the key if the key was previously in the map.

pub fn contains_key<Q>(&self, key: &Q) -> bool

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Returns true if the map contains a value for the specified key.

impl<K, V, const N: usize> SmallMap<K, V, N>

where K: Eq + Hash,

pub fn entry(&mut self, key: K) -> SmallMapEntry<'_, K, V, N>

Gets the given key’s corresponding entry in the map for in-place manipulation.

impl<K, V, const N: usize> SmallMap<K, V, N>

where K: Eq + Hash,

pub fn iter(&self) -> SmallMapIter<'_, K, V>

Returns an iterator over the map.

Trait Implementations

impl<K: Eq + Hash, V, const N: usize> AnyMap<K, V> for SmallMap<K, V, N>

fn len(&self) -> usize

Returns the number of elements.

fn insert(&mut self, key: K, value: V) -> Option<V>

Inserts the given key-value pair or element.

fn get<Q>(&self, key: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Returns a reference to the value corresponding to the key.

fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Returns a reference to the value corresponding to the key.

fn remove<Q>(&mut self, key: &Q) -> Option<V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Removes the specified element or key-value pair.

fn contains_key<Q>(&self, key: &Q) -> bool

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Returns true if the collection contains the item or key.

fn clear(&mut self)

Clears all elements from the collection.

fn is_empty(&self) -> bool

Returns true if the collection is empty.

impl<K, V, const N: usize> Clone for SmallMap<K, V, N>

where K: Eq + Hash + Clone, V: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K: Debug + Eq + Hash, V: Debug, const N: usize> Debug for SmallMap<K, V, N>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<K: Eq + Hash, V, const N: usize> Default for SmallMap<K, V, N>

fn default() -> Self

Returns the “default value” for a type.

impl<K, V, const N: usize> Drop for SmallMap<K, V, N>

fn drop(&mut self)

Executes the destructor for this type.

impl<K, V, const N: usize> FromIterator<(K, V)> for SmallMap<K, V, N>

where K: Eq + Hash,

fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> Self

Creates a value from an iterator.

impl<K, V, Q, const N: usize> Index<&Q> for SmallMap<K, V, N>

where K: Eq + Hash + Borrow<Q>, Q: Eq + Hash + ?Sized,

Allows read access using map[&key].

Panics

Panics if the key is not present in the map.

type Output = V

The returned type after indexing.

fn index(&self, key: &Q) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<K, V, Q, const N: usize> IndexMut<&Q> for SmallMap<K, V, N>

where K: Eq + Hash + Borrow<Q>, Q: Eq + Hash + ?Sized,

Allows mutable access using map[&key] = new_value.

Panics

Panics if the key is not present in the map.

fn index_mut(&mut self, key: &Q) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<K: Eq + Hash, V, const N: usize> IntoIterator for SmallMap<K, V, N>

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = SmallMapIntoIter<K, V, N>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<K, V, const N: usize, M> PartialEq<M> for SmallMap<K, V, N>

where K: Eq + Hash, V: PartialEq, M: AnyMap<K, V>,

fn eq(&self, other: &M) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, V, const N: usize> Eq for SmallMap<K, V, N>

where K: Eq + Hash, V: Eq,