Skip to main content

ByteArray

Struct ByteArray 

Source
pub struct ByteArray<const N: usize>(pub [u8; N]);
Expand description

A fixed-size byte array.

Tuple Fields§

§0: [u8; N]

Methods from Deref<Target = [u8; N]>§

Source

pub fn as_ascii(&self) -> Option<&[AsciiChar; N]>

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

Converts this array of bytes into an array of ASCII characters, or returns None if any of the characters is non-ASCII.

§Examples
#![feature(ascii_char)]

const HEX_DIGITS: [std::ascii::Char; 16] =
    *b"0123456789abcdef".as_ascii().unwrap();

assert_eq!(HEX_DIGITS[1].as_str(), "1");
assert_eq!(HEX_DIGITS[10].as_str(), "a");
Source

pub unsafe fn as_ascii_unchecked(&self) -> &[AsciiChar; N]

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

Converts this array of bytes into an array of ASCII characters, without checking whether they’re valid.

§Safety

Every byte in the array must be in 0..=127, or else this is UB.

1.55.0 · Source

pub fn map<F, U>(self, f: F) -> [U; N]
where F: FnMut(T) -> U,

Returns an array of the same size as self, with function f applied to each element in order.

If you don’t necessarily need a new fixed-size array, consider using Iterator::map instead.

§Note on performance and stack usage

Note that this method is eager. It evaluates f all N times before returning the new array.

That means that arr.map(f).map(g) is, in general, not equivalent to array.map(|x| g(f(x))), as the former calls f 4 times then g 4 times, whereas the latter interleaves the calls (fgfgfgfg).

A consequence of this is that it can have fairly-high stack usage, especially in debug mode or for long arrays. The backend may be able to optimize it away, but especially for complicated mappings it might not be able to.

If you’re doing a one-step map and really want an array as the result, then absolutely use this method. Its implementation uses a bunch of tricks to help the optimizer handle it well. Particularly for simple arrays, like [u8; 3] or [f32; 4], there’s nothing to be concerned about.

However, if you don’t actually need an array of the results specifically, just to process them, then you likely want Iterator::map instead.

For example, rather than doing an array-to-array map of all the elements in the array up-front and only iterating after that completes,

for x in my_array.map(f) {
    // ...
}

It’s often better to use an iterator along the lines of

for x in my_array.into_iter().map(f) {
    // ...
}

as that’s more likely to avoid large temporaries.

§Examples
let x = [1, 2, 3];
let y = x.map(|v| v + 1);
assert_eq!(y, [2, 3, 4]);

let x = [1, 2, 3];
let mut temp = 0;
let y = x.map(|v| { temp += 1; v * temp });
assert_eq!(y, [1, 4, 9]);

let x = ["Ferris", "Bueller's", "Day", "Off"];
let y = x.map(|v| v.len());
assert_eq!(y, [6, 9, 3, 3]);
Source

pub fn try_map<R>( self, f: impl FnMut(T) -> R, ) -> <<R as Try>::Residual as Residual<[<R as Try>::Output; N]>>::TryType
where R: Try, <R as Try>::Residual: Residual<[<R as Try>::Output; N]>,

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

A fallible function f applied to each element on array self in order to return an array the same size as self or the first error encountered.

The return type of this function depends on the return type of the closure. If you return Result<T, E> from the closure, you’ll get a Result<[T; N], E>. If you return Option<T> from the closure, you’ll get an Option<[T; N]>.

§Examples
#![feature(array_try_map)]

let a = ["1", "2", "3"];
let b = a.try_map(|v| v.parse::<u32>()).unwrap().map(|v| v + 1);
assert_eq!(b, [2, 3, 4]);

let a = ["1", "2a", "3"];
let b = a.try_map(|v| v.parse::<u32>());
assert!(b.is_err());

use std::num::NonZero;

let z = [1, 2, 0, 3, 4];
assert_eq!(z.try_map(NonZero::new), None);

let a = [1, 2, 3];
let b = a.try_map(NonZero::new);
let c = b.map(|x| x.map(NonZero::get));
assert_eq!(c, Some(a));
1.57.0 · Source

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

Returns a slice containing the entire array. Equivalent to &s[..].

1.77.0 · Source

pub fn each_ref(&self) -> [&T; N]

