Trait Array

pub trait Array<T>:
    AsRef<[T]>
    + AsMut<[T]>
    + Default {
    // Required methods
    fn capacity(&self) -> usize;
    fn as_ptr(&self) -> *const T;
    fn as_mut_ptr(&mut self) -> *mut T;
    unsafe fn set_len(&mut self, len: usize);
    fn len(&self) -> usize;

    // Provided methods
    fn truncate(&mut self, len: usize) { ... }
    fn as_slice(&self) -> &[T] { ... }
    fn as_mut_slice(&mut self) -> &mut [T] { ... }
    fn swap_remove(&mut self, index: usize) -> T { ... }
    fn insert(&mut self, index: usize, element: T) { ... }
    fn remove(&mut self, index: usize) -> T { ... }
    fn retain<F>(&mut self, f: F)
       where F: FnMut(&T) -> bool { ... }
    fn drain<R>(&mut self, range: R) -> Drain<'_, T, Self> 
       where R: RangeBounds<usize> { ... }
    fn dedup(&mut self)
       where T: PartialEq { ... }
    fn dedup_by_key<F, K>(&mut self, key: F)
       where F: FnMut(&mut T) -> K,
             K: PartialEq { ... }
    fn dedup_by<F>(&mut self, same_bucket: F)
       where F: FnMut(&mut T, &mut T) -> bool { ... }
    fn push(&mut self, value: T) { ... }
    fn append(&mut self, other: &mut Self) { ... }
    fn clear(&mut self) { ... }
    fn is_empty(&self) -> bool { ... }
    fn pop(&mut self) -> Option<T> { ... }
    fn ensure_capacity(&mut self, total_len: usize) { ... }
    fn remaining_capacity(&self) -> usize { ... }
    fn extend_from_slice(&mut self, other: impl AsRef<[T]>)
       where T: Copy { ... }
}

Required Methods

fn capacity(&self) -> usize

Returns the number of elements the array can hold.

Examples

use stack_array::*;

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

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.

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.

unsafe fn set_len(&mut self, len: usize)

Forces the length of the array to new_len.

This is a low-level operation that maintains none of the normal invariants of the type. Normally changing the length of a array is done using one of the safe operations instead, such as truncate or clear.

Safety

• new_len must be less than or equal to capacity().
• The elements at old_len..new_len must be initialized.

fn len(&self) -> usize

Returns the number of elements currently in the array.

Examples

use stack_array::*;

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

Provided Methods

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.

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

Extracts a slice containing the entire array.

Equivalent to &s[..].

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

Extracts a mutable slice of the entire array.

Equivalent to &mut s[..].

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::*;

let mut arr = ArrayBuf::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"]);

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::*;

let mut list: ArrayBuf<u8, 3> = ArrayBuf::from([3].as_ref());
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.

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::*;

let mut list = ArrayBuf::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.

fn retain<F>(&mut self, f: F)

where F: FnMut(&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::*;

let mut arr = ArrayBuf::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::*;

let mut arr  = ArrayBuf::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]);

fn drain<R>(&mut self, range: R) -> Drain<'_, T, Self>

where R: RangeBounds<usize>,

fn dedup(&mut self)

where T: PartialEq,

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::*;

let mut arr = ArrayBuf::from([10, 20, 21, 30, 20]);

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

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

fn dedup_by<F>(&mut self, same_bucket: F)

where F: FnMut(&mut T, &mut T) -> bool,

fn push(&mut self, value: T)

fn append(&mut self, other: &mut Self)

fn clear(&mut self)

Clears the array, removing all values.

Examples

use stack_array::*;

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

fn is_empty(&self) -> bool

Returns true if the array contains no elements.

Examples

use stack_array::*;

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

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

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

Removes the last element from a collection and returns it.

Examples

use stack_array::*;

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

fn ensure_capacity(&mut self, total_len: usize)

fn remaining_capacity(&self) -> usize

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

Examples

use stack_array::*;

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

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

where T: Copy,

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T> Array<T> for Vec<T>

fn capacity(&self) -> usize

fn truncate(&mut self, len: usize)

fn as_ptr(&self) -> *const T

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

unsafe fn set_len(&mut self, len: usize)

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

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

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

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

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

fn retain<F>(&mut self, f: F)

where F: FnMut(&T) -> bool,

fn dedup(&mut self)

where T: PartialEq,

fn dedup_by_key<F, K>(&mut self, key: F)

where F: FnMut(&mut T) -> K, K: PartialEq,

fn dedup_by<F>(&mut self, same_bucket: F)

where F: FnMut(&mut T, &mut T) -> bool,

fn push(&mut self, value: T)

fn append(&mut self, other: &mut Self)

fn clear(&mut self)

fn len(&self) -> usize

fn is_empty(&self) -> bool

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

fn ensure_capacity(&mut self, new_len: usize)

Implementors

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