Bytemuck

https://docs.rs/bytemuck/latest
Admin
Bytemuck is a Rust crate that provides utilities for safely casting between plain data types while...
Tokens:91,412
Snippets:738
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Pod derive examples

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.Pod.html

Examples of structs deriving Pod with repr(C) and repr(transparent) attributes.

```rust
#[derive(Copy, Clone, Pod, Zeroable)]
#[repr(C)]
struct Test {
  a: u16,
  b: u16,
}

#[derive(Copy, Clone, Pod, Zeroable)]
#[repr(transparent)]
struct Generic<A, B> {
  a: A,
  b: PhantomData<B>,
}
```

--------------------------------

### Zeroable Custom Bounds Examples

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.Zeroable.html

Examples demonstrating the use of custom bounds and perfect derive semantics for generic types.

```rust
#[derive(Clone, Zeroable)]
#[zeroable(bound = "")]
struct AlwaysZeroable<T> {
  a: PhantomData<T>,
}

AlwaysZeroable::<std::num::NonZeroU8>::zeroed();
```

```rust
#[derive(Copy, Clone, Zeroable)]
#[repr(u8)]
#[zeroable(bound = "")]
enum MyOption<T> {
  None,
  Some(T),
}

assert!(matches!(MyOption::<std::num::NonZeroU8>::zeroed(), MyOption::None));
```

```rust
#[derive(Clone, Zeroable)]
#[zeroable(bound = "T: Copy")]
struct ZeroableWhenTIsCopy<T> {
  a: PhantomData<T>,
}

ZeroableWhenTIsCopy::<String>::zeroed();
```

```rust
#[derive(Clone, Zeroable)]
#[zeroable(bound = "")]
struct ZeroableWhenTIsZeroable<T> {
  a: T,
}
ZeroableWhenTIsZeroable::<u32>::zeroed();
```

```rust
ZeroableWhenTIsZeroable::<String>::zeroed();
```

--------------------------------

### Zeroable Derive Examples

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.Zeroable.html

Examples of deriving Zeroable for a struct and various enum configurations.

```rust
#[derive(Copy, Clone, Zeroable)]
#[repr(C)]
struct Test {
  a: u16,
  b: u16,
}
```

```rust
#[derive(Copy, Clone, Zeroable)]
#[repr(i32)]
enum Values {
  A = 0,
  B = 1,
  C = 2,
}
#[derive(Clone, Zeroable)]
#[repr(C)]
enum Implicit {
  A(bool, u8, char),
  B(String),
  C(std::num::NonZeroU8),
}
```

--------------------------------

### Basic ByteHash usage

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.ByteHash.html

Example of deriving ByteHash on a simple struct with repr(C).

```rust
#[derive(Copy, Clone, NoUninit, ByteHash)]
#[repr(C)]
struct Test {
  a: u32,
  b: char,
  c: f32,
}
```

--------------------------------

### Basic ByteEq usage

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.ByteEq.html

A simple example of deriving ByteEq on a struct with a C representation.

```rust
#[derive(Copy, Clone, NoUninit, ByteEq)]
#[repr(C)]
struct Test {
  a: u32,
  b: char,
  c: f32,
}
```

--------------------------------

### Partitioning a slice

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Examples demonstrating how to use partition_point to find split indices or insert elements into sorted collections.

```rust
assert_eq!(i, 4);
assert!(v[..i].iter().all(|&x| x < 5));
assert!(v[i..].iter().all(|&x| !(x < 5)));
```

```rust
let a = [2, 4, 8];
assert_eq!(a.partition_point(|x| x < &100), a.len());
let a: [i32; 0] = [];
assert_eq!(a.partition_point(|x| x < &100), 0);
```

```rust
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = 42;
let idx = s.partition_point(|&x| x <= num);
s.insert(idx, num);
assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);
```

--------------------------------

### Sort a slice

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Basic example of sorting a mutable slice of integers.

```rust
let mut v = [4, -5, 1, -3, 2];
```

--------------------------------

### Successful slice casting examples

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.must_cast_slice.html

Demonstrates valid conversions between slice types that satisfy alignment and size requirements.

```rust
let indicies: &[u16] = &[1, 2, 3];
// compiles:
let bytes: &[u8] = bytemuck::must_cast_slice(indicies);
```

```rust
let zsts: &[()] = &[(), (), ()];
// compiles:
let bytes: &[u8] = bytemuck::must_cast_slice(zsts);
```

--------------------------------

### Deriving TransparentWrapper

Source: https://docs.rs/bytemuck/latest/bytemuck/trait.TransparentWrapper.html

Examples of deriving TransparentWrapper, including a case that fails due to missing Zeroable implementation.

```rust
use bytemuck::TransparentWrapper;
use std::marker::PhantomData;

#[derive(TransparentWrapper)]
#[repr(transparent)]
#[transparent(usize)]
struct Wrapper<T: ?Sized>(usize, PhantomData<T>); // PhantomData<T> implements Zeroable for all T
```

```rust
use bytemuck::TransparentWrapper;
struct MyZst;

#[derive(TransparentWrapper)]
#[repr(transparent)]
#[transparent(usize)]
struct Wrapper(usize, MyZst); // MyZst does not implement Zeroable
```

