Struct arrav::Arrav

#[repr(transparent)]pub struct Arrav<T: Copy, const N: usize> where
    [T; N]: LengthAtMost32,  { /* fields omitted */ }

A Vec-like type backed only by an array.

Sentinels

Arrav<T> uses a sentinel value for each type T to indicate the end of the array. For this reason, you can never insert a T::SENTINEL into an Arrav<T> — it would make the list be in an inconsistent state! All safe methods on Arrav return an error if you attempt to insert the sentinel value for the array's type, or they panic if no Result return type is provided.

Representation

In memory, an Arrav<T, N> is represented exactly like a [T; N].

Indexing

The Arrav type allows to access values by index, because it implements the [Index] trait. An example might help:

let v = arrav::avec![0, 2, 4, 6];
println!("{}", v[1]); // will display '2'

However be careful: if you try to access an index which isn't in the Arrav, as your code will panic! You cannot do this:

let v = arrav::avec![0, 2, 4, 6];
println!("{}", v[6]); // it will panic!

Use [get] if you want to check whether the index is in the Arrav.

Slicing

You can slice an Arrav just like you would an array. To get a slice, use &. Example:

fn read_slice(_: &[usize]) { /* .. */ }

let v = vec![0, 1];
read_slice(&v);

// ... and that's all!
// you can also do it like this:
let x : &[usize] = &v;

You can also get a sub-slice using &[Range]:

fn read_slice(_: &[usize]) { /* .. */ }

let v = vec![0, 1, 2];
read_slice(&v[1..2]);

In Rust, it's more common to pass slices as arguments rather than vectors when you just want to provide a read access.

Mutability

Since an Arrav<T> cannot hold all legal values of T (specifically, not the sentinel value), you cannot safely get mutable access to the elements of the arrav. Instead, you must use [set], which returns an error if the sentinel value is inserted, or the unsafe [get_mut] method.

Methods

impl<T, const N: usize> Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

pub const fn new() -> Self

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

You will generally want to specify the capacity of the Arrav when you construct it:

let mut av: Arrav<i32, 4> = Arrav::new();

You can often give _ instead of the type (here i32), but this will not work for the capacity.

pub fn repeat(e: T) -> Result<Self, IsSentinel<T>> where
    T: Copy, 

Constructs a new Arrav<T, N> and fills it with copies of e.

You will generally want to specify the capacity of the Arrav when you construct it:

let mut av: Arrav<_, 4> = Arrav::repeat(3).unwrap();

impl<T, const N: usize> Arrav<T, N> where
    T: Copy,
    [T; N]: LengthAtMost32, 

pub const unsafe fn from_array_unchecked(arr: [T; N]) -> Self

Constructs a new Arrav<T, N> directly from a backing array.

Safety

This method does not check that T::SENTINEL only appears in a suffix of the array's elements. If it appears elsewhere, methods will do strange things.

impl<T, const N: usize> Arrav<T, N> where
    T: Copy,
    [T; N]: LengthAtMost32, 

pub const fn capacity(&self) -> usize

Returns the number of elements the Arrav can hold without reallocating.

Examples

let av: Arrav<i32, 10> = Arrav::new();
assert_eq!(av.capacity(), 10);

impl<T, const N: usize> Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

pub fn len(&self) -> usize where
    Self: SpecializedLen, 

Returns the number of elements in the Arrav, also referred to as its 'length'.

Since the Arrav does not store the number of non-sentinel elements, it must search the elements of the backing array for the first sentinel in order to compute the length. This should be very fast for small N, but may become a bottleneck at large N.

Examples

let av = arrav::avec![1, 2, 3];
assert_eq!(av.len(), 3);

pub fn is_empty(&self) -> bool

Returns true if the Arrav contains no elements.

Examples

let mut v: Arrav<_, 4> = Arrav::new();
assert!(v.is_empty());

v.try_push(1).unwrap();
assert!(!v.is_empty());

pub const fn iter(&self) -> ArravIter<T, N>

Returns an iterator over the elements.

Examples

let x = avec![1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(1));
assert_eq!(iterator.next(), Some(2));
assert_eq!(iterator.next(), Some(4));
assert_eq!(iterator.next(), None);

impl<T: Copy, const N: usize> Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

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

Gets a reference to the element at position index.

Returns None if index is greater than or equal to the arrav's length.

