Struct HexArray

Source

pub struct HexArray<const N: usize>(pub [u8; N]);

Available on crate feature hex only.

Expand description

A byte array that displays and parses as hex.

HexArray<N> wraps [u8; N], providing Display, FromStr, LowerHex, and UpperHex implementations that use hexadecimal encoding.

With the serde feature enabled, it also implements Serialize and Deserialize (hex strings in human-readable formats, raw bytes in binary formats), and can be used with #[serde(with = "HexArray::<N>")] on [u8; N] fields.

§Examples

use byte_wrapper::HexArray;

let h = HexArray::new([0x01, 0x02, 0xab, 0xff]);
assert_eq!(h.to_string(), "0102abff");

let parsed: HexArray<4> = "0102abff".parse().unwrap();
assert_eq!(parsed, h);

Tuple Fields§

§0: [u8; N]

Implementations§

Source §

impl<const N: usize> HexArray<N>

Source

pub fn serialize<S>(bytes: &[u8; N], serializer: S) -> Result<S::Ok, S::Error>
where S: Serializer,

Available on crate feature serde only.

Serializes a byte array as hex in human-readable formats, or as raw bytes otherwise.

Intended for use with #[serde(with = "HexArray::<N>")].

§Examples

use byte_wrapper::HexArray;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Record {
    #[serde(with = "HexArray::<4>")]
    id: [u8; 4],
}

let r = Record { id: [0x01, 0x02, 0x03, 0x04] };
let json = serde_json::to_string(&r).unwrap();
assert_eq!(json, r#"{"id":"01020304"}"#);

Source

pub fn deserialize<'de, D>(deserializer: D) -> Result<[u8; N], D::Error>
where D: Deserializer<'de>,

Available on crate feature serde only.

Deserializes a byte array from hex if the format is human-readable, or as raw bytes otherwise.

Intended for use with #[serde(with = "HexArray::<N>")].

§Examples

use byte_wrapper::HexArray;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Record {
    #[serde(with = "HexArray::<4>")]
    id: [u8; 4],
}

let r: Record = serde_json::from_str(r#"{"id":"01020304"}"#).unwrap();
assert_eq!(r.id, [0x01, 0x02, 0x03, 0x04]);

Source §

impl<const N: usize> HexArray<N>

Source

pub const fn new(bytes: [u8; N]) -> Self

Creates a new HexArray from a byte array.

Source

pub const fn into_inner(self) -> [u8; N]

Returns the inner byte array.

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.57.0 · Source

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

Returns a mutable slice containing the entire array. Equivalent to &mut 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);

1.77.0 · Source

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

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

§Example


let mut floats = [3.1, 2.7, -1.0];
let float_refs: [&mut f64; 3] = floats.each_mut();
*float_refs[0] = 0.0;
assert_eq!(float_refs, [&mut 0.0, &mut 2.7, &mut -1.0]);
assert_eq!(floats, [0.0, 2.7, -1.0]);

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 split_array_mut<const M: usize>(&mut self) -> (&mut [T; M], &mut [T])

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

Divides one mutable 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 mut v = [1, 0, 3, 0, 5, 6];
let (left, right) = v.split_array_mut::<2>();
assert_eq!(left, &mut [1, 0][..]);
assert_eq!(right, &mut [3, 0, 5, 6]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);

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

Source

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

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

Divides one mutable 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 mut v = [1, 0, 3, 0, 5, 6];
let (left, right) = v.rsplit_array_mut::<4>();
assert_eq!(left, &mut [1, 0]);
assert_eq!(right, &mut [3, 0, 5, 6][..]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);