--------------------------------

### Mutable slice casting examples

Source: https://docs.rs/bytemuck/latest/src/bytemuck/must.rs.html

Demonstrations of successful and failing mutable slice casts using must_cast_slice_mut.

```rust
let mut indicies = [1, 2, 3];
let indicies: &mut [u16] = &mut indicies;
// compiles:
let bytes: &mut [u8] = bytemuck::must_cast_slice_mut(indicies);
```

```rust
let zsts: &mut [()] = &mut [(), (), ()];
// compiles:
let bytes: &mut [u8] = bytemuck::must_cast_slice_mut(zsts);
```

```rust
# let mut bytes = [1, 0, 2, 0, 3, 0];
# let bytes : &mut [u8] = &mut bytes[..];
// fails to compile (bytes.len() might not be a multiple of 2):
let byte_pairs : &mut [[u8; 2]] = bytemuck::must_cast_slice_mut(bytes);
```

```rust
# let mut byte_pairs = [[1, 0], [2, 0], [3, 0]];
# let byte_pairs : &mut [[u8; 2]] = &mut byte_pairs[..];
// fails to compile (alignment requirements increased):
let indicies : &mut [u16] = bytemuck::must_cast_slice_mut(byte_pairs);
```

```rust
let bytes: &mut [u8] = &mut [];
// fails to compile: (bytes.len() might not be 0)
let zsts: &mut [()] = bytemuck::must_cast_slice_mut(bytes);
```

--------------------------------

### ByteEq with const generics

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.ByteEq.html

Example of deriving ByteEq on a struct utilizing const generics.

```rust
#[derive(Copy, Clone, ByteEq)]
#[repr(C)]
struct Test<const N: usize> {
  a: [u32; N],
}
unsafe impl<const N: usize> NoUninit for Test<N> {}
```

--------------------------------

### ByteHash with const generics

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.ByteHash.html

Example of deriving ByteHash on a struct utilizing const generics.

```rust
#[derive(Copy, Clone, ByteHash)]
#[repr(C)]
struct Test<const N: usize> {
  a: [u32; N],
}
unsafe impl<const N: usize> NoUninit for Test<N> {}
```

--------------------------------

### Implement TransparentWrapper for standard types

Source: https://docs.rs/bytemuck/latest/src/bytemuck/transparent.rs.html

Examples of implementing the TransparentWrapper trait for core library types like Wrapping, Saturating, and Reverse.

```rust
unsafe impl<T> TransparentWrapper<T> for core::num::Wrapping<T> {}
```

```rust
#[cfg(feature = "transparentwrapper_extra")]
#[cfg_attr(
  feature = "nightly_docs",
  doc(cfg(feature = "transparentwrapper_extra"))
)]
unsafe impl<T> TransparentWrapper<T> for core::num::Saturating<T> {}
```

```rust
#[cfg(feature = "transparentwrapper_extra")]
#[cfg_attr(
  feature = "nightly_docs",
  doc(cfg(feature = "transparentwrapper_extra"))
)]
unsafe impl<T> TransparentWrapper<T> for core::cmp::Reverse<T> {}
```

--------------------------------

### Compile-time failure scenarios

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.must_cast_slice.html

Examples of code that will fail to compile due to alignment mismatches or invalid size calculations.

```rust
// fails to compile (bytes.len() might not be a multiple of 2):
let byte_pairs : &[[u8; 2]] = bytemuck::must_cast_slice(bytes);
```

```rust
// fails to compile (alignment requirements increased):
let indicies : &[u16] = bytemuck::must_cast_slice(byte_pairs);
```

```rust
let bytes: &[u8] = &[];
// fails to compile: (bytes.len() might not be 0)
let zsts: &[()] = bytemuck::must_cast_slice(bytes);
```

--------------------------------

### as_chunks

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Splits the slice into a slice of N-element arrays, starting at the beginning of the slice, and a remainder slice.

```APIDOC
## pub fn as_chunks<const N: usize>(&self) -> (&[[T; N]], &[T])

### Description
Splits the slice into a slice of `N`-element arrays, starting at the beginning of the slice, and a remainder slice with length strictly less than `N`.

### Panics
Panics if `N` is zero.
```

--------------------------------

### Invalid generic Pod example

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.Pod.html

A struct that fails to meet Pod requirements due to incorrect repr usage with generics.

