Module safe_transmute::guard

The guard module exposes an API for memory boundary checking.

Examples:

In order to check whether a value would fit in the given slice without extraneous space:

SingleValueGuard::check::<u32>(&[0x00, 0x01, 0x00, 0x02])?;

Different guard types implement different checking strategies. For example, the pedantic guard type PedanticGuard requires the slice to have space for at least one value, and not have extraneous bytes at the end.

PedanticGuard::check::<u16>(&[0xAA, 0xAA, 0xBB, 0xBB, 0xCC, 0xCC])?;

PermissiveGuard, on the other hand, will accept any memory slice.

PermissiveGuard::check::<i16>(b"covfefe")?;

If the check fails, the resulting GuardError value describes why.

assert_eq!(PedanticGuard::check::<i16>(b"covfefe"),
           Err(GuardError {
               required: 2,
               actual: 7,
               reason: ErrorReason::InexactByteCount,
           }));

Regardless of the chosen strategy, guarded transmutation functions will always ensure that no out of bounds access is attempted, usually by restricting the output to spatially safe portions of the input.

Structs

AllOrNothingGuard

An all-or-nothing guard: The byte slice should not have extraneous data, but can be empty, unlike PedanticGuard.

PedanticGuard

Pedantic guard: The byte slice must have at least enough bytes to fill a single instance of a type, and should not have extraneous data.

PermissiveGuard

Permissive guard: The resulting slice would have as many instances of a type as will fit, rounded down. Therefore, this guard will never yield an error.

SingleManyGuard

A single-or-many guard: The byte slice must have at least enough bytes to fill a single instance of a type, and extraneous data is ignored.

SingleValueGuard

Single value guard: The byte slice must have exactly enough bytes to fill a single instance of a type.

Traits

Guard

The trait describes types which define boundary checking strategies. See the module-level documentation for more details.