bytecheck

https://docs.rs/bytecheck/0.8.2
Admin
bytecheck is a memory validation framework for Rust that performs byte-level validations and...
Tokens:27,375
Snippets:178
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Bytecheck Usage Example

Source: https://docs.rs/bytecheck/0.8.2/index.html

Demonstrates how to use the bytecheck crate with a custom struct, including valid and invalid byte scenarios.

```APIDOC
## Example

```rust
use bytecheck::{CheckBytes, check_bytes, rancor::Failure};

#[derive(CheckBytes, Debug)]
#[repr(C)]
struct Test {
    a: u32,
    b: char,
    c: bool,
}

#[repr(C, align(4))]
struct Aligned<const N: usize>([u8; N]);

macro_rules! bytes {
    ($($byte:literal,)*) => {
        (&Aligned([$($byte,)*]).0 as &[u8]).as_ptr()
    };
    ($($byte:literal),*) => {
        bytes!($($byte,)*)
    };
}

// In this example, the architecture is assumed to be little-endian
#[cfg(target_endian = "little")]
unsafe {
    // These are valid bytes for a `Test`
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x78u8, 0u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap();

    // Changing the bytes for the u32 is OK, any bytes are a valid u32
    check_bytes::<Test, Failure>(
        bytes![
            42u8, 16u8, 20u8, 3u8,
            0x78u8, 0u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap();

    // Characters outside the valid ranges are invalid
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x00u8, 0xd8u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap_err();
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x00u8, 0x00u8, 0x11u8, 0u8,
            1u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap_err();

    // 0 is a valid boolean value (false) but 2 is not
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x78u8, 0u8, 0u8, 0u8,
            0u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap();
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x78u8, 0u8, 0u8, 0u8,
            2u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap_err();
}
```
```

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

### Example: Custom CheckBytes Implementation

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Demonstrates how to manually implement the `CheckBytes` trait for a custom type, including custom error handling.

```APIDOC
## Example: Manual `CheckBytes` Implementation

### Description
This example shows a manual implementation of `CheckBytes` for a `NonMaxU32` struct, which enforces that the `u32` value does not exceed a certain maximum. It defines a custom error type for validation failures.

### Type Definition
```rust
#[repr(C, align(4))]
pub struct NonMaxU32(u32);
```

### Custom Error Type
```rust
#[derive(Debug)]
struct NonMaxCheckError;

impl fmt::Display for NonMaxCheckError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "value exceeds maximum")
    }
}

impl Error for NonMaxCheckError {}
```

### `CheckBytes` Implementation
```rust
use core::{error::Error, fmt};
use bytecheck::CheckBytes;
use rancor::{fail, Fallible, Source};

unsafe impl<C: Fallible + ?Sized> CheckBytes<C> for NonMaxU32
where
    C::Error: Source,
{
    unsafe fn check_bytes(
        value: *const Self,
        context: &mut C,
    ) -> Result<(), C::Error> {
        // Dereference the pointer to get the value
        let inner_value = (*value).0;

        // Define the maximum allowed value (e.g., u32::MAX - 1)
        const MAX_ALLOWED: u32 = u32::MAX - 1;

        if inner_value > MAX_ALLOWED {
            // Use `fail` to create and return a custom error
            fail!(NonMaxCheckError).with_context(context)
        } else {
            // If the value is valid, return Ok
            Ok(())
        }
    }
}
```
```

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

### Verify Struct2 with Current Crate Root

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This code demonstrates verifying an instance of `Test2` using `check_bytes`. Similar to the previous example, it uses `Infallible` as the context.

```rust
unsafe {
    check_bytes::<_, Infallible>(&Test2).unwrap();
}
```

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

### Implementing Verify for a Custom Type

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/trait.Verify.html

Example showing how to implement the Verify trait for a struct, including custom error handling and the use of the #[bytecheck(verify)] attribute.