```rust
#[derive(Copy, Clone, Pod, Zeroable)]
#[repr(C)] // must be `#[repr(transparent)]`
struct Generic<A> {
  a: A,
}
```

--------------------------------

### TransparentWrapper with Multiple Fields

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.TransparentWrapper.html

Example of using TransparentWrapper on a struct with multiple fields, requiring an explicit #[transparent(T)] attribute.

```rust
#[derive(Copy, Clone, TransparentWrapper)]
#[repr(transparent)]
#[transparent(u16)]
struct Test<T> {
  inner: u16,
  extra: PhantomData<T>,
}
```

--------------------------------

### Invalid mutable slice casting examples

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.must_cast_slice_mut.html

Examples of mutable slice casts that fail to compile due to alignment or length requirements.

```rust
// fails to compile (bytes.len() might not be a multiple of 2):
let byte_pairs : &mut [[u8; 2]] = bytemuck::must_cast_slice_mut(bytes);
```

```rust
// fails to compile (alignment requirements increased):
let indicies : &mut [u16] = bytemuck::must_cast_slice_mut(byte_pairs);
```

```rust
let bytes: &mut [u8] = &mut [];
// fails to compile: (bytes.len() might not be 0)
let zsts: &mut [()] = bytemuck::must_cast_slice_mut(bytes);
```

--------------------------------

### NoUninit Implementation for Arrays

Source: https://docs.rs/bytemuck/latest/src/bytemuck/no_uninit.rs.html

Implementation of NoUninit for arrays, gated by the min_const_generics feature.

```rust
#[cfg(feature = "min_const_generics")]
#[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "min_const_generics")))]
mod no_uninit_array {
  use super::*;
  unsafe impl<const N: usize> NoUninit for [char; N] {}
}
```

--------------------------------

### get<I>

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Returns a reference to an element or subslice depending on the type of index.

```APIDOC
## pub fn get<I>(&self, index: I) -> Option<&<I as SliceIndex<[T]>>::Output>

### Description
Returns a reference to an element or subslice depending on the type of index. If given a position, returns a reference to the element at that position or `None` if out of bounds. If given a range, returns the subslice corresponding to that range, or `None` if out of bounds.
```

--------------------------------

### Check slice prefix with starts_with

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Verifies if a slice starts with a given prefix.

```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

```rust
let v = &[10, 40, 30];
assert!(v.starts_with(&[]));
let v: &[u8] = &[];
assert!(v.starts_with(&[]));
```

--------------------------------

### Basic TransparentWrapper Usage

Source: https://docs.rs/bytemuck/latest/bytemuck/trait.TransparentWrapper.html

Demonstrates implementing TransparentWrapper for a simple struct and using wrap_ref and wrap_mut to cast references.

```rust
use bytemuck::TransparentWrapper;

#[repr(transparent)]
struct MyWrapper(SomeStruct);

unsafe impl TransparentWrapper<SomeStruct> for MyWrapper {}

// interpret a reference to &SomeStruct as a &MyWrapper
let thing = SomeStruct::default();
let inner_ref: &MyWrapper = MyWrapper::wrap_ref(&thing);

// Works with &mut too.
let mut mut_thing = SomeStruct::default();
let inner_mut: &mut MyWrapper = MyWrapper::wrap_mut(&mut mut_thing);
```

--------------------------------

### Implement Pod for wrapper and utility types

Source: https://docs.rs/bytemuck/latest/src/bytemuck/pod.rs.html

Various wrapper types and utility structures that satisfy Pod requirements.

```rust
unsafe impl<T: Pod> Pod for Wrapping<T> {}

#[cfg(feature = "pod_saturating")]
unsafe impl<T: Pod> Pod for core::num::Saturating<T>{}

unsafe impl<T: ?Sized + 'static> Pod for PhantomData<T> {}
unsafe impl Pod for PhantomPinned {}
unsafe impl<T: Pod> Pod for core::mem::ManuallyDrop<T> {}
```

--------------------------------

### NoUninit Trait Definition and Implementations

Source: https://docs.rs/bytemuck/latest/src/bytemuck/no_uninit.rs.html

The core trait definition and standard library implementations for primitive types.

```rust
pub unsafe trait NoUninit: Sized + Copy + 'static {}

unsafe impl<T: Pod> NoUninit for T {}

unsafe impl NoUninit for char {}

unsafe impl NoUninit for bool {}

unsafe impl NoUninit for NonZeroU8 {}
unsafe impl NoUninit for NonZeroI8 {}
unsafe impl NoUninit for NonZeroU16 {}
unsafe impl NoUninit for NonZeroI16 {}
unsafe impl NoUninit for NonZeroU32 {}
unsafe impl NoUninit for NonZeroI32 {}
unsafe impl NoUninit for NonZeroU64 {}
unsafe impl NoUninit for NonZeroI64 {}
unsafe impl NoUninit for NonZeroU128 {}
unsafe impl NoUninit for NonZeroI128 {}
unsafe impl NoUninit for NonZeroUsize {}
unsafe impl NoUninit for NonZeroIsize {}
```

--------------------------------

### Crate Configuration and Imports

Source: https://docs.rs/bytemuck/latest/src/bytemuck/lib.rs.html

Initial crate configuration including no_std support and conditional feature flags for architecture-specific intrinsics and core library imports.

