Struct ArrayDeque

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

A double-ended queue with fixed capacity, backed by an array.

The capacity of the deque is determined by the generic parameter N.

All values are stored inline; that is, the size of of ArrayDeque<T, N> is at least size_of::<[T; N]>(), regardless of the number of elements currently stored in the deque.

Implementations

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

where T: Default,

pub fn new() -> Self

Constructs a new, empty ArrayDeque<T, N>.

Example

let mut deque: ArrayDeque<String, 8> = ArrayDeque::new();

assert!(deque.is_empty());

pub fn capacity(&self) -> usize

Returns the maximum number of elements the deque may hold.

This has the same value as the const generic parameter N.

Example

use holodeque::ArrayDeque;
let mut deque: ArrayDeque<(), 42> = ArrayDeque::new();

assert_eq!(deque.capacity(), 42);

pub fn len(&self) -> usize

Returns the number of elements in the deque.

Example

let mut deque: ArrayDeque<char, 3> = ArrayDeque::new();

deque.push_back('a')?;
deque.push_back('b')?;
deque.push_back('c')?;

assert_eq!(deque.len(), 3);

pub fn is_empty(&self) -> bool

Returns true if the deque contains no elements.

Example

let mut deque: ArrayDeque<u32, 8> = ArrayDeque::new();

deque.push_back(42)?;
assert!(!deque.is_empty());
deque.pop_front();
assert!(deque.is_empty());

pub fn is_full(&self) -> bool

Returns true if the deque is at capacity.

Example

let mut deque: ArrayDeque<u32, 4> = ArrayDeque::new();

deque.push_back(1)?;
deque.push_back(2)?;
deque.push_back(3)?;
assert!(!deque.is_full());

deque.push_back(4)?;
assert!(deque.is_full());

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

Returns a reference to the first element in the deque.

If the deque is empty, None is returned.

Example

let mut deque: ArrayDeque<char, 3> = ArrayDeque::new();

deque.push_back('a')?;
deque.push_back('b')?;
deque.push_back('c')?;

assert_eq!(deque.front(), Some(&'a'));

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

Returns a mutable reference to the first element in the deque.

If the deque is empty, None is returned.

Example

let mut deque: ArrayDeque<&str, 4> = ArrayDeque::new();

deque.push_front("old")?;
deque.front_mut().map(|mut val| {
    *val = "new";
});

assert_eq!(deque.front(), Some(&"new"));

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

Returns a reference to the last element in the deque.

If the deque is empty, None is returned.

Example

let mut deque: ArrayDeque<char, 3> = ArrayDeque::new();

deque.push_back('a')?;
deque.push_back('b')?;
deque.push_back('c')?;

assert_eq!(deque.back(), Some(&'c'));

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

Returns a mutable reference to the last element in the deque.

If the deque is empty, None is returned.

Example

let mut deque: ArrayDeque<&str, 4> = ArrayDeque::new();

deque.push_back("old")?;
deque.back_mut().map(|mut val| {
    *val = "new";
});

assert_eq!(deque.back(), Some(&"new"));

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

Returns a pair of slices which contain, in order, the elements of the ArrayDeque.

Example

let mut deque: ArrayDeque<u32, 6> = ArrayDeque::new();

deque.push_front(3)?;
deque.push_front(6)?;
deque.push_front(9)?;
deque.push_back(5)?;
deque.push_back(10)?;
deque.push_back(15)?;

let (first, second) = deque.as_slices();
assert_eq!(first, &[9, 6, 3]);
assert_eq!(second, &[5, 10, 15]);

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

Returns a pair of mutable slices which contain, in order, the elements of the ArrayDeque.

Example

let mut deque: ArrayDeque<u32, 6> = ArrayDeque::new();

deque.push_front(3)?;
deque.push_front(6)?;
deque.push_front(9)?;
deque.push_back(5)?;
deque.push_back(10)?;
deque.push_back(15)?;

let (first_mut, second_mut) = deque.as_mut_slices();
for item in first_mut {
    *item -= 1;
}
for item in second_mut {
    *item += 1;
}

let (first, second) = deque.as_slices();
assert_eq!(first, &[8, 5, 2]);
assert_eq!(second, &[6, 11, 16]);

pub fn push_front(&mut self, item: T) -> Result<(), CapacityError<T>>

Prepends an element to the deque.

If the deque is at capacity, an Err containing the pushed value is returned.

Example

let mut deque: ArrayDeque<u32, 3> = ArrayDeque::new();

deque.push_front(1)?;
deque.push_front(2)?;
deque.push_front(3)?;

assert_eq!(deque.front(), Some(&3));
assert_eq!(deque.back(), Some(&1));

// Another element would exceed capacity, so this fails.
let err = deque.push_front(4).unwrap_err();
assert_eq!(err.into_inner(), 4);

pub fn push_back(&mut self, item: T) -> Result<(), CapacityError<T>>

Appends an element to the deque.

If the deque is at capacity, an Err containing the pushed value is returned.

Example

let mut deque: ArrayDeque<u32, 3> = ArrayDeque::new();

deque.push_back(1)?;
deque.push_back(2)?;
deque.push_back(3)?;

