Crate array_append

array-append

array-append exports a small family of functions for working with const-generic array types:

• [concat] which concatenates two arrays
• push_right and push_left which add an element to the end or beginning of an array respectively
• split and split_end which split an array into two arrays
• pop_right and pop_left which separate the last or first element respectively from an array

And a few aliases:

• push/pop for push_right/pop_right respectively
• unshift/shift for push_left/pop_left respectively

This library requires a nightly compiler due to the use of #![feature(generic_const_exprs)]. All unsafe code has been verified to be sound by manual proof and Miri.

This library does not yet require the standard library, but it is brought in anyway unless the std default feature is disabled. This is for forward-compatibility in case std-dependent code is ever added.

Example

Create a no-alloc builder:

#![allow(incomplete_features)]
#![feature(generic_const_exprs)]

use array_append::push;

#[derive(PartialEq, Debug)]
struct Built<const N: usize> {
	whatever: [usize; N]
}

struct Builder<const N: usize> {
	whatever: [usize; N]
}

impl Builder<0> {
	pub fn new() -> Self {
		Self { whatever: [] }
	}
}

impl<const N: usize> Builder<N> {
	pub fn from_array(array: [usize; N]) -> Self {
		Self { whatever: array }
	}

	pub fn with_usize(self, new: usize) -> Builder<{N + 1}> {
		// Can't use `Self` here, because `Self` is `Builder<N>`
		Builder { whatever: push(self.whatever, new) }
	}

	pub fn build(self) -> Built<N> {
		Built { whatever: self.whatever }
	}
}

assert_eq!(
	Builder::new()
		.with_usize(1)
		.with_usize(2)
		.with_usize(3)
		.build(),
	Builder::from_array([1, 2, 3]).build()
);

Re-exports

pub use push_right as push;

pub use pop_right as pop;

pub use push_left as unshift;

pub use pop_left as shift;

Functions

concat

Concatenates the given array a with the given other array b. Returns a new array which contains all elements from a and b. No elements are dropped, copied or cloned.

pop_left

Identical to pop_right, but pops from the left of the array instead.

pop_right

Pops one element from the end of the given array a, returning the rest of the array and the popped element in a tuple. No elements are dropped, copied or cloned.

push_left

Extends the given element b by the given array a. Returns a new array which is the direct extension of a by b. No elements are dropped, copied or cloned.

push_right

Extends the given array a by the given element b. Returns a new array which is the direct extension of a by b. No elements are dropped, copied or cloned.

split

Splits the given array a at the given point M. Returns a tuple containing two arrays where the first element is an array containing all elements from a[..M] and the second element is an array containing all elements from a[M..]. No elements are dropped, copied or cloned.

split_end

Identical to split, but splits starting from the end of the array, to hopefully help with compiler proofs (in cases like pop_right).