```rust
1#![no_std]
2#![warn(missing_docs)]
3#![allow(unused_mut)]
4#![allow(clippy::match_like_matches_macro)]
5#![allow(clippy::uninlined_format_args)]
6#![allow(clippy::result_unit_err)]
7#![allow(clippy::type_complexity)]
8#![allow(clippy::manual_is_multiple_of)]
9#![cfg_attr(feature = "nightly_docs", feature(doc_cfg))]
10#![cfg_attr(feature = "nightly_portable_simd", feature(portable_simd))]
11#![cfg_attr(feature = "nightly_float", feature(f16, f128))]
12
13//! This crate gives small utilities for casting between plain data types.
14//!
15//! ## Basics
16//!
17//! Data comes in five basic forms in Rust, so we have five basic casting
18//! functions:
19//!
20//! * `T` uses [`cast`]
21//! * `&T` uses [`cast_ref`]
22//! * `&mut T` uses [`cast_mut`]
23//! * `&[T]` uses [`cast_slice`]
24//! * `&mut [T]` uses [`cast_slice_mut`]
25//!
26//! Depending on the function, the [`NoUninit`] and/or [`AnyBitPattern`] traits
27//! are used to maintain memory safety.
28//!
29//! **Historical Note:** When the crate first started the [`Pod`] trait was used
30//! instead, and so you may hear people refer to that, but it has the strongest
31//! requirements and people eventually wanted the more fine-grained system, so
32//! here we are. All types that impl `Pod` have a blanket impl to also support
33//! `NoUninit` and `AnyBitPattern`. The traits unfortunately do not have a
34//! perfectly clean hierarchy for semver reasons.
35//!
36//! ## Failures
37//!
38//! Some casts will never fail, and other casts might fail.
39//!
40//! * `cast::<u32, f32>` always works (and [`f32::from_bits`]).
41//! * `cast_ref::<[u8; 4], u32>` might fail if the specific array reference
42//!   given at runtime doesn't have alignment 4.
43//!
44//! In addition to the "normal" forms of each function, which will panic on
45//! invalid input, there's also `try_` versions which will return a `Result`.
46//!
47//! If you would like to statically ensure that a cast will work at runtime you
48//! can use the `must_cast` crate feature and the `must_` casting functions. A
49//! "must cast" that can't be statically known to be valid will cause a
50//! compilation error (and sometimes a very hard to read compilation error).
51//!
52//! ## Using Your Own Types
53//!
54//! All the functions listed above are guarded by the [`Pod`] trait, which is a
55//! sub-trait of the [`Zeroable`] trait.
56//!
57//! If you enable the crate's `derive` feature then these traits can be derived
58//! on your own types. The derive macros will perform the necessary checks on
59//! your type declaration, and trigger an error if your type does not qualify.
60//!
61//! The derive macros might not cover all edge cases, and sometimes they will
62//! error when actually everything is fine. As a last resort you can impl these
63//! traits manually. However, these traits are `unsafe`, and you should
64//! carefully read the requirements before using a manual implementation.
65//!
66//! ## Cargo Features
67//!
68//! The crate supports Rust 1.34 when no features are enabled, and so there's
69//! cargo features for thing that you might consider "obvious".
70//!
71//! The cargo features **do not** promise any particular MSRV, and they may
72//! increase their MSRV in new versions.
73//!
74//! * `derive`: Provide derive macros for the various traits.
75//! * `extern_crate_alloc`: Provide utilities for `alloc` related types such as
76//!   Box and Vec.
77//! * `zeroable_maybe_uninit` and `zeroable_atomics`: Provide more [`Zeroable`]
78//!   impls.
79//! * `pod_saturating`: Provide more [`Pod`] and [`Zeroable`] impls.
80//! * `wasm_simd` and `aarch64_simd`: Support more SIMD types.
81//! * `min_const_generics`: Provides appropriate impls for arrays of all lengths
82//!   instead of just for a select list of array lengths.
83//! * `must_cast`: Provides the `must_` functions, which will compile error if
84//!   the requested cast can't be statically verified.
85//! * `const_zeroed`: Provides a const version of the `zeroed` function.
86//!
87//! ## Related Crates
88//!
89//! - [`pack1`](https://docs.rs/pack1), which contains `bytemuck`-compatible
90//!   packed little-endian, big-endian and native-endian integer and floating
91//!   point number types.
92
93#[cfg(all(target_arch = "aarch64", feature = "aarch64_simd"))]
94use core::arch::aarch64;
95#[cfg(all(target_arch = "wasm32", feature = "wasm_simd"))]
96use core::arch::wasm32;
97#[cfg(target_arch = "x86")]
98use core::arch::x86;
99#[cfg(target_arch = "x86_64")]
100use core::arch::x86_64;
101//
102use core::{
103  marker::*,
104  mem::{align_of, size_of},
105  num::*,
106  ptr::*,
107};
108
109// Used from macros to ensure we aren't using some locally defined name and
110// actually are referencing libcore. This also would allow pre-2018 edition
```

--------------------------------

### Get last chunk

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Retrieves an array reference to the last N elements of a slice.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.last_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.last_chunk::<0>());
```

--------------------------------

### Enable extern_crate_alloc feature

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/index.html

Add this configuration to your Cargo.toml to enable the allocation module features.

```toml
bytemuck = { version = "VERSION_YOU_ARE_USING", features = ["extern_crate_alloc"]}
```

--------------------------------

### Successful mutable slice casting

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.must_cast_slice_mut.html

Examples of valid mutable slice casts that compile successfully.

```rust
let mut indicies = [1, 2, 3];
let indicies: &mut [u16] = &mut indicies;
// compiles:
let bytes: &mut [u8] = bytemuck::must_cast_slice_mut(indicies);
```

```rust
let zsts: &mut [()] = &mut [(), (), ()];
// compiles:
let bytes: &mut [u8] = bytemuck::must_cast_slice_mut(zsts);
```

--------------------------------

### Derive NoUninit Macro Usage

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.NoUninit.html

Basic syntax for deriving the NoUninit trait on a type.

```rust
#[derive(NoUninit)]
{
    // Attributes available to this derive:
    #[bytemuck]
}
```

--------------------------------

### Invalid generic Pod cast

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.Pod.html

Example of a cast that fails because the generic type does not implement Pod.

```rust
struct NotPod;