assert_eq!(deque.front(), Some(&1));
assert_eq!(deque.back(), Some(&3));

// Another element would exceed capacity, so this fails.
let err = deque.push_front(4).unwrap_err();
assert_eq!(err.into_inner(), 4);

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

Removes and returns the first element of the deque.

If the deque is empty, None is returned.

Example

let mut deque: ArrayDeque<u32, 3> = ArrayDeque::new();

deque.push_back(1)?;
deque.push_back(2)?;
deque.push_back(3)?;

assert_eq!(deque.pop_front(), Some(1));
assert_eq!(deque.pop_front(), Some(2));
assert_eq!(deque.pop_front(), Some(3));
assert_eq!(deque.pop_front(), None);

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

Removes and returns the last element of the deque.

If the deque is empty, None is returned.

Example

let mut deque: ArrayDeque<u32, 3> = ArrayDeque::new();

deque.push_back(1)?;
deque.push_back(2)?;
deque.push_back(3)?;

assert_eq!(deque.pop_back(), Some(3));
assert_eq!(deque.pop_back(), Some(2));
assert_eq!(deque.pop_back(), Some(1));
assert_eq!(deque.pop_back(), None);

pub fn clear(&mut self)

Clears the ArrayDeque, removing all values.

Example

let mut deque: ArrayDeque<usize, 8> = ArrayDeque::new();

for i in 0..deque.capacity() / 2 {
    deque.push_front(i)?;
    deque.push_back(i)?;
}

assert_eq!(deque.len(), 8);
deque.clear();
assert!(deque.is_empty());

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

Shortens the ArrayDeque, keeping the first len elements and dropping the rest.

If len is greater than the ArrayDeque’s current length, this has no effect.

Example

let mut deque: ArrayDeque<usize, 8> = ArrayDeque::new();

deque.push_back(5)?;
deque.push_back(10)?;
deque.push_back(15)?;
deque.push_back(20)?;
deque.push_back(25)?;

assert_eq!(deque.len(), 5);
deque.truncate(2);
assert_eq!(deque.len(), 2);

pub fn iter(&self) -> Iter<'_, T, N>

Returns an iterator over the elements of the deque.

Example

let mut deque: ArrayDeque<&str, 5> = ArrayDeque::new();

deque.push_back("ideas")?;
deque.push_front("green")?;
deque.push_back("sleep")?;
deque.push_front("colorless")?;
deque.push_back("furiously")?;

let sentence = deque.iter().cloned().collect::<Vec<_>>();

assert_eq!(
    sentence,
    &["colorless", "green", "ideas", "sleep", "furiously"],
);

pub fn drain_front(&mut self, n: usize) -> Option<DrainFront<'_, T, N>>

Drains n elements from the front of the deque.

If n exceeds self.len(), None is returned.

When this method is called, n elements are immediately removed from the front of the deque. If the returned iterator is dropped before yielding all its items, they are dropped along with it.

If the returned iterator is leaked (e.g. with mem::forget), the drained elements will not be dropped immediately. They may be dropped as a result of subsequent operations on the deque; otherwise, they will be dropped when the deque itself is dropped.

Example

let mut deque: ArrayDeque<u32, 5> = ArrayDeque::new();

deque.push_back(0)?;
deque.push_back(1)?;
deque.push_back(2)?;
deque.push_back(3)?;
deque.push_back(4)?;

let mut drain = deque.drain_front(3).unwrap();

assert_eq!(drain.next(), Some(0));
assert_eq!(drain.next(), Some(1));
assert_eq!(drain.next(), Some(2));
assert_eq!(drain.next(), None);
drop(drain);

assert_eq!(deque.len(), 2);

pub fn drain_back(&mut self, n: usize) -> Option<DrainBack<'_, T, N>>

Drains n elements from the back of the deque.

If n exceeds self.len(), None is returned.

When this method is called, n elements are immediately removed from the back of the deque. If the returned iterator is dropped before yielding all its items, they are dropped along with it.

If the returned iterator is leaked (e.g. with mem::forget), the drained elements will not be dropped immediately. They may be dropped as a result of subsequent operations on the deque; otherwise, they will be dropped when the deque itself is dropped.

Example

let mut deque: ArrayDeque<u32, 5> = ArrayDeque::new();

deque.push_back(0)?;
deque.push_back(1)?;
deque.push_back(2)?;
deque.push_back(3)?;
deque.push_back(4)?;

let mut drain = deque.drain_back(3).unwrap();

assert_eq!(drain.next(), Some(4));
assert_eq!(drain.next(), Some(3));
assert_eq!(drain.next(), Some(2));
assert_eq!(drain.next(), None);
drop(drain);

assert_eq!(deque.len(), 2);

Trait Implementations

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

where T: Default + Clone,

fn clone(&self) -> ArrayDeque<T, N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

where T: Default + Debug,

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

Formats the value using the given formatter.

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

where T: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, T, const N: usize> Deserialize<'de> for ArrayDeque<T, N>

where T: Deserialize<'de> + Default,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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

where T: PartialEq + Default,

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, const N: usize> Serialize for ArrayDeque<T, N>

where T: Serialize + Default,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

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

where T: PartialEq + Default,