pub fn get_range(&self, index: Range<usize>) -> Option<&[T]>

Gets a reference to the slice of elements whose indices fall in the given range.

Returns None if the range does not fall within the bounds of the Arrav.

pub fn set(&mut self, index: usize, value: T) -> Result<(), IsSentinel<T>>

Sets the value at index to value.

Returns an error if value is the sentinel value.

Panics

Panics if index is outside the bounds of the Arrav.

impl<T, const N: usize> Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

pub fn try_push(&mut self, t: T) -> Result<(), PushError<T>>

Appends an element to the back of the Arrav.

Returns Err if the provided value is T's [sentinel value], or if the Arrav is already full.

sentinel value

Examples

let mut av: Arrav<i32, 3> = Arrav::new();
av.try_push(1).unwrap();
av.try_push(2).unwrap();
assert_eq!(av, [1, 2]);

// this fails since it is pushing the sentinel value
av.try_push(std::i32::MAX).unwrap_err();

// this fills the arrav to capacity
av.try_push(3).unwrap();

// this fails since the arrav is full
av.try_push(4).unwrap_err();

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

Removes the last element from the Arrav and returns it, or None if it is empty.

Examples

let mut av = avec![1, 2, 3];
assert_eq!(av.pop(), Some(3));
assert_eq!(av, [1, 2]);
assert_eq!(av.pop(), Some(2));
assert_eq!(av.pop(), Some(1));
assert_eq!(av.pop(), None);

pub fn clear(&mut self)

Clears the Arrav, removing all values.

Note that this method has no effect on the allocated capacity of the Arrav.

Examples

let mut v = avec![1, 2, 3];

v.clear();

assert!(v.is_empty());

pub fn expand<const N2: usize>(self) -> Arrav<T, N2> where
    [T; N2]: LengthAtMost32, 

Increases the capacity of an Arrav by moving to a larger backing array.

Examples

let v = avec![1];
assert_eq!(v.capacity(), 1);
let v: Arrav<_, 3> = v.expand();
assert_eq!(v.capacity(), 3);

Panics

Panics if N2 < N.

let v = avec![1, 2, 3];
assert_eq!(v.capacity(), 3);
let v: Arrav<_, 1> = v.expand();

pub fn resize(&mut self, new_len: usize, value: T) -> Result<(), IsSentinel<T>>

Resizes the Arrav in-place so that len is equal to new_len.

If new_len is greater than len, the Arrav is extended by the difference, with each additional slot filled with value. If new_len is less than len, the Arrav is simply truncated.

Examples

let mut v: Arrav<_, 3> = avec![1].expand();
v.resize(3, 2);
assert_eq!(v, [1, 2, 2]);

let mut v = avec![1, 2, 3, 4];
v.resize(2, 0);
assert_eq!(v, [1, 2]);

pub fn try_from_iter<I>(iter: I) -> Result<Self, IsSentinel<T>> where
    I: IntoIterator<Item = T>, 

Creates an Arrav from an iterator.

Returns Err if one of the values in the iterator is the sentinel value.

Panics

Panics if the iterator yields more than N elements.

Examples

use std::iter::FromIterator;
let five_fives = std::iter::repeat(5).take(5);
let v: Arrav<_, 5> = Arrav::try_from_iter(five_fives).unwrap();
assert_eq!(v, avec![5, 5, 5, 5, 5]);

Arrav::<_, 1>::try_from_iter(std::iter::once(std::i32::MAX)).unwrap_err();

pub fn try_extend<I>(&mut self, iter: I) -> Result<(), IsSentinel<T>> where
    I: IntoIterator<Item = T>, 

Extends an Arrav with elements from an iterator.

Returns Err if one of the values in the iterator is the sentinel value. The values yielded by the iterator before the sentinel value are still pushed.

Panics

Panics if the capacity of the Arrav is exceeded.

Examples

let mut v: Arrav<_, 5> = Arrav::new();
v.try_push(1).unwrap();
v.try_extend(vec![2, 3, 4]).unwrap();
assert_eq!(v, avec![1, 2, 3, 4]);

v.try_extend(vec![5, std::i32::MAX]).unwrap_err();
assert_eq!(v, avec![1, 2, 3, 4, 5]);

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

Removes an element from the Arrav and returns it.

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

This does not preserve ordering, but is O(1).

Panics

