Trait ArrayExt

pub trait ArrayExt: Array {
    // Provided methods
    fn iter_move(self) -> IterMove<Self>  { ... }
    fn concat_arr<A, R>(self, other: A) -> R
       where A: Array<Item = Self::Item>,
             R: Array<Item = Self::Item> { ... }
    fn split_arr<A, B>(self) -> (A, B)
       where A: Array<Item = Self::Item>,
             B: Array<Item = Self::Item> { ... }
    fn into_array<A>(self) -> Result<A, Self>
       where A: Array<Item = Self::Item> { ... }
    fn to_vec(&self) -> Vec<Self::Item>
       where Self::Item: Clone { ... }
    fn into_vec(self) -> Vec<Self::Item> { ... }
    fn from_slice(slice: &[Self::Item]) -> Result<Self, SizeError>
       where Self::Item: Copy { ... }
    fn clone_from_slice(slice: &[Self::Item]) -> Result<Self, SizeError>
       where Self::Item: Clone { ... }
    fn wrap(self) -> ArrayWrapper<Self> { ... }
    fn ref_cast(slice: &[Self::Item]) -> &Self { ... }
    fn mut_cast(slice: &mut [Self::Item]) -> &mut Self { ... }
    fn try_ref_cast(slice: &[Self::Item]) -> Result<&Self, &[Self::Item]> { ... }
    fn try_mut_cast(
        slice: &mut [Self::Item],
    ) -> Result<&mut Self, &mut [Self::Item]> { ... }
    unsafe fn ref_cast_unchecked(slice: &[Self::Item]) -> &Self { ... }
    unsafe fn mut_cast_unchecked(slice: &mut [Self::Item]) -> &mut Self { ... }
}

Extension on arrays that provide additional functions.

Provided Methods

fn iter_move(self) -> IterMove<Self>

Creates iterator which moves elements out of array.

See also: IterMove

fn concat_arr<A, R>(self, other: A) -> R

where A: Array<Item = Self::Item>, R: Array<Item = Self::Item>,

Example

use arraylib::ArrayExt;

let arr: [_; 6] = [1, 2, 3].concat_arr([4, 5, 6]);
assert_eq!(arr, [1, 2, 3, 4, 5, 6])

Panics

Panics if Self::SIZE + A::SIZE != R::SIZE:

use arraylib::ArrayExt;

let arr: [_; 4] = [1, 2, 3].concat_arr([4, 5, 6]);

fn split_arr<A, B>(self) -> (A, B)

where A: Array<Item = Self::Item>, B: Array<Item = Self::Item>,

Splits self into 2 arrays

Example

use arraylib::ArrayExt;

let arr = [1, 2, 3, 4, 5];
let (head, tail) = arr.split_arr::<[_; 2], [_; 3]>();

assert_eq!(head, [1, 2]);
assert_eq!(tail, [3, 4, 5]);

fn into_array<A>(self) -> Result<A, Self>

where A: Array<Item = Self::Item>,

Converts self into an array. This function will return Some(_) if sizes of Self and A are the same and None otherwise.

Example

use arraylib::{Array, ArrayExt};

fn function_optimized_for_8(_: [i32; 8]) {
    /* ... */
}

fn general<A>(array: A)
where
    A: Array<Item = i32>,
{
    match array.into_array::<[i32; 8]>() {
        Ok(array) => function_optimized_for_8(array),
        Err(array) => { /* here `array` is of type `A` */ },
    }
}

fn to_vec(&self) -> Vec<Self::Item>

where Self::Item: Clone,

Available on crate feature alloc only.

Copies self into a new Vec.

Examples

use arraylib::{Array, ArrayExt};

fn generic<A>(arr: A)
where
    A: Array,
    A::Item: Clone,
{
    let x = arr.to_vec();
    // Here, `arr` and `x` can be modified independently.
}

See also: [T]::to_vec

fn into_vec(self) -> Vec<Self::Item>

Available on crate feature alloc only.

Converts self into a vector without clones.

The resulting vector can be converted back into a box via Vec<T>’s into_boxed_slice method.

Examples

use arraylib::ArrayExt;

let s = [10, 40, 30];
let x = s.into_vec();
// `s` cannot be used anymore because it has been converted into `x`.

assert_eq!(x, vec![10, 40, 30]);

See also: [T]::in to_vec

fn from_slice(slice: &[Self::Item]) -> Result<Self, SizeError>

where Self::Item: Copy,

Create array from slice. Return Err(()) if slice.len != Self::SIZE.

Examples

use arraylib::ArrayExt;

let slice = &[1, 2, 3];
let arr = <[i32; 3]>::from_slice(slice);
assert_eq!(arr, Ok([1, 2, 3]));