let _: u32 = bytemuck::cast(Generic { a: 4u32, b: PhantomData::<NotPod> });
```

--------------------------------

### Split slice from the end with rsplitn_mut

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Splits a mutable slice into at most n subslices starting from the end.

```rust
let mut s = [10, 40, 30, 20, 60, 50];

for group in s.rsplitn_mut(2, |num| *num % 3 == 0) {
    group[0] = 1;
}
assert_eq!(s, [1, 40, 30, 20, 60, 1]);
```

--------------------------------

### Implement CheckedBitPattern for Types

Source: https://docs.rs/bytemuck/latest/src/bytemuck/checked.rs.html

Implementations for various types including primitives and NonZero types.

```rust
unsafe impl<T: AnyBitPattern> CheckedBitPattern for T {
  type Bits = T;

  #[inline(always)]
  fn is_valid_bit_pattern(_bits: &T) -> bool {
    true
  }
}
```

```rust
unsafe impl CheckedBitPattern for char {
  type Bits = u32;

  #[inline]
  fn is_valid_bit_pattern(bits: &Self::Bits) -> bool {
    core::char::from_u32(*bits).is_some()
  }
}
```

```rust
unsafe impl CheckedBitPattern for bool {
  type Bits = u8;

  #[inline]
  fn is_valid_bit_pattern(bits: &Self::Bits) -> bool {
    // DO NOT use the `matches!` macro, it isn't 1.34 compatible.
    match *bits {
      0 | 1 => true,
      _ => false,
    }
  }
}
```

```rust
macro_rules! impl_checked_for_nonzero {
  ($($nonzero:ty: $primitive:ty),* $(,)?) => {
    $(
      unsafe impl CheckedBitPattern for $nonzero {
        type Bits = $primitive;

        #[inline]
        fn is_valid_bit_pattern(bits: &Self::Bits) -> bool {
          *bits != 0
        }
      }
    )*
  };
}
impl_checked_for_nonzero! {
  core::num::NonZeroU8: u8,
  core::num::NonZeroI8: i8,
  core::num::NonZeroU16: u16,
  core::num::NonZeroI16: i16,
  core::num::NonZeroU32: u32,
  core::num::NonZeroI32: i32,
  core::num::NonZeroU64: u64,
  core::num::NonZeroI64: i64,
  core::num::NonZeroI128: i128,
  core::num::NonZeroU128: u128,
  core::num::NonZeroUsize: usize,
  core::num::NonZeroIsize: isize,
}
```

--------------------------------

### Split slice in reverse

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Splits a slice into subslices starting from the end, excluding the matched element.

```rust
let slice = [11, 22, 33, 0, 44, 55];
let mut iter = slice.rsplit(|num| *num == 0);

assert_eq!(iter.next().unwrap(), &[44, 55]);
assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
assert_eq!(iter.next(), None);
```

```rust
let v = &[0, 1, 1, 2, 3, 5, 8];
let mut it = v.rsplit(|n| *n % 2 == 0);
assert_eq!(it.next().unwrap(), &[]);
assert_eq!(it.next().unwrap(), &[3, 5]);
assert_eq!(it.next().unwrap(), &[1, 1]);
assert_eq!(it.next().unwrap(), &[]);
assert_eq!(it.next(), None);
```

--------------------------------

### Mutate windows using Cell

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Shows how to use Cell to perform mutable operations on windows, as standard mutable windows are not supported.

```rust
use std::cell::Cell;

let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5'];
let slice = &mut array[..];
let slice_of_cells: &[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();
for w in slice_of_cells.windows(3) {
    Cell::swap(&w[0], &w[2]);
}
assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']);
```

--------------------------------

### as_rchunks

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Splits the slice into a slice of N-element arrays, starting at the end of the slice, and a remainder slice.

```APIDOC
## pub fn as_rchunks<const N: usize>(&self) -> (&[T], &[[T; N]])

### Description
Splits the slice into a slice of `N`-element arrays, starting at the end of the slice, and a remainder slice with length strictly less than `N`.

### Panics
Panics if `N` is zero.
```

--------------------------------

### from_raw_parts

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Constructs a BoxBytes instance from a raw pointer and a memory layout.

```APIDOC
## pub unsafe fn from_raw_parts(ptr: NonNull<u8>, layout: Layout) -> Self

### Description
Constructs a `BoxBytes` from its raw parts. The pointer is owned, has been allocated with the provided layout, and points to `layout.size()` initialized bytes.

### Safety
This function is unsafe because the caller must ensure the pointer is valid, owned, and matches the provided layout.
```

--------------------------------

### AnyBitPattern Trait Definition and Implementations

Source: https://docs.rs/bytemuck/latest/src/bytemuck/anybitpattern.rs.html

The core trait definition and blanket implementations for Pod types and MaybeUninit wrappers.

```rust
pub unsafe trait AnyBitPattern:
  Zeroable + Sized + Copy + 'static
{
}

unsafe impl<T: Pod> AnyBitPattern for T {}

#[cfg(feature = "zeroable_maybe_uninit")]
#[cfg_attr(
  feature = "nightly_docs",
  doc(cfg(feature = "zeroable_maybe_uninit"))
)]
unsafe impl<T> AnyBitPattern for core::mem::MaybeUninit<T> where T: AnyBitPattern
{}