```rust
use core::{error::Error, fmt};

use bytecheck::{CheckBytes, Verify};
use rancor::{fail, Fallible, Source};

#[derive(CheckBytes)]
#[bytecheck(verify)]
#[repr(C, align(4))]
pub struct NonMaxU32(u32);

unsafe impl<C: Fallible + ?Sized> Verify<C> for NonMaxU32
where
    C::Error: Source,
{
    fn verify(&self, context: &mut C) -> Result<(), C::Error> {
        #[derive(Debug)]
        struct NonMaxCheckError;

        impl fmt::Display for NonMaxCheckError {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "non-max u32 was set to u32::MAX")
            }
        }

        impl Error for NonMaxCheckError {}

        if self.0 == u32::MAX {
            fail!(NonMaxCheckError);
        }

        Ok(())
    }
}
```

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

### Derive CheckBytes and Verify for UnitStruct

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This example derives `CheckBytes` and `verify` for a `UnitStruct`. The `#[bytecheck(crate, verify)]` attribute enables both functionalities, allowing the struct to be checked and verified using custom logic.

```rust
#[derive(CheckBytes)]
#[bytecheck(crate, verify)]
struct UnitStruct;
```

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

### CheckBytes Trait Example

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/trait.CheckBytes.html

An example implementation of the CheckBytes trait for a custom struct NonMaxU32.

```APIDOC
## Example
```rust
use core::{error::Error, fmt};

use bytecheck::CheckBytes;
use rancor::{fail, Fallible, Source};

#[repr(C, align(4))]
pub struct NonMaxU32(u32);

unsafe impl<C: Fallible + ?Sized>
    CheckBytes<C> for NonMaxU32
where
    C::Error: Source,
{
    unsafe fn check_bytes(
        value: *const Self,
        context: &mut C,
    ) -> Result<(), C::Error> {
        #[derive(Debug)]
        struct NonMaxCheckError;

        impl fmt::Display for NonMaxCheckError {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "non-max u32 was set to u32::MAX")
            }
        }

        impl Error for NonMaxCheckError {}

        let value = unsafe { value.read() };
        if value.0 == u32::MAX {
            fail!(NonMaxCheckError);
        }

        Ok(())
    }
}
```
See `Verify` for an example which uses less unsafe.
```

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

### Test Struct with Bytecheck

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Validates a regular struct using `check_bytes`. This example includes a `Debug` derive and uses `Failure` as the error type. It also demonstrates checking against specific byte sequences, similar to the tuple struct example.

```rust
#[derive(CheckBytes, Debug)]
#[bytecheck(crate)]
struct Test {
    a: u32,
    b: bool,
    c: CharLE,
}

let value = Test {
    a: 42,
    b: true,
    c: 'x'.into(),
};

unsafe {
    check_bytes::<_, Failure>(&value).unwrap();
}
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 1u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        42u8, 16u8, 20u8, 3u8, 0x78u8, 0u8, 0u8, 0u8, 1u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x00u8, 0xd8u8, 0u8, 0u8, 1u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap_err();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x00u8, 0x00u8, 0x11u8, 0u8, 1u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap_err();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 0u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 2u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap_err();
```

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

### Example Usage of Node Enum with check_bytes

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This code block shows how to create instances of the `Node` enum and use the `check_bytes` function to verify them. It involves creating a `Nil` node and a `Cons` node pointing to the `Nil` node.

```rust
unsafe {
    let nil = Node::Nil;
    let cons = Node::Cons(MyBox {
        inner: &nil as *const Node,
    });
    check_bytes::<Node, Failure>(&cons).unwrap();
}
```

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

### Contextual Byte Check Example

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This snippet illustrates using `check_bytes_with_context` to validate a byte value against a specific context. It defines a `Context` trait and an `Allowed` struct to check if a byte matches a predefined value.

```rust
use core::{error::Error, fmt};

use bytecheck::{check_bytes_with_context, CheckBytes, Verify};
use rancor::{fail, Failure, Fallible, Source, Strategy};

trait Context {
    fn is_allowed(&self, value: u8) -> bool;
}

impl<T: Context + ?Sized, E> Context for Strategy<T, E> {
    fn is_allowed(&self, value: u8) -> bool {
        T::is_allowed(self, value)
    }
}

struct Allowed(u8);

impl Context for Allowed {
    fn is_allowed(&self, value: u8) -> bool {
        value == self.0
    }
}

#[derive(CheckBytes)]
#[bytecheck(verify)]
#[repr(C)]
pub struct ContextualByte(u8);


```

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

