[−][src]Crate bytecheck
bytecheck
bytecheck is a type validation framework for Rust.
For some types, creating an invalid value immediately results in undefined behavior. This can cause some issues when trying to validate potentially invalid bytes, as just casting the bytes to your type can technically cause errors. This makes it difficult to write validation routines, because until you're certain that the bytes represent valid values you cannot cast them.
bytecheck provides a framework for performing these byte-level validations and implements checks for basic types along with a derive macro to implement validation for custom structs and enums.
Design
There are two traits at the core of bytecheck, Context
and
CheckBytes
. CheckBytes
does the heavy lifting of verifying
that some bytes represent a valid type, whereas Context
provides
any contextual information that may be needed to properly do so. For
core types no context is required, but for more complex and custom
types there may be context needed to properly validate bytes.
Examples
use bytecheck::CheckBytes; #[derive(CheckBytes, Debug)] struct Test { a: u32, b: bool, c: char, } // This type is laid out as (u32, char, bool) unsafe { // These are valid bytes for (0, 'x', true) Test::check_bytes( &[ 0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 1u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8 ] as *const u8, &() ).unwrap(); // Changing the bytes for the u32 is OK, any bytes are a valid u32 Test::check_bytes( &[ 42u8, 16u8, 20u8, 3u8, 0x78u8, 0u8, 0u8, 0u8, 1u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8 ] as *const u8, &() ).unwrap(); // Characters outside the valid ranges are invalid Test::check_bytes( &[ 0u8, 0u8, 0u8, 0u8, 0x00u8, 0xd8u8, 0u8, 0u8, 1u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8 ] as *const u8, &() ).unwrap_err(); Test::check_bytes( &[ 0u8, 0u8, 0u8, 0u8, 0x00u8, 0x00u8, 0x11u8, 0u8, 1u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8 ] as *const u8, &() ).unwrap_err(); // 0 is a valid boolean value (false) but 2 is not Test::check_bytes( &[ 0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 0u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8 ] as *const u8, &() ).unwrap(); Test::check_bytes( &[ 0u8, 0u8, 0u8, 0u8, 0x78u8, 0u8, 0u8, 0u8, 2u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8, 255u8 ] as *const u8, &() ).unwrap_err(); }
Features
const_generics
: Extends the implementations ofCheckBytes
to to all arrays and not just arrays up to length 32.silent
: Silently consumes nested errors in#![no_std]
instead of printing them to stderr.std
: Enables standard library support.
By default, the std
feature is enabled.
Macros
offset_of | Calculates the offset of the specified field from the start of the named struct. |
Structs
ArrayCheckError | An error resulting from an invalid array. |
BoolCheckError | An error resulting from an invalid boolean. |
CharCheckError | An error resulting from an invalid character. |
ErrorSink | An error that consumes source errors and may log to stderr. |
StructCheckError | An error resulting from an invalid struct. |
TupleStructCheckError | An error resulting from an invalid tuple struct. |
Enums
CheckBufferError | An error resulting from an invalid buffer. |
EnumCheckError | An error resulting from an invalid enum. |
Tuple1CheckError | An error resulting from an invalid tuple. |
Tuple2CheckError | An error resulting from an invalid tuple. |
Tuple3CheckError | An error resulting from an invalid tuple. |
Tuple4CheckError | An error resulting from an invalid tuple. |
Tuple5CheckError | An error resulting from an invalid tuple. |
Tuple6CheckError | An error resulting from an invalid tuple. |
Tuple7CheckError | An error resulting from an invalid tuple. |
Tuple8CheckError | An error resulting from an invalid tuple. |
Tuple9CheckError | An error resulting from an invalid tuple. |
Tuple10CheckError | An error resulting from an invalid tuple. |
Tuple11CheckError | An error resulting from an invalid tuple. |
Tuple12CheckError | An error resulting from an invalid tuple. |
Unreachable | An error that cannot be produced. |
Traits
CheckBytes | A type that can validate whether some bytes represent a valid value. |
Context | A context that can provide some typed context for validating types. |
Functions
check_buffer | Checks whether a valid value of the given type is located in the given buffer at the given position. |
Type Definitions
DefaultError | The default error type that must be convertible from all other error types. |
Derive Macros
CheckBytes | Derives |