Borrows each element and returns an array of references with the same size as self.

§Example
let floats = [3.1, 2.7, -1.0];
let float_refs: [&f64; 3] = floats.each_ref();
assert_eq!(float_refs, [&3.1, &2.7, &-1.0]);

This method is particularly useful if combined with other methods, like map. This way, you can avoid moving the original array if its elements are not Copy.

let strings = ["Ferris".to_string(), "♥".to_string(), "Rust".to_string()];
let is_ascii = strings.each_ref().map(|s| s.is_ascii());
assert_eq!(is_ascii, [true, false, true]);

// We can still access the original array: it has not been moved.
assert_eq!(strings.len(), 3);
Source

pub fn split_array_ref<const M: usize>(&self) -> (&[T; M], &[T])

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

Divides one array reference into two at an index.

The first will contain all indices from [0, M) (excluding the index M itself) and the second will contain all indices from [M, N) (excluding the index N itself).

§Panics

Panics if M > N.

§Examples
#![feature(split_array)]

let v = [1, 2, 3, 4, 5, 6];

{
   let (left, right) = v.split_array_ref::<0>();
   assert_eq!(left, &[]);
   assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
}

{
    let (left, right) = v.split_array_ref::<2>();
    assert_eq!(left, &[1, 2]);
    assert_eq!(right, &[3, 4, 5, 6]);
}

{
    let (left, right) = v.split_array_ref::<6>();
    assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
    assert_eq!(right, &[]);
}
Source

pub fn rsplit_array_ref<const M: usize>(&self) -> (&[T], &[T; M])

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

Divides one array reference into two at an index from the end.

The first will contain all indices from [0, N - M) (excluding the index N - M itself) and the second will contain all indices from [N - M, N) (excluding the index N itself).

§Panics

Panics if M > N.

§Examples
#![feature(split_array)]

let v = [1, 2, 3, 4, 5, 6];

{
   let (left, right) = v.rsplit_array_ref::<0>();
   assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
   assert_eq!(right, &[]);
}

{
    let (left, right) = v.rsplit_array_ref::<2>();
    assert_eq!(left, &[1, 2, 3, 4]);
    assert_eq!(right, &[5, 6]);
}

{
    let (left, right) = v.rsplit_array_ref::<6>();
    assert_eq!(left, &[]);
    assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
}

Trait Implementations§

Source§

impl<const N: usize> Clone for ByteArray<N>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<const N: usize> Copy for ByteArray<N>

Source§

impl<const N: usize> Debug for ByteArray<N>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<const N: usize> Deref for ByteArray<N>

Source§

type Target = [u8; N]

The resulting type after dereferencing.
Source§

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

Dereferences the value.
Source§

impl<const N: usize> Eq for ByteArray<N>

Source§

impl<const N: usize> PartialEq for ByteArray<N>

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl<const N: usize> StructuralPartialEq for ByteArray<N>

Source§

impl<'a, const N: usize, C: Default> TryRead<'a, C> for ByteArray<N>

Source§

fn try_read(bytes: &'a [u8], _: C) -> Result<(Self, usize), Error>

Try to read from a byte slice using a specific context. Read more
Source§

impl<const N: usize, C: Default> TryWrite<C> for ByteArray<N>

Source§

fn try_write(self, bytes: &mut [u8], _: C) -> Result<usize, Error>

Try to write to a byte slice using a specific context. Read more

Auto Trait Implementations§

§

impl<const N: usize> Freeze for ByteArray<N>
where [u8; N]: Freeze,

§

impl<const N: usize> RefUnwindSafe for ByteArray<N>
where [u8; N]: RefUnwindSafe,

§

impl<const N: usize> Send for ByteArray<N>
where [u8; N]: Send,

§

impl<const N: usize> Sync for ByteArray<N>
where [u8; N]: Sync,

§

impl<const N: usize> Unpin for ByteArray<N>
where [u8; N]: Unpin,

§

impl<const N: usize> UnsafeUnpin for ByteArray<N>
where [u8; N]: UnsafeUnpin,

§

impl<const N: usize> UnwindSafe for ByteArray<N>
where [u8; N]: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

type Target = T

🔬This is a nightly-only experimental API. (arbitrary_self_types)
The target type on which the method may be called.
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.