### Example of Verify Trait Implementation

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Demonstrates implementing the `Verify` trait for a `NonMaxU32` struct. The `verify` method checks if the `u32` field is equal to `u32::MAX` and returns an error if it is, ensuring the invariant is upheld.

```rust
use core::{error::Error, fmt};

use bytecheck::{CheckBytes, Verify};
use rancor::{fail, Fallible, Source};

#[derive(CheckBytes)]
#[bytecheck(verify)]
#[repr(C, align(4))]
pub struct NonMaxU32(u32);

unsafe impl<C: Fallible + ?Sized> Verify<C> for NonMaxU32
where
    C::Error: Source,
{
    fn verify(&self, context: &mut C) -> Result<(), C::Error> {
        #[derive(Debug)]
        struct NonMaxCheckError;

        impl fmt::Display for NonMaxCheckError {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "non-max u32 was set to u32::MAX")
            }
        }

        impl Error for NonMaxCheckError {}

        if self.0 == u32::MAX {
            fail!(NonMaxCheckError);
        }

        Ok(())
    }
}

```

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

### Derive CheckBytes and Verify for Struct

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This example derives `CheckBytes` and `verify` for a `Struct` with a `value` field. The `#[bytecheck(crate, verify)]` attribute enables both functionalities, allowing the struct to be checked and verified with its field value influencing the context.

```rust
#[derive(CheckBytes)]
#[bytecheck(crate, verify)]
struct Struct {
    value: i32,
}
```

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

### Derive CheckBytes with Current Crate Root

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This example derives `CheckBytes` for `Test2` using `#[bytecheck(crate = crate)]`, explicitly specifying the current crate as the source for `bytecheck` macros. This is equivalent to not specifying the `crate` attribute if `bytecheck` is in the root.

```rust
#[derive(CheckBytes)]
#[bytecheck(crate = crate)]
struct Test2;
```

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

### Example Usage of check_bytes

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/fn.check_bytes.html

Demonstrates checking valid and invalid byte representations for a boolean type using check_bytes. Ensure the pointer is correctly cast to the target type.

```rust
use bytecheck::check_bytes;
use rancor::Failure;

unsafe {
    // 0 and 1 are valid values for bools
    check_bytes::<bool, Failure>((&0u8 as *const u8).cast()).unwrap();
    check_bytes::<bool, Failure>((&1u8 as *const u8).cast()).unwrap();

    // 2 is not a valid value
    check_bytes::<bool, Failure>((&2u8 as *const u8).cast()).unwrap_err();
}

```

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

### Test Tuple Struct with Bytecheck

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Validates a tuple struct using `check_bytes`. This example includes a `Debug` derive and uses `Failure` as the error type. It also demonstrates checking against specific byte sequences.

```rust
#[derive(CheckBytes, Debug)]
#[bytecheck(crate)]
struct Test(u32, bool, CharLE);

let value = Test(42, true, 'x'.into());

unsafe {
    check_bytes::<_, Failure>(&value).unwrap();
}
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 1u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        42u8, 16u8, 20u8, 3u8, 0x78u8, 0u8, 0u8, 0u8, 1u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x00u8, 0xd8u8, 0u8, 0u8, 1u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap_err();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x00u8, 0x00u8, 0x11u8, 0u8, 1u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap_err();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 0u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap();
```

```rust
check_bytes::<Test, Failure>(
    bytes![
        0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 2u8, 255u8,
        255u8, 255u8, 255u8, 255u8, 255u8, 255u8,
    ]
    .cast(),
)
.unwrap_err();
```

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

### Derive CheckBytes and Verify for TupleStruct

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This example derives `CheckBytes` and `verify` for a `TupleStruct` containing an `i32`. The `#[bytecheck(crate, verify)]` attribute enables both functionalities, allowing the tuple struct to be checked and verified, with its inner value affecting the context.

