Trait Array

Source

pub unsafe trait Array: Sized {
    type Item;
    type Maybe: Array<Item = MaybeUninit<Self::Item>>;

    const SIZE: usize;

    // Required methods
    fn as_slice(&self) -> &[Self::Item];
    fn as_mut_slice(&mut self) -> &mut [Self::Item];
    fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
       where F: FnMut(&mut St) -> Result<Self::Item, E>;
    fn unfold<St, F>(init: St, f: F) -> Self
       where F: FnMut(&mut St) -> Self::Item;
    fn try_from_fn<F, E>(f: F) -> Result<Self, E>
       where F: FnMut(usize) -> Result<Self::Item, E>;
    fn from_fn<F>(f: F) -> Self
       where F: FnMut(usize) -> Self::Item;
    fn try_from_iter<I>(iter: I) -> Option<Self>
       where I: IntoIterator<Item = Self::Item>;
    fn into_boxed_slice(self) -> Box<[Self::Item]>;

    // Provided methods
    fn from_iter<I>(iter: I) -> Self
       where I: IntoIterator<Item = Self::Item> { ... }
    fn into_uninit(self) -> Self::Maybe { ... }
    fn uninit() -> Self::Maybe { ... }
    unsafe fn assume_init(uninit: Self::Maybe) -> Self { ... }
}

Expand description

Represent array of some size. E.g.: [u8; 32], [&str; 8], [T; N].

§Sizes

See Sizes Limitations paragraph in crate docs.

§Safety

By implementing this trait for type T you guarantee that

T has the same ABI as [T::Item; T::Size]
T::Maybe is an array of the same type ([MeybeUninit<T::Item>; T::Size])

Violating these rules will cause UB.

It is highly not recommended to implement this trait on your type unless you really know what you are doing.

Required Associated Constants§

Source

const SIZE: usize

Size of the array.

§Example

use arraylib::Array;

assert_eq!(<[(); 0]>::SIZE, 0);
assert_eq!(<[(); 2]>::SIZE, 2);

Required Associated Types§

Source

type Item

Type of the Items in the array. i.e.

[T; 4]: Array<Item = T>

Source

type Maybe: Array<Item = MaybeUninit<Self::Item>>

Same array but item is wrapped with MaybeUninit<_>.

[T; 4]: Array<Item = T, Maybe = [core::mem::MaybeUninit<T>; 4]>

Required Methods§

Source

fn as_slice(&self) -> &[Self::Item]

Extracts a slice containing the entire array.

§Example

use arraylib::Array;

let array = [1, 2, 3];
assert_eq!(array.as_slice()[1..], [2, 3]);

Source

fn as_mut_slice(&mut self) -> &mut [Self::Item]

Extracts a mutable slice of the entire array.

§Example

use arraylib::Array;

let mut array = [1, 0, 1];
array.as_mut_slice()[1] = 2;
assert_eq!(array, [1, 2, 1]);

Source

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

Create new array, filled with elements returned by f. If f return Err then this method also return Err.

§Example

use arraylib::Array;

let f = |it: &mut u32| {
    let res = Ok(*it);
    *it = it.checked_sub(10).ok_or(())?;
    res
};

let arr = <[_; 3]>::try_unfold(30, f);
assert_eq!(arr, Ok([30, 20, 10]));

let arr = <[_; 10]>::try_unfold(40, f);
assert_eq!(arr, Err(()));

Source

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

Create new array, filled with elements returned by f

§Example

use arraylib::Array;

let arr = <[_; 11]>::unfold(1, |it| {
    let res = *it;
    *it *= -2;
    res
});
assert_eq!(arr, [1, -2, 4, -8, 16, -32, 64, -128, 256, -512, 1024]);

Source

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

Create new array, filled with elements returned by f. If f return Err then this method also return Err.

§Example

use arraylib::Array;

let f = |it| 250u8.checked_add(it as u8).ok_or(());

let arr = <[_; 3]>::try_from_fn(f);
assert_eq!(arr, Ok([250, 251, 252]));

let arr = <[_; 10]>::try_from_fn(f);
assert_eq!(arr, Err(()));

Source

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

Create new array, filled with elements returned by f

§Example

use arraylib::Array;

let arr = <[_; 11]>::from_fn(|it| it.pow(2));
assert_eq!(arr, [0, 1, 4, 9, 16, 25, 36, 49, 64, 81, 100]);

Source

