Struct SmallDeque 

pub struct SmallDeque<T, const N: usize> { /* private fields */ }

A double-ended queue that lives on the stack for up to N items, then spills to a heap-allocated VecDeque transparently.

Stack representation

Items are stored in a ring buffer of [MaybeUninit<T>; N] with a head cursor and a len counter. Two helpers, wrap_add and wrap_sub, implement the modular arithmetic using a bitmask (requires N to be a power of two — enforced by a const assertion in new).

Spill behaviour

When push_back or push_front causes len > capacity on the stack, the ring buffer is drained in logical order into a freshly heap-allocated VecDeque via spill_to_heap. After a spill, all subsequent mutations go directly to the VecDeque; the struct never returns to stack storage.

Generic parameters

Parameter	Meaning
T	Element type
N	Stack capacity; must be a power of two

Compile-time assertions

new() uses const { assert!(...) } to verify:

• size_of::<Self>() <= 16 KiB — prevents accidental blowing of the stack frame.
• N.is_power_of_two() — required for bitmask ring-buffer arithmetic.

Implementations

impl<T, const N: usize> SmallDeque<T, N>

pub fn new() -> Self

Creates a new empty deque backed by stack storage.

Panics (compile-time)

Asserts that size_of::<Self>() <= 16 KiB and that N is a power of two.

pub fn with_capacity(capacity: usize) -> Self

Creates a deque that starts on the heap if capacity > N, otherwise on the stack.

Useful when the caller already knows the required size will exceed N.

pub fn is_on_stack(&self) -> bool

Returns true if the deque is currently using stack storage.

pub fn len(&self) -> usize

Returns the number of elements currently in the deque.

pub fn is_empty(&self) -> bool

Returns true if the deque contains no elements.

pub fn capacity(&self) -> usize

Returns the current capacity (not necessarily N after a spill).

pub fn get(&self, index: usize) -> Option<&T>

Returns a shared reference to the element at logical index, or None.

Logical index 0 is the front (oldest element).

pub fn get_mut(&mut self, index: usize) -> Option<&mut T>

Returns an exclusive reference to the element at logical index, or None.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements, spilling to the heap if necessary.

pub fn push_back(&mut self, item: T)

Appends item to the back of the deque. Spills to heap if the stack is full.

pub fn push_front(&mut self, item: T)

Prepends item to the front of the deque. Spills to heap if the stack is full.

pub fn pop_back(&mut self) -> Option<T>

Removes and returns the last element, or None if empty.

pub fn pop_front(&mut self) -> Option<T>

Removes and returns the first element, or None if empty.

pub fn remove(&mut self, index: usize) -> Option<T>

Removes the element at logical index and returns it, or None if out of bounds.

Chooses whether to shift from the front or back depending on which is cheaper (shift the shorter half).

pub fn clear(&mut self)

Shortens the deque to len, dropping all elements beyond that point.

If len >= self.len(), this is a no-op.

pub fn truncate(&mut self, len: usize)

Shortens the deque to at most len elements, dropping those beyond.

pub fn front(&self) -> Option<&T>

Returns a shared reference to the front element, or None if empty.

pub fn back(&self) -> Option<&T>

Returns a shared reference to the back element, or None if empty.

pub fn front_mut(&mut self) -> Option<&mut T>

Returns an exclusive reference to the front element, or None if empty.

pub fn back_mut(&mut self) -> Option<&mut T>

Returns an exclusive reference to the back element, or None if empty.

pub fn as_slices(&self) -> (&[T], &[T])

Returns up to two contiguous slices covering the logical range [0, len).

Returns (head_slice, &[]) when the ring buffer hasn’t wrapped, or (head_slice, tail_slice) when it has. On the heap path delegates to VecDeque::as_slices.

pub fn as_mut_slices(&mut self) -> (&mut [T], &mut [T])

Mutable counterpart of as_slices.

Trait Implementations

impl<T, const N: usize> AnyDeque<T> for SmallDeque<T, N>

fn len(&self) -> usize

Returns the number of elements in the deque.

fn push_back(&mut self, item: T)

Appends an element to the back.

fn push_front(&mut self, item: T)

Prepends an element to the front.

fn pop_back(&mut self) -> Option<T>

Removes and returns the element from the back, or None if empty.

fn pop_front(&mut self) -> Option<T>

Removes and returns the element from the front, or None if empty.

fn remove(&mut self, index: usize) -> Option<T>

Removes and returns the element at index, or None if out of bounds.

fn clear(&mut self)

Removes all elements.

fn front(&self) -> Option<&T>

Returns a shared reference to the front element, or None if empty.

fn back(&self) -> Option<&T>

Returns a shared reference to the back element, or None if empty.

fn front_mut(&mut self) -> Option<&mut T>

Returns an exclusive reference to the front element, or None if empty.

fn back_mut(&mut self) -> Option<&mut T>

Returns an exclusive reference to the back element, or None if empty.

fn is_empty(&self) -> bool

Returns true if the deque contains no elements.

impl<T: Clone, const N: usize> Clone for SmallDeque<T, N>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug, const N: usize> Debug for SmallDeque<T, N>

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

Formats the value using the given formatter.

impl<T, const N: usize> Default for SmallDeque<T, N>

fn default() -> Self

Returns the “default value” for a type.

impl<T, const N: usize> Drop for SmallDeque<T, N>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, const N: usize> Extend<T> for SmallDeque<T, N>

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T, const N: usize> FromIterator<T> for SmallDeque<T, N>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: Ord, const N: usize> Ord for SmallDeque<T, N>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq, const N: usize> PartialEq for SmallDeque<T, N>

fn eq(&self, other: &Self) -> 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<T: PartialOrd, const N: usize> PartialOrd for SmallDeque<T, N>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Eq, const N: usize> Eq for SmallDeque<T, N>