```rust
#[derive(CheckBytes)]
#[bytecheck(crate, verify)]
struct TupleStruct(i32);
```

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

### Validate Struct Bytes with CheckBytes

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/index.html

Demonstrates using the CheckBytes derive macro and check_bytes function to validate memory representations of a struct. Requires the target architecture to be little-endian for this specific example.

```rust
use bytecheck::{CheckBytes, check_bytes, rancor::Failure};

#[derive(CheckBytes, Debug)]
#[repr(C)]
struct Test {
    a: u32,
    b: char,
    c: bool,
}

#[repr(C, align(4))]
struct Aligned<const N: usize>([u8; N]);

macro_rules! bytes {
    ($($byte:literal,)*) => {
        (&Aligned([$($byte,)*]).0 as &[u8]).as_ptr()
    };
    ($($byte:literal),*) => {
        bytes!($($byte,)*)
    };
}

// In this example, the architecture is assumed to be little-endian
#[cfg(target_endian = "little")]
unsafe {
    // These are valid bytes for a `Test`
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x78u8, 0u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap();

    // Changing the bytes for the u32 is OK, any bytes are a valid u32
    check_bytes::<Test, Failure>(
        bytes![
            42u8, 16u8, 20u8, 3u8,
            0x78u8, 0u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap();

    // Characters outside the valid ranges are invalid
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x00u8, 0xd8u8, 0u8, 0u8,
            1u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap_err();
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x00u8, 0x00u8, 0x11u8, 0u8,
            1u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap_err();

    // 0 is a valid boolean value (false) but 2 is not
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x78u8, 0u8, 0u8, 0u8,
            0u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap();
    check_bytes::<Test, Failure>(
        bytes![
            0u8, 0u8, 0u8, 0u8,
            0x78u8, 0u8, 0u8, 0u8,
            2u8, 255u8, 255u8, 255u8,
        ].cast()
    ).unwrap_err();
}
```

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

### Derive CheckBytes with Explicit Crate Root Alias

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This example shows how to derive `CheckBytes` for a struct `Test` by explicitly aliasing the `bytecheck` crate using `#[bytecheck(crate = m::bc)]`. This is useful when the `bytecheck` crate is imported into a module with a different name.

```rust
mod m {
    pub use crate as bc;
}

#[derive(CheckBytes)]
#[bytecheck(crate = m::bc)]
struct Test;
```

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

### Implement CheckBytes for Slices

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This implementation of `CheckBytes` for slices iterates through each element, calling `check_bytes` on it. It uses `SliceCheckContext` to provide specific error tracing for slice index issues. The `ptr_meta::to_raw_parts` function is used to get the slice's data pointer and length.

```rust
// SAFETY: `check_bytes` only returns `Ok` if each element of the slice is
// valid. If each element of the slice is valid then the whole slice is also
// valid.
unsafe impl<T, C> CheckBytes<C> for [T]
where
    T: CheckBytes<C>,
    C: Fallible + ?Sized,
    C::Error: Trace,
{
    #[inline]
    unsafe fn check_bytes(
        value: *const Self,
        context: &mut C,
    ) -> Result<(), C::Error> {
        let (data_address, len) = ptr_meta::to_raw_parts(value);
        let base = data_address.cast::<T>();
        for index in 0..len {
            // SAFETY: The caller has guaranteed that `value` points to enough
            // bytes for this slice and is properly aligned, so we can create
            // pointers to each element and check them.
            unsafe {

```

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

### Implement CheckBytes for Custom Type

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Implement the `CheckBytes` trait for a custom struct to enable byte-level validation. This example shows how to validate a `NonMaxU32` type, returning an error if the value is invalid. Requires `rancor` for error handling.