let slice = &[1, 2, 3, 4];
let arr = <[i32; 2]>::from_slice(slice);
//          ^^^^^^ ---- wrong size, slice len = 4, arr len = 2
assert_eq!(arr, Err(SizeError::default()));

fn clone_from_slice(slice: &[Self::Item]) -> Result<Self, SizeError>

where Self::Item: Clone,

Create array from slice. Return Err(()) if slice.len != Self::SIZE.

Same as from_slice, but doesn’t require items to be Copy, instead only require elements to be Clone

Examples

use arraylib::ArrayExt;

let slice = &[String::from("hi"), 123.to_string(), String::new()];
let arr = <[String; 3]>::clone_from_slice(slice);
assert_eq!(
    arr,
    Ok([String::from("hi"), 123.to_string(), String::new()])
);

fn wrap(self) -> ArrayWrapper<Self>

Wrap self into ArrayWrapper

fn ref_cast(slice: &[Self::Item]) -> &Self

Safely cast &[T] to &Self ([T; N])

Panics

Panics if size of slice is less than size of Self.

Examples

use arraylib::ArrayExt;

let vec = vec![1, 0, 2, 14];
assert_eq!(<[i32; 4]>::ref_cast(&vec[..]), &[1, 0, 2, 14]);

// panics
<[i32; 4]>::ref_cast(&[1, 2][..]);

fn mut_cast(slice: &mut [Self::Item]) -> &mut Self

Safely cast &mut [T] to &mut Self ([T; N])

Panics

Panics if size of slice is less than size of Self.

Examples

use arraylib::{ArrayExt, SizeError};

let mut vec = vec![1, 0, 2, 14];
assert_eq!(<[i32; 4]>::mut_cast(&mut vec[..]), &mut [1, 0, 2, 14]);

// panics
<[i32; 4]>::mut_cast(&mut [1, 2][..]);

fn try_ref_cast(slice: &[Self::Item]) -> Result<&Self, &[Self::Item]>

Safely cast &[T] to &Self ([T; N])

Errors

If size of slice is less than size of Self, then an error is returned.

Examples

use arraylib::{ArrayExt, SizeError};

let vec = vec![1, 0, 2, 14];
assert_eq!(<[i32; 4]>::try_ref_cast(&vec[..]), Ok(&[1, 0, 2, 14]));
assert_eq!(<[i32; 4]>::try_ref_cast(&vec[1..=2]), Err(&[0, 2][..]));

fn try_mut_cast( slice: &mut [Self::Item], ) -> Result<&mut Self, &mut [Self::Item]>

Safely cast &mut [T] to &mut Self ([T; N])

Errors

If size of slice is less than size of Self, then an error is returned.

Examples

use arraylib::{ArrayExt, SizeError};

let mut vec = vec![1, 0, 2, 14];
assert_eq!(
    <[i32; 4]>::try_mut_cast(&mut vec[..]),
    Ok(&mut [1, 0, 2, 14])
);
assert_eq!(
    <[i32; 4]>::try_mut_cast(&mut vec[1..=2]),
    Err(&mut [0, 2][..])
);

unsafe fn ref_cast_unchecked(slice: &[Self::Item]) -> &Self

Unsafety cast &[T] to &Self ([T; N])

Safety

To safely call this function you need to ensure that size of slice is not less than the size of array: slice.len() >= Self::SIZE

Examples

ok usage:

use arraylib::ArrayExt;

let vec = vec![1, 0, 2, 14];

let _: &[i32; 4] = unsafe {
    // Safe because we know that size of `vec` is equal 4
    <[i32; 4]>::ref_cast_unchecked(&vec[..])
};

wrong (UB) usage:

use arraylib::ArrayExt;

let vec = vec![1, 0, 2, 14];

let _: &[i32; 4] = unsafe {
    // size of slice borrowed from `vec` is not equal to 4 so this is UB
    <[i32; 4]>::ref_cast_unchecked(&vec[1..])
};

unsafe fn mut_cast_unchecked(slice: &mut [Self::Item]) -> &mut Self

Unsafety cast &mut [T] to &mut Self ([T; N])

Safety

To safely call this function you need to ensure that size of slice is not less than the size of array: slice.len() >= Self::SIZE

Examples

ok usage:

use arraylib::ArrayExt;

let mut vec = vec![1, 0, 2, 14];

let _: &[i32; 4] = unsafe {
    // Safe because we know that size of `vec` is equal 4
    <[i32; 4]>::ref_cast_unchecked(&mut vec[..])
};

wrong (UB) usage:

use arraylib::ArrayExt;

let mut vec = vec![1, 0, 2, 14];

let _: &[i32; 4] = unsafe {
    // size of slice borrowed from `vec` is not equal to 4 so this is UB
    <[i32; 4]>::ref_cast_unchecked(&mut vec[1..])
};

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.

Implementors

impl<A> ArrayExt for A

where A: Array,