#[cfg(all(feature = "zeroable_maybe_uninit", feature = "min_const_generics"))]
#[cfg_attr(
  feature = "nightly_docs",
  doc(cfg(all(
    feature = "zeroable_maybe_uninit",
    feature = "min_const_generics"
  )))
)]
unsafe impl<T, const N: usize> AnyBitPattern for [core::mem::MaybeUninit<T>; N] where
  T: AnyBitPattern
{
}
```

--------------------------------

### TransparentWrapper Derivation Failure

Source: https://docs.rs/bytemuck/latest/src/bytemuck/transparent.rs.html

Example of a compilation failure when a non-wrapped field does not implement the required Zeroable trait.

```rust
use bytemuck::TransparentWrapper;
struct MyZst;

#[derive(TransparentWrapper)]
#[repr(transparent)]
#[transparent(usize)]
struct Wrapper(usize, MyZst); // MyZst does not implement Zeroable
```

--------------------------------

### Find ranges of matching items using partition_point

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Shows how to identify the range of indices containing a specific value or determine insertion points.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

let low = s.partition_point(|x| x < &1);
assert_eq!(low, 1);
let high = s.partition_point(|x| x <= &1);
assert_eq!(high, 5);
let r = s.binary_search(&1);
assert!((low..high).contains(&r.unwrap()));

assert!(s[..low].iter().all(|&x| x < 1));
assert!(s[low..high].iter().all(|&x| x == 1));
assert!(s[high..].iter().all(|&x| x > 1));

// For something not found, the "range" of equal items is empty
assert_eq!(s.partition_point(|x| x < &11), 9);
assert_eq!(s.partition_point(|x| x <= &11), 9);
assert_eq!(s.binary_search(&11), Err(9));
```

--------------------------------

### Pod derive macro syntax

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.Pod.html

Basic syntax for applying the Pod derive macro with the bytemuck attribute.

```rust
#[derive(Pod)]
{
    // Attributes available to this derive:
    #[bytemuck]
}
```

--------------------------------

### Derive AnyBitPattern for a struct

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.AnyBitPattern.html

Use this macro to implement AnyBitPattern for a struct. Requires the derive feature to be enabled.

```rust
#[derive(AnyBitPattern)]
{
    // Attributes available to this derive:
    #[bytemuck]
}
```

--------------------------------

### Get unchecked slice element

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Returns a reference to an element or subslice without performing bounds checking.

```rust
let x = &[1, 2, 4];

unsafe {
    assert_eq!(x.get_unchecked(1), &2);
}
```

--------------------------------

### pub fn as_simd<const LANES: usize>(&self) -> (&[T], &[Simd<T, LANES>], &[T])

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Splits a slice into a prefix, a middle of aligned SIMD types, and a suffix. This is a safe wrapper around `slice::align_to`.

```APIDOC
## pub fn as_simd<const LANES: usize>(&self) -> (&[T], &[Simd<T, LANES>], &[T])

### Description
Splits a slice into a prefix, a middle of aligned SIMD types, and a suffix. This is a safe wrapper around `slice::align_to`, so inherits the same guarantees as that method.

### Panics
This will panic if the size of the SIMD type is different from `LANES` times that of the scalar.
```

--------------------------------

### Get slice element or subslice

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Returns a reference to an element or subslice based on the provided index or range.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

--------------------------------

### Get last chunk mutably

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Retrieves a mutable array reference to the last N elements of a slice.

```rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_chunk_mut::<2>() {
    last[0] = 10;
    last[1] = 20;
}
assert_eq!(x, &[0, 10, 20]);

assert_eq!(None, x.last_chunk_mut::<4>());
```

--------------------------------

### try_cast_box<A, B>(input: Box<A>) -> Result<Box<B>, (PodCastError, Box<A>)>

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/fn.try_cast_box.html

Attempts to cast the content type of a Box. Requires the crate feature 'extern_crate_alloc'.

```APIDOC
## try_cast_box

### Description
Attempts to cast the content type of a `Box` from type `A` to type `B`. If the cast fails, it returns a `PodCastError` along with the original `Box`.

### Signature
`pub fn try_cast_box<A: NoUninit, B: AnyBitPattern>(input: Box<A>) -> Result<Box<B>, (PodCastError, Box<A>)>`

### Requirements
- **Crate Feature**: `extern_crate_alloc`
- **Alignment**: The start and end content type of the `Box` must have the exact same alignment.
- **Size**: The start and end size of the `Box` must have the exact same size.
```

--------------------------------

### NoUninit Implementations for Arrays