```rust
use core::{error::Error, fmt};

use bytecheck::CheckBytes;
use rancor::{fail, Fallible, Source};

#[repr(C, align(4))]
pub struct NonMaxU32(u32);

unsafe impl<C: Fallible + ?Sized>
    CheckBytes<C> for NonMaxU32
where
    C::Error: Source,
{
    unsafe fn check_bytes(
        value: *const Self,
        context: &mut C,
    ) -> Result<(), C::Error> {
        #[derive(Debug)]
        struct NonMaxCheckError;

        impl fmt::Display for NonMaxCheckError {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                f.write_str("value is not a valid NonMaxU32")
            }
        }

        impl Error for NonMaxCheckError {}

        let this = &*value;

        if this.0 > u32::MAX - 1 {
            fail!(NonMaxCheckError);
        }

        Ok(())
    }
}
```

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

### Custom NonMaxU32 Implementation of CheckBytes

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/trait.CheckBytes.html

An example of manually implementing the CheckBytes trait for a custom struct NonMaxU32. This implementation checks if the u32 value is equal to u32::MAX, returning an error if it is. Requires the rancor crate for Fallible and Source traits.

```rust
use core::{error::Error, fmt};

use bytecheck::CheckBytes;
use rancor::{fail, Fallible, Source};

#[repr(C, align(4))]
pub struct NonMaxU32(u32);

unsafe impl<C: Fallible + ?Sized>
where
    C::Error: Source,
{
    unsafe fn check_bytes(
        value: *const Self,
        context: &mut C,
    ) -> Result<(), C::Error> {
        #[derive(Debug)]
        struct NonMaxCheckError;

        impl fmt::Display for NonMaxCheckError {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "non-max u32 was set to u32::MAX")
            }
        }

        impl Error for NonMaxCheckError {}

        let value = unsafe { value.read() };
        if value.0 == u32::MAX {
            fail!(NonMaxCheckError);
        }

        Ok(())
    }
}
```

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

### Bytecheck Crate Overview

Source: https://docs.rs/bytecheck/0.8.2/index.html

Provides a summary of the bytecheck crate, its core functionality, and design principles.

```APIDOC
## Crate bytecheck

### Summary

bytecheck is a memory validation framework for Rust. It helps in validating potentially invalid bytes by providing a framework to perform byte-level checks before casting them to a specific type, thus preventing undefined behavior.

### Design

The `CheckBytes` trait is central to bytecheck, handling the verification of bytes representing a valid type. This can be implemented manually or automatically using the derive macro.

### Features

*   `derive`: Re-exports macros from `bytecheck_derive`. Enabled by default.
*   `simdutf8`: Uses the `simdutf8` crate for UTF-8 string validation. Enabled by default.

### Crates

Bytecheck offers default integrations for common crates, such as `uuid-1`.
```

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

### Check and Verify Struct with Custom Context

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This code demonstrates checking and verifying a `Struct` instance with `value: 4`. It uses `check_bytes_with_context` and a `FooContext`, asserting that the context's value is updated to 4 after verification.

```rust
let mut context = FooContext { value: 0 };
unsafe {
    check_bytes_with_context::<_, _, Infallible>(
        &Struct { value: 4 },
        &mut context,
    )
    .unwrap();
}

assert_eq!(context.value, 4);
```

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

### Define Aligned Helper and Bytes Macro

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Utility structures and macros for creating aligned byte buffers for testing.

```rust
#[repr(C, align(16))]
struct Aligned<const N: usize>(pub [u8; N]);

macro_rules! bytes {
    ($($byte:literal),* $(,)?) => {
        (&$crate::tests::Aligned([$($byte,)*]).0 as &[u8]).as_ptr()
    }
}
```

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

### Check and Verify UnitStruct with Custom Context

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This code demonstrates checking and verifying a `UnitStruct` using `check_bytes_with_context`. It initializes a `FooContext` and asserts that its `value` field is updated to 1 after the verification process.

```rust
let mut context = FooContext { value: 0 };
unsafe {
    check_bytes_with_context::<_, _, Infallible>(
        &UnitStruct,
        &mut context,
    )
    .unwrap();
}

assert_eq!(context.value, 1);
```

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

### Check Bytes with Context

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Demonstrates checking bytes with a specific context, showing both successful and failing scenarios. This function is unsafe and requires careful handling of pointers and contexts.