Panics if index is out of bounds.

Examples

let mut v = avec![1, 2, 3, 4];

assert_eq!(v.swap_remove(1), 2);
assert_eq!(v, [1, 4, 3]);

assert_eq!(v.swap_remove(0), 1);
assert_eq!(v, [3, 4]);

impl<T: Copy, const N: usize> Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

pub unsafe fn get_unchecked(&self, index: usize) -> &T

Gets a reference to the element at position index.

Safety

This method does not perform any bounds checks or sentinel checks on the index.

pub unsafe fn get_unchecked_range(&self, index: Range<usize>) -> &[T]

Gets a reference to the slice of elements whose indices fall in the given range.

Safety

This method does not perform any bounds checks or sentinel checks on the index.

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

Gets an exclusive reference to the element at position index.

This method does perform bounds and sentinel checks.

Safety

This method is unsafe, because you must ensure that you do not use the returned reference to overwrite the T with T's sentinel value.

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

Gets an exclusive reference to the element at position index.

Safety

This method does not perform bounds or sentinel checks.

Like [get_mut], this method is also unsafe because you must ensure that you do not use the returned reference to overwrite the T with T's sentinel value.

Trait Implementations

impl<T, const N: usize> AsRef<[T]> for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

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

Performs the conversion.

impl<T: Clone + Copy, const N: usize> Clone for Arrav<T, N> where
    [T; N]: LengthAtMost32, 

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Copy, const N: usize> Copy for Arrav<T, N> where
    [T; N]: LengthAtMost32, 

impl<T: Debug, const N: usize> Debug for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

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

Formats the value using the given formatter.

impl<T, const N: usize> Default for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

fn default() -> Self

Returns the "default value" for a type.

impl<T, const N: usize> Deref for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

type Target = [T]

The resulting type after dereferencing.

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

Dereferences the value.

impl<T, const N: usize> Eq for Arrav<T, N> where
    T: Eq + Copy + Sentinel,
    [T; N]: LengthAtMost32, 

impl<T, const N: usize> Extend<T> for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

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

Extends a collection with the contents of an iterator.

impl<T, const N: usize> FromIterator<T> for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

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

Creates a value from an iterator.

impl<T: Hash + Copy, const N: usize> Hash for Arrav<T, N> where
    [T; N]: LengthAtMost32, 

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<T, const N: usize> Index<Range<usize>> for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

type Output = [T]

The returned type after indexing.

fn index(&self, idx: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, const N: usize> Index<usize> for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

type Output = T

The returned type after indexing.

fn index(&self, idx: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, const N: usize> IntoIterator for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

type IntoIter = ArravIter<T, N>

Which kind of iterator are we turning this into?

type Item = T

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, const N: usize> IntoIterator for &'a Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

type IntoIter = ArravIter<T, N>

Which kind of iterator are we turning this into?

type Item = T

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, const N: usize> Ord for Arrav<T, N> where
    T: Ord + Copy + Sentinel,
    [T; N]: LengthAtMost32, 

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

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

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

Restrict a value to a certain interval.

impl<T, const N: usize, const AN: usize> PartialEq<[T; AN]> for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

fn eq(&self, rhs: &[T; AN]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, const N: usize> PartialEq<[T]> for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

fn eq(&self, rhs: &[T]) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, const N1: usize, const N2: usize> PartialEq<Arrav<T, N2>> for Arrav<T, N1> where
    T: PartialEq + Copy + Sentinel,
    [T; N1]: LengthAtMost32,
    [T; N2]: LengthAtMost32, 

fn eq(&self, rhs: &Arrav<T, N2>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, const N1: usize, const N2: usize> PartialOrd<Arrav<T, N2>> for Arrav<T, N1> where
    T: PartialOrd + Copy + Sentinel,
    [T; N1]: LengthAtMost32,
    [T; N2]: LengthAtMost32, 

fn partial_cmp(&self, other: &Arrav<T, N2>) -> Option<Ordering>

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

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

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

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

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

impl<T, const N: usize> TryFrom<[T; N]> for Arrav<T, N> where
    T: Copy + Sentinel,
    [T; N]: LengthAtMost32, 

type Error = ([T; N], IsSentinel<T>)

The type returned in the event of a conversion error.

fn try_from(arr: [T; N]) -> Result<Self, Self::Error>

Performs the conversion.