Source: https://docs.rs/bytemuck/latest/src/bytemuck/no_uninit.rs.html

These unsafe implementations allow arrays of specific non-zero types and booleans to be treated as types without uninitialized memory.

```rust
unsafe impl<const N: usize> NoUninit for [bool; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroU8; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroI8; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroU16; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroI16; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroU32; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroI32; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroU64; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroI64; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroU128; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroI128; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroUsize; N] {}
unsafe impl<const N: usize> NoUninit for [NonZeroIsize; N] {}
```

--------------------------------

### TransparentWrapper ZST Constraint Error

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.TransparentWrapper.html

Example demonstrating a compilation error when a ZST field does not implement the Zeroable trait.

```rust
struct NonTransparentSafeZST;

#[derive(TransparentWrapper)]
#[repr(transparent)]
#[transparent(u16)]
struct Test<T> {
  inner: u16,
  extra: PhantomData<T>,
  another_extra: NonTransparentSafeZST, // not `Zeroable`
}
```

--------------------------------

### Perform binary search with a comparator

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Demonstrates searching a slice using a custom comparator function to determine element order.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

let seek = 13;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
let seek = 4;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
let seek = 100;
assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
let seek = 1;
let r = s.binary_search_by(|probe| probe.cmp(&seek));
assert!(match r { Ok(1..=4) => true, _ => false, });
```

--------------------------------

### Zeroable Derive Macro Syntax

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.Zeroable.html

Basic syntax for applying the Zeroable derive macro with available attributes.

```rust
#[derive(Zeroable)]
{
    // Attributes available to this derive:
    #[bytemuck]
    #[zeroable]
}
```

--------------------------------

### Split slice mutably in reverse

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Splits a slice into mutable subslices starting from the end, excluding the matched element.

```rust
let mut v = [100, 400, 300, 200, 600, 500];

let mut count = 0;
for group in v.rsplit_mut(|num| *num % 3 == 0) {
    count += 1;
    group[0] = count;
}
assert_eq!(v, [3, 400, 300, 2, 600, 1]);
```

--------------------------------

### Function signature for cast_ref

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.cast_ref.html

The function requires the source type to implement NoUninit and the destination type to implement AnyBitPattern.

```rust
pub fn cast_ref<A: NoUninit, B: AnyBitPattern>(a: &A) -> &B
```

--------------------------------

### Trim ASCII whitespace from byte slices

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Examples of removing leading, trailing, or both types of ASCII whitespace from byte slices.

```rust
assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
assert_eq!(b"  ".trim_ascii_start(), b"");
assert_eq!(b"".trim_ascii_start(), b"");
```

```rust
assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
assert_eq!(b"  ".trim_ascii_end(), b"");
assert_eq!(b"".trim_ascii_end(), b"");
```

```rust
assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
assert_eq!(b"  ".trim_ascii(), b"");
assert_eq!(b"".trim_ascii(), b"");
```

--------------------------------

### Iterate over contiguous windows

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Demonstrates creating an iterator over overlapping windows of a specified size. Panics if the size is zero.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.windows(3);
assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
assert!(iter.next().is_none());
```

```rust
let slice = ['f', 'o', 'o'];
let mut iter = slice.windows(4);
assert!(iter.next().is_none());
```

--------------------------------

### Compile-time slice casting failures

Source: https://docs.rs/bytemuck/latest/src/bytemuck/must.rs.html

Examples of code that fails to compile due to alignment or size constraints when using must_cast_slice.

```rust
let indicies : &[u16] = bytemuck::must_cast_slice(byte_pairs);
```

```rust
let bytes: &[u8] = &[];
// fails to compile: (bytes.len() might not be 0)
let zsts: &[()] = bytemuck::must_cast_slice(bytes);
```

--------------------------------

### TransparentWrapper Missing Attribute Error

Source: https://docs.rs/bytemuck/latest/bytemuck/derive.TransparentWrapper.html

Example demonstrating a compilation error when the required #[transparent(T)] attribute is missing for a multi-field struct.

```rust
#[derive(Copy, Clone, TransparentWrapper)]
#[repr(transparent)]
// missing `#[transparent(u16)]`
struct Test<T> {
  inner: u16,
  extra: PhantomData<T>,
}
```

--------------------------------

### Function signature for try_from_bytes_mut

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.try_from_bytes_mut.html

The function signature requires T to implement NoUninit and AnyBitPattern traits.

```rust
pub fn try_from_bytes_mut<T: NoUninit + AnyBitPattern>(
    s: &mut [u8],
) -> Result<&mut T, PodCastError>
```

--------------------------------

### TransparentWrapper with Dynamically Sized Types

Source: https://docs.rs/bytemuck/latest/bytemuck/trait.TransparentWrapper.html

Shows how to use TransparentWrapper with dynamically sized types like slices.

```rust
use bytemuck::TransparentWrapper;

#[repr(transparent)]
struct Slice<T>([T]);

unsafe impl<T> TransparentWrapper<[T]> for Slice<T> {}

let s = Slice::wrap_ref(&[1u32, 2, 3]);
assert_eq!(&s.0, &[1, 2, 3]);

