Module safe_transmute::guard

source ·
Expand description

The guard module exposes an API for memory boundary checking.

§Examples:

In order to check whether a value would fit in the given slice with no extra trailing bytes:

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

§Note

Regardless of the chosen strategy, guarded transmutation functions will always ensure that no out of bounds access is attempted. All functions will restrict the output to spatially safe portions of the input. The guard API exists to establish expectations in the conversion process.

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§