fn try_from_iter(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

Creates an array from an iterator.

This method returns None if there are not enough elements to fill the array.

§Examples

use arraylib::{Array, ArrayExt};
use std::iter::once;

let iter = [-2, -1, 0, 1, 2].iter_move().filter(|it| it % 2 == 0);
let arr = <[i32; 2]>::try_from_iter(iter);
assert_eq!(arr, Some([-2, 0]));

let arr = <[i32; 2]>::try_from_iter(once(0));
assert_eq!(arr, None);

Source

fn into_boxed_slice(self) -> Box<[Self::Item]>

Available on crate feature alloc only.

Converts self into Box<[Self::Item]>

Provided Methods§

Source

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

Creates an array from an iterator.

§Examples

use arraylib::{Array, ArrayExt};

let iter = [-2, -1, 0, 1, 2].iter_move().filter(|it| it % 2 == 0);
let arr = <[i32; 2]>::from_iter(iter);

assert_eq!(arr, [-2, 0]);

§Panics

If there are not enough elements to fill the array:

use arraylib::Array;
use std::iter::once;

let _ = <[i32; 2]>::from_iter(once(0));

Source

fn into_uninit(self) -> Self::Maybe

Converts self into [MaybeUninit<Self::Item>; Self::Size]. This function is used internally in this crate for some unsafe code.

§Example

use arraylib::Array;
use std::mem::MaybeUninit;

let _: [MaybeUninit<bool>; 3] = [true, false, false].into_uninit();

Source

fn uninit() -> Self::Maybe

Creates uninitialized array of MaybeUninit<T>.

§Example

use arraylib::Array;
use std::mem::MaybeUninit;

let _: [MaybeUninit<i32>; 3] = <[i32; 3]>::uninit();

Source

unsafe fn assume_init(uninit: Self::Maybe) -> Self

Extracts the values from the MaybeUninit<T> containers.

§Safety

It is up to the caller to guarantee that all elements of the array are really in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior. The MaybeUninit's type-level documentation contains more information about this initialization invariant.

See also MaybeUninit::assume_init documentation.

§Examples

Correct usage of this method:

use arraylib::Array;
use std::mem::MaybeUninit;

let mut arr: [MaybeUninit<bool>; 4] = <[bool; 4]>::uninit();
for x in arr.iter_mut() {
    unsafe { x.as_mut_ptr().write(true) };
}

let arr_init: [bool; 4] = unsafe { <_>::assume_init(arr) };
assert_eq!(arr_init, [true; 4]);

Incorrect usage of this method:

use arraylib::Array;
use std::mem::MaybeUninit;

let mut arr: [MaybeUninit<bool>; 4] = <[bool; 4]>::uninit();
for i in 0..3 {
    unsafe { arr[i].as_mut_ptr().write(true) };
}

let arr_init: [bool; 4] = unsafe { <_>::assume_init(arr) };
// `arr[3]` had not been initialized yet, so this last line caused undefined behavior.

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.

Trait ArrayCopy item path

§Sizes

§Safety

Required Associated Constants§

const SIZE: usize

§Example

Required Associated Types§

type Item

type Maybe: Array<Item = MaybeUninit<Self::Item>>

Required Methods§

fn as_slice(&self) -> &[Self::Item]

§Example

fn as_mut_slice(&mut self) -> &mut [Self::Item]

§Example

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>where F: FnMut(&mut St) -> Result<Self::Item, E>,

§Example

fn unfold<St, F>(init: St, f: F) -> Selfwhere F: FnMut(&mut St) -> Self::Item,

§Example

fn try_from_fn<F, E>(f: F) -> Result<Self, E>where F: FnMut(usize) -> Result<Self::Item, E>,

§Example

fn from_fn<F>(f: F) -> Selfwhere F: FnMut(usize) -> Self::Item,

§Example

fn try_from_iter<I>(iter: I) -> Option<Self>where I: IntoIterator<Item = Self::Item>,

§Examples

fn into_boxed_slice(self) -> Box<[Self::Item]>

Provided Methods§

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

§Examples

§Panics

fn into_uninit(self) -> Self::Maybe

§Example

fn uninit() -> Self::Maybe

§Example

unsafe fn assume_init(uninit: Self::Maybe) -> Self

§Safety

§Examples

Dyn Compatibility§

Implementations on Foreign Types§

impl<T> Array for [T; 0]

const SIZE: usize = 0usize

type Item = T

type Maybe = [MaybeUninit<T>; 0]

fn into_boxed_slice(self) -> Box<[Self::Item]>

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

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

fn try_unfold<St, F, E>(_init: St, _f: F) -> Result<Self, E>where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(_init: St, _f: F) -> Selfwhere F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(_f: F) -> Result<Self, E>where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(_f: F) -> Selfwhere F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(_iter: I) -> Option<Self>where I: IntoIterator<Item = Self::Item>,

fn into_uninit(self) -> Self::Maybe

impl<T> Array for [T; 1]

const SIZE: usize = 1usize

type Item = T

type Maybe = [MaybeUninit<T>; 1]

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

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

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Selfwhere F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Selfwhere F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>where I: IntoIterator<Item = Self::Item>,

fn into_boxed_slice(self) -> Box<[Self::Item]>

impl<T> Array for [T; 2]

const SIZE: usize = 2usize

type Item = T

type Maybe = [MaybeUninit<T>; 2]

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

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

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Selfwhere F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Selfwhere F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>where I: IntoIterator<Item = Self::Item>,

fn into_boxed_slice(self) -> Box<[Self::Item]>

impl<T> Array for [T; 3]

const SIZE: usize = 3usize

type Item = T

type Maybe = [MaybeUninit<T>; 3]

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

Trait Array

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

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

fn try_unfold<St, F, E>(_init: St, _f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(_init: St, _f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(_f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(_f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(_iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,

fn try_unfold<St, F, E>(init: St, f: F) -> Result<Self, E>
where F: FnMut(&mut St) -> Result<Self::Item, E>,

fn unfold<St, F>(init: St, f: F) -> Self
where F: FnMut(&mut St) -> Self::Item,

fn try_from_fn<F, E>(f: F) -> Result<Self, E>
where F: FnMut(usize) -> Result<Self::Item, E>,

fn from_fn<F>(f: F) -> Self
where F: FnMut(usize) -> Self::Item,

fn try_from_iter<I>(iter: I) -> Option<Self>
where I: IntoIterator<Item = Self::Item>,