Struct stack_array::Array

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

A data structure for storing and manipulating fixed number of elements of a specific type.

Implementations

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

pub fn new() -> Self

Creates a new Array<T, N>.

Examples

use stack_array::Array;

let arr = Array::<u8, 4>::new();
// or
let arr: Array<u8, 4> = Array::new();

pub const fn capacity(&self) -> usize

Returns the number of elements the array can hold.

Examples

use stack_array::Array;

let arr: Array<u8, 4> = Array::new();
assert_eq!(arr.capacity(), 4);

pub const fn is_full(&self) -> bool

Returns true, If the array is full.

Examples

use stack_array::Array;

let arr: Array<u8, 3> = Array::from([1, 2]);
assert!(!arr.is_full());

pub const fn remaining_capacity(&self) -> usize

Returns the number of elements can be inserted into the array.

Examples

use stack_array::Array;

let arr: Array<u8, 3> = Array::from([1, 2]);
assert_eq!(arr.remaining_capacity(), 1);

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

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

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

The drain method can emulate truncate, but causes the excess elements to be returned instead of dropped.

Examples

Truncating a five element array to two elements:

use stack_array::Array;

let mut arr: Array<u8, 5> = Array::from([1, 2, 3, 4, 5]);
arr.truncate(2);
assert_eq!(arr[..], [1, 2]);

No truncation occurs when len is greater than the array’s current length:

use stack_array::Array;

let mut arr: Array<u8, 5> = Array::from([1, 2, 3]);
arr.truncate(8);
assert_eq!(arr[..], [1, 2, 3]);

Truncating when len == 0 is equivalent to calling the clear method.

use stack_array::Array;

let mut arr: Array<u8, 5> = Array::from([1, 2, 3]);
arr.truncate(0);
assert_eq!(arr[..], []);

pub fn as_slice(&self) -> &[T]

Extracts a slice containing the entire array.

Equivalent to &s[..].

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

Extracts a mutable slice of the entire array.

Equivalent to &mut s[..].

pub fn as_ptr(&self) -> *const T

Returns a raw pointer to the array’s buffer.

The caller must ensure that the array outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the array may cause its buffer to be reallocated, which would also make any pointers to it invalid.

The caller must also ensure that the memory the pointer (non-transitively) points to is never written to (except inside an UnsafeCell) using this pointer or any pointer derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.

pub fn as_mut_ptr(&mut self) -> *mut T

Returns an unsafe mutable pointer to the array’s buffer.

The caller must ensure that the array outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the array may cause its buffer to be reallocated, which would also make any pointers to it invalid.

pub unsafe fn set_len(&mut self, new_len: usize)

Returns an unsafe mutable pointer to the array’s buffer.

The caller must ensure that the array outlives the pointer this function returns, or else it will end up pointing to garbage. Modifying the array may cause its buffer to be reallocated, which would also make any pointers to it invalid.

pub fn swap_remove(&mut self, index: usize) -> T

Removes an element from the array and returns it.

The removed element is replaced by the last element of the array.

This does not preserve ordering, but is O(1). If you need to preserve the element order, use remove instead.

Panics

Panics if index is out of bounds.

Examples

use stack_array::Array;

let mut arr: Array<&str, 4> = Array::from(["foo", "bar", "baz", "qux"]);

assert_eq!(arr.swap_remove(1), "bar");
assert_eq!(arr[..], ["foo", "qux", "baz"]);

assert_eq!(arr.swap_remove(0), "foo");
assert_eq!(arr[..], ["baz", "qux"]);

pub fn insert(&mut self, index: usize, element: T)

Inserts an element at position index within the array, shifting all elements after it to the right.

Examples

use stack_array::Array;

let mut list: Array<u8, 3> = Array::from([3]);
list.insert(0, 1);
assert_eq!(&list[..], [1, 3]);
list.insert(1, 2);
assert_eq!(&list[..], [1, 2, 3]);

Panics

Panics if the index is out of bounds.

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

Removes an element from position index within the array, shifting all elements after it to the left.

Note: Because this shifts over the remaining elements, it has a worst-case performance of O(n). If you don’t need the order of elements to be preserved, use swap_remove instead.

Examples

use stack_array::Array;

let mut list: Array<u8, 3> = Array::from([1, 2, 3]);
assert_eq!(list.remove(0), 1);
assert_eq!(list.remove(0), 2);
assert_eq!(list.remove(0), 3);

Panics

Panics if the index is out of bounds.

pub fn retain<F>(&mut self, f: F) where
    F: FnMut(&mut T) -> bool, 

Retains only the elements specified by the predicate.

In other words, remove all elements e such that f(&e) returns false. This method operates in place, visiting each element exactly once in the original order, and preserves the order of the retained elements.

Examples

use stack_array::Array;

let mut arr: Array<u8, 4> = Array::from([1, 2, 3, 4]);

arr.retain(|x| *x % 2 == 0);
assert_eq!(arr[..], [2, 4]);