```rust
let value = 45u8;
unsafe {
    // Checking passes when the context allows byte 45
    check_bytes_with_context::<ContextualByte, _, Failure>(
        (&value as *const u8).cast(),
        &mut Allowed(45),
    )
    .unwrap();

    // Checking fails when the conteext does not allow byte 45
    check_bytes_with_context::<ContextualByte, _, Failure>(
        (&value as *const u8).cast(),
        &mut Allowed(0),
    )
    .unwrap_err();
}
```

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

### Implement Verify for UnitStruct with Custom Context

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This snippet implements the `Verify` trait for a `UnitStruct`. The `verify` method interacts with a custom context `C` that implements `MyContext`, setting its value to 1. This demonstrates how to integrate custom verification logic with context.

```rust
unsafe impl<C: Fallible + MyContext + ?Sized> Verify<C> for UnitStruct {
    fn verify(&self, context: &mut C) -> Result<(), C::Error> {
        context.set_value(1);
        Ok(())
    }
}
```

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

### Test Unit Struct with Bytecheck

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Demonstrates checking a unit struct using `check_bytes`. Requires the `CheckBytes` derive macro and `#[bytecheck(crate)]` attribute. Uses `Infallible` for error type.

```rust
#[derive(CheckBytes)]
#[bytecheck(crate)]
struct Test;

unsafe {
    check_bytes::<_, Infallible>(&Test).unwrap();
}
```

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

### Check and Verify TupleStruct with Custom Context

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This code demonstrates checking and verifying a `TupleStruct(10)` using `check_bytes_with_context`. It uses a `FooContext` and asserts that the context's value is updated to 10 after verification.

```rust
let mut context = FooContext { value: 0 };
unsafe {
    check_bytes_with_context::<_, _, Infallible>(
        &TupleStruct(10),
        &mut context,
    )
    .unwrap();
}

assert_eq!(context.value, 10);
```

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

### Implement ContextualByte Verification

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Implements the `Verify` trait for `ContextualByte` to check if a byte is allowed by the provided context. This is used for custom byte validation logic.

```rust
unsafe impl<C: Context + Fallible + ?Sized> Verify<C> for ContextualByte
where
    C::Error: Source,
{
    fn verify(&self, context: &mut C) -> Result<(), C::Error> {
        #[derive(Debug)]
        struct InvalidByte(u8);

        impl fmt::Display for InvalidByte {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "invalid contextual byte: {}", self.0)
            }
        }

        impl Error for InvalidByte {}

        if !context.is_allowed(self.0) {
            fail!(InvalidByte(self.0));
        }

        Ok(())
    }
}
```

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

### Derive CheckBytes for Enum with Custom Crate

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Demonstrates deriving `CheckBytes` for an enum `Node` while specifying a custom crate root for the `bytecheck` macros. This is useful when `bytecheck` is re-exported or used from a different path.

```rust
#[derive(CheckBytes)]
#[bytecheck(crate)]
#[repr(u8)]
enum Node {
    Nil,
    Cons(#[bytecheck(omit_bounds)] MyBox<Node>),
}
```

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

### Bytecheck API - Traits and Functions

Source: https://docs.rs/bytecheck/0.8.2/index.html

Details the core traits and functions provided by the bytecheck crate for memory validation.

```APIDOC
## Traits

### CheckBytes

A type that can check whether a pointer points to a valid value.

### Verify

A type that can check whether its invariants are upheld.

## Functions

### check_bytes⚠

Checks whether the given pointer points to a valid value.

### check_bytes_with_context⚠

Checks whether the given pointer points to a valid value within the given context.

## Derive Macros

### CheckBytes

Derives `CheckBytes` for the labeled type.
```

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

### Function check_bytes_with_context

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/fn.check_bytes_with_context.html

Checks whether the given pointer points to a valid value within the given context.