let mut buf = [1, 2, 3u8];
let sm = Slice::wrap_mut(&mut buf);
```

--------------------------------

### Get unchecked mutable slice element

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Returns a mutable reference to an element or subslice without performing bounds checking.

```rust
let x = &mut [1, 2, 4];

unsafe {
    let elem = x.get_unchecked_mut(1);
    *elem = 13;
}
assert_eq!(x, &[1, 13, 4]);
```

--------------------------------

### pod_align_to_mut function signature

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.pod_align_to_mut.html

The function signature for pod_align_to_mut, requiring T and U to implement NoUninit and AnyBitPattern.

```rust
pub fn pod_align_to_mut<T: NoUninit + AnyBitPattern, U: NoUninit + AnyBitPattern>(
    vals: &mut [T],
) -> (&mut [T], &mut [U], &mut [T])
```

--------------------------------

### Function signature for cast

Source: https://docs.rs/bytemuck/latest/bytemuck/checked/fn.cast.html

The function signature requires A to implement NoUninit and B to implement CheckedBitPattern.

```rust
pub fn cast<A: NoUninit, B: CheckedBitPattern>(a: A) -> B
```

--------------------------------

### Get mutable slice element or subslice

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Returns a mutable reference to an element or subslice based on the provided index or range.

```rust
let x = &mut [0, 1, 2];

if let Some(elem) = x.get_mut(1) {
    *elem = 42;
}
assert_eq!(x, &[0, 42, 2]);
```

--------------------------------

### Split slice into N parts in reverse

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Splits a slice into at most N subslices starting from the end, excluding the matched element.

```rust
let v = [10, 40, 30, 20, 60, 50];

for group in v.rsplitn(2, |num| *num % 3 == 0) {
    println!("{group:?}");
}
```

--------------------------------

### as_ptr

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Returns a raw pointer to the slice’s buffer.

```APIDOC
## pub fn as_ptr(&self) -> *const T

### Description
Returns a raw pointer to the slice’s buffer. The caller must ensure that the slice outlives the pointer and that the memory is not written to.
```

--------------------------------

### Iterate over slice in reverse chunks

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Demonstrates using rchunks to iterate over a slice in chunks of a specified size starting from the end.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.rchunks(2);
assert_eq!(iter.next().unwrap(), &['e', 'm']);
assert_eq!(iter.next().unwrap(), &['o', 'r']);
assert_eq!(iter.next().unwrap(), &['l']);
assert!(iter.next().is_none());
```

--------------------------------

### Signature of the cast function

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.cast.html

The function signature requires the source type to implement NoUninit and the destination type to implement AnyBitPattern.

```rust
pub fn cast<A: NoUninit, B: AnyBitPattern>(a: A) -> B
```

--------------------------------

### array_windows<const N: usize>

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Returns an iterator over overlapping windows of N elements of a slice, starting at the beginning of the slice.

```APIDOC
## pub fn array_windows<const N: usize>(&self) -> ArrayWindows<'_, T, N>

### Description
Returns an iterator over overlapping windows of N elements of a slice, starting at the beginning of the slice. If N is greater than the size of the slice, it will return no windows.

### Panics
Panics if N is zero.
```

--------------------------------

### pub fn try_from_bytes<T: AnyBitPattern>(s: &[u8]) -> Result<&T, PodCastError>

Source: https://docs.rs/bytemuck/latest/bytemuck/fn.try_from_bytes.html

Re-interprets a byte slice as a reference to a type T. This function returns a Result containing the reference if the conversion is successful, or a PodCastError if the slice is not properly aligned or the length does not match the size of T.

```APIDOC
## try_from_bytes

### Description
Re-interprets a `&[u8]` as a `&T`. This function performs a safe cast by verifying alignment and size requirements.

### Signature
`pub fn try_from_bytes<T: AnyBitPattern>(s: &[u8]) -> Result<&T, PodCastError>`

### Failure Conditions
- The slice is not aligned for the target type `T`.
- The slice length is not exactly the size of the target type `T`.
```

--------------------------------

### Perform binary search on a slice

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Demonstrates searching for elements in a sorted slice, handling both found and missing values.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

assert_eq!(s.binary_search(&13),  Ok(9));
assert_eq!(s.binary_search(&4),   Err(7));
assert_eq!(s.binary_search(&100), Err(13));
let r = s.binary_search(&1);
assert!(match r { Ok(1..=4) => true, _ => false, });
```

--------------------------------

### chunks_exact_mut

Source: https://docs.rs/bytemuck/latest/bytemuck/allocation/struct.BoxBytes.html

Returns an iterator over chunk_size elements of the slice at a time, starting at the beginning of the slice. The chunks are mutable slices and do not overlap.

```APIDOC
## pub fn chunks_exact_mut(&mut self, chunk_size: usize) -> ChunksExactMut<'_, T>

### Description
Returns an iterator over `chunk_size` elements of the slice at a time, starting at the beginning of the slice. The chunks are mutable slices, and do not overlap. If `chunk_size` does not divide the length of the slice, then the last up to `chunk_size-1` elements will be omitted.

### Parameters
- **chunk_size** (usize) - Required - The size of each chunk.

### Panics
Panics if `chunk_size` is zero.
```
Tokens:
Raw