Struct ByteArray 

pub struct ByteArray<const N: usize>(/* private fields */);

A fixed size byte slice.

Internally this is just a wrapper around [Bytes], with the constructors checking that the length is equal to N. This implements Deref with the target being [u8; N].

Implementations

impl<const N: usize> ByteArray<N>

pub fn take_bytes(self) -> Bytes

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

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");

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.

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]);

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));

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

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

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);

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, &[]);
}

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

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

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

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

type Target = [u8; N]

The resulting type after dereferencing.

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

Dereferences the value.

impl<'de, const N: usize> Deserialize<'de> for ByteArray<N>

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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

impl<const N: usize> From<[u8; N]> for ByteArray<N>

fn from(value: [u8; N]) -> Self

Converts to this type from the input type.

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

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

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

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

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

Restrict a value to a certain range.

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

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

Equality operator ==.

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

Inequality operator !=.

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

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

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

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

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

impl<const N: usize> TryFrom<Bytes> for ByteArray<N>

type Error = FixedByteError

The type returned in the event of a conversion error.

fn try_from(value: Bytes) -> Result<Self, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<Vec<u8>> for ByteArray<N>

type Error = FixedByteError

The type returned in the event of a conversion error.

fn try_from(value: Vec<u8>) -> Result<Self, Self::Error>

Performs the conversion.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 32 bytes