```APIDOC
## Function check_bytes_with_context

### Description
Checks whether the given pointer points to a valid value within the given context.

### Signature
`pub unsafe fn check_bytes_with_context<T, C, E>(value: *const T, context: &mut C) -> Result<(), E>`

### Parameters
- **value** (*const T) - Required - The pointer to the value to check.
- **context** (&mut C) - Required - The context used for validation.

### Safety
The passed pointer must be aligned and point to enough initialized bytes to represent the type.

### Request Example
```rust
let value = 45u8;
unsafe {
    check_bytes_with_context::<ContextualByte, _, Failure>(
        (&value as *const u8).cast(),
        &mut Allowed(45),
    ).unwrap();
}
```
```

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

### Trait: Verify

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/trait.Verify.html

Documentation for the Verify trait, which defines the interface for checking type invariants.

```APIDOC
## Trait Verify

### Description
A type that can check whether its invariants are upheld. When using the derive, adding `#[bytecheck(verify)]` allows implementing `Verify` for the derived type. `Verify::verify` will be called after the type is checked and all fields are known to be valid.

### Required Methods
#### fn verify(&self, context: &mut C) -> Result<(), C::Error>
Checks whether the invariants of this type are upheld by `self`.

### Safety
- `verify` must only return `Ok` if all of the invariants of this type are upheld by `self`.
- `verify` may not assume that its type invariants are upheld by the given `self` (the invariants of each field are guaranteed to be upheld).
```

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

### CheckBytes for PhantomData<T>

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/trait.CheckBytes.html

This snippet shows the implementation of check_bytes for PhantomData<T>. This implementation is a no-op.

```APIDOC
## unsafe fn check_bytes(_: *const Self, _: &mut C) -> Result<(), C::Error>

### Description
Checks the bytes of a PhantomData<T>. This is a no-op.

### Method
unsafe fn

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Implement Debug for TupleStructCheckContext

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/struct.TupleStructCheckContext.html

Provides a Debug implementation for TupleStructCheckContext, allowing it to be formatted for debugging purposes.

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

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

### Check Bytes for char

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Implements `CheckBytes` for `char`. It reads the pointed-to value as an unaligned `u32` and attempts to convert it to a `char`. This is safe because `char` is a Unicode scalar value, and `try_from` validates this.

```rust
unsafe fn check_bytes(ptr: *const Self, _: &mut C) -> Result<(), C::Error> {
        // SAFETY: `char` and `u32` are both four bytes, but we're not
        // guaranteed that they have the same alignment. Using `read_unaligned`
        // ensures that we can read a `u32` regardless and try to convert it to
        // a `char`.
        
```

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

### Implement Verify for Struct with Custom Context

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This snippet implements the `Verify` trait for a `Struct`. The `verify` method sets the context's value to the `value` field of the struct instance. This shows how to pass struct field data into the verification context.

```rust
unsafe impl<C: Fallible + MyContext + ?Sized> Verify<C> for Struct {
    fn verify(&self, context: &mut C) -> Result<(), C::Error> {
        context.set_value(self.value);
        Ok(())
    }
}
```

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

### Verify Trait Definition

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/trait.Verify.html

The core trait definition for verifying type invariants within a fallible context.

```rust
pub unsafe trait Verify<C: Fallible + ?Sized> {
    // Required method
    fn verify(&self, context: &mut C) -> Result<(), C::Error>;
}
```

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

### Implement CheckBytes for str

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Validates that the bytes pointed to by a str are valid UTF-8. It uses an optimized check by verifying ASCII status before falling back to full UTF-8 validation.

```rust
unsafe impl<C> CheckBytes<C> for str
where
    C: Fallible + ?Sized,
    C::Error: Source,
{
    #[inline]
    unsafe fn check_bytes(
        value: *const Self,
        _: &mut C,
    ) -> Result<(), C::Error> {
        #[derive(Debug)]
        struct Utf8Error;

        impl fmt::Display for Utf8Error {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "invalid UTF-8")
            }
        }

        impl Error for Utf8Error {}

        let slice_ptr = value as *const [u8];
        // SAFETY: The caller has guaranteed that `value` is properly-aligned
        // and points to enough bytes for its `str`. Because a `u8` slice has
        // the same layout as a `str`, we can dereference it for UTF-8
        // validation.
        let slice = unsafe { &*slice_ptr };

        // Checking whether a byte slice is ASCII is much faster than checking
        // whether it is valid UTF-8. Falling back to a full UTF-8 check
        // afterward nets a performance improvement for the average case.
        if !slice.is_ascii() {
            from_utf8(slice).map_err(|_| Utf8Error).into_error()?;
        }

        Ok(())
    }
}
```

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

