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 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

Guard

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