Because the elements are visited exactly once in the original order, external state may be used to decide which elements to keep.

use stack_array::Array;

let mut arr: Array<u8, 5> = Array::from([1, 2, 3, 4, 5]);
let keep = [false, true, true, false, true];
let mut iter = keep.iter();
arr.retain(|_| *iter.next().unwrap());
assert_eq!(arr[..], [2, 3, 5]);

pub fn dedup_by_key<F, K>(&mut self, key: F) where
    F: FnMut(&mut T) -> K,
    K: PartialEq, 

Removes all but the first of consecutive elements in the array that resolve to the same key.

If the array is sorted, this removes all duplicates.

Examples

use stack_array::Array;

let mut arr: Array<u8, 5> = Array::from([10, 20, 21, 30, 20]);

arr.dedup_by_key(|i| *i / 10);

assert_eq!(arr[..], [10, 20, 30, 20]);

pub fn dedup_by<F>(&mut self, same_bucket: F) where
    F: FnMut(&mut T, &mut T) -> bool, 

Removes all but the first of consecutive elements in the array satisfying a given equality relation.

The same_bucket function is passed references to two elements from the array and must determine if the elements compare equal. The elements are passed in opposite order from their order in the slice, so if same_bucket(a, b) returns true, a is removed.

If the array is sorted, this removes all duplicates.

Examples

use stack_array::Array;

let mut arr: Array<&str, 5> = Array::from(["foo", "bar", "Bar", "baz", "bar"]);

arr.dedup_by(|a, b| a.eq_ignore_ascii_case(b));

assert_eq!(arr[..], ["foo", "bar", "baz", "bar"]);

pub fn push(&mut self, value: T)

Appends an element to the back of a collection

Examples

use stack_array::Array;

let mut arr: Array<u8, 3> = Array::from([1]);
arr.push(2);
arr.push(3);
assert_eq!(&arr[..], [1, 2, 3]);

Panics

Panics if the array is full.

pub fn pop(&mut self) -> T

Removes the last element from a collection and returns it.

Examples

use stack_array::Array;

let mut arr: Array<u8, 3> = Array::from([1, 2]);
assert_eq!(arr.pop(), 2);
assert_eq!(arr.pop(), 1);
assert!(arr.is_empty());

Panics

Panics if the array is empty.

pub fn append(&mut self, other: impl AsRef<[T]>)

Moves all the elements of other into Self

Panics

Panics if the number of elements in the array overflows.

Examples

use stack_array::Array;

let mut arr: Array<u8, 6> = Array::from([1, 2, 3]);
arr.append([4, 5, 6]);
assert_eq!(arr[..], [1, 2, 3, 4, 5, 6]);

pub fn drain<R>(&mut self, range: R) -> Drain<'_, T, N> where
    R: RangeBounds<usize>, 

Creates a draining iterator that removes the specified range in the array and yields the removed items.

When the iterator is dropped, all elements in the range are removed from the array, even if the iterator was not fully consumed. If the iterator is not dropped (with mem::forget for example), it is unspecified how many elements are removed.

Panics

Panics if the starting point is greater than the end point or if the end point is greater than the length of the array.

Examples

use stack_array::Array;
 
let mut arr: Array<u8, 3> = Array::from([1, 2, 3]);
let vec: Vec<_> = arr.drain(1..).collect();
assert_eq!(arr[..], [1]);
assert_eq!(vec[..], [2, 3]);

// A full range clears the array
arr.drain(..);
assert_eq!(arr[..], []);

pub fn clear(&mut self)

Clears the array, removing all values.

Examples

use stack_array::Array;

let mut list: Array<u8, 3> = Array::from([1, 2, 3]);
list.clear();
assert!(list.is_empty());

pub const fn len(&self) -> usize

Returns the number of elements currently in the array.

Examples

use stack_array::Array;
     
let arr: Array<u8, 3> = Array::from([1, 2]);
assert_eq!(arr.len(), 2);

pub const fn is_empty(&self) -> bool

Returns true if the array contains no elements.

Examples

use stack_array::Array;

let mut arr: Array<u8, 2> = Array::new();
assert!(arr.is_empty());

arr.push(1);
assert!(!arr.is_empty());

Trait Implementations

impl<T, const N: usize> AsMut<[T]> for Array<T, N>

fn as_mut(&mut self) -> &mut [T]

Performs the conversion.

impl<T, const N: usize> AsRef<[T]> for Array<T, N>

fn as_ref(&self) -> &[T]

Performs the conversion.

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

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

impl<T, const N: usize> Deref for Array<T, N>

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, const N: usize> DerefMut for Array<T, N>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T, const N: usize> From<&'_ [T]> for Array<T, N>

fn from(values: &[T]) -> Self

Performs the conversion.

impl<T, const N: usize, const S: usize> From<[T; S]> for Array<T, N>

fn from(values: [T; S]) -> Self

Performs the conversion.