### Implement Any for T

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/struct.InvalidEnumDiscriminantError.html

Blanket implementation of the Any trait for any type T, providing runtime type information.

```rust
impl<T> Any for T
where T: 'static + ?Sized,
Source§
#### fn type_id(&self) -> TypeId
```

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

### Implement CheckBytes for Tuples

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This macro implements the `CheckBytes` trait for tuples of varying sizes. It iterates through each element of the tuple, recursively calling `check_bytes` on them. The `with_trace` method is used to add context to errors, indicating which tuple element caused the failure.

```rust
macro_rules! impl_tuple {
    ($($type:ident $index:tt),*) => {
        // SAFETY: A tuple is valid if all of its elements are valid, and
        // `check_bytes` only returns `Ok` when all of the elements validated
        // successfully.
        unsafe impl<$($type,)* C> CheckBytes<C> for ($($type,)*)
        where
            $($type: CheckBytes<C>,)*
            C: Fallible + ?Sized,
            C::Error: Trace,
        {
            #[inline]
            #[allow(clippy::unneeded_wildcard_pattern)]
            unsafe fn check_bytes(
                value: *const Self,
                context: &mut C,
            ) -> Result<(), C::Error> {
                $( 
                    // SAFETY: The caller has guaranteed that `value` points to
                    // enough bytes for this tuple and is properly aligned, so
                    // we can create pointers to each element and check them.
                    unsafe {
                        <$type>::check_bytes(
                            ptr::addr_of!((*value).$index),
                            context,
                        ).with_trace(|| TupleIndexContext { index: $index })?;
                    }
                )*
                Ok(())
            }
        }
    }
}
```

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

### CheckBytes for [T; N]

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/trait.CheckBytes.html

This snippet shows the implementation of check_bytes for a fixed-size array [T; N], where T must implement CheckBytes.

```APIDOC
## unsafe fn check_bytes( value: *const Self, context: &mut C, ) -> Result<(), C::Error>

### Description
Checks the bytes of a fixed-size array [T; N].

### Method
unsafe fn

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Implement TryInto<U> for T

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/struct.TupleStructCheckContext.html

Provides a fallible conversion from type T into type U. The associated Error type indicates conversion failures.

```rust
type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

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

### Check Bytes for CharLE (Big-Endian)

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

Implements `CheckBytes` for `CharLE` when the target endianness is big. It reads the `u32` as bytes, reverses them to simulate little-endian, and then checks the resulting `char`.

```rust
#[cfg(target_endian = "big")]
unsafe {
    let mut bytes = *value.cast::<[u8; 4]>();
    bytes.reverse();
    char::check_bytes(bytes.as_ref().as_ptr().cast(), context)
}
```

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

### Implement CheckBytes for MyBox<T>

Source: https://docs.rs/bytecheck/0.8.2/src/bytecheck/lib.rs.html

This snippet shows how to implement the `CheckBytes` trait for a custom smart pointer `MyBox<T>`, delegating the check to the inner type `T`. It requires `T` to implement `CheckBytes` and `C` to be a `Fallible` context.

```rust
unsafe impl<T, C> CheckBytes<C> for MyBox<T>
        where
            T: CheckBytes<C>,
            C: Fallible + ?Sized,
        {
            unsafe fn check_bytes(
                value: *const Self,
                context: &mut C,
            ) -> Result<(), C::Error> {
                unsafe { T::check_bytes((*value).inner, context) }
            }
        }
```

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

### Implement Pointee for T

Source: https://docs.rs/bytecheck/0.8.2/bytecheck/struct.TupleStructCheckContext.html

Defines the metadata type for pointers and references to type T.

```rust
type Metadata = ();
```
Tokens:
Raw