[][src]Crate safe_transmute

This crate contains checked implementations of transmutation procedures, some of which ensure memory safety.

Crate outline

The following modules are available:

This crate can be used in a no-std environment by disabling the std feature through specifying default-features = false on import.

Examples

View bytes as a series of u16s, with a single-many boundary guard (at least one value, extraneous bytes are allowed):

let bytes = &[0x00, 0x01, 0x12, 0x24,
              0x00]; // 1 spare byte
match transmute_many::<u16, SingleManyGuard>(bytes) {
    Ok(words) => {
        assert_eq!(words,
                   [u16::from_be(0x0001), u16::from_be(0x1224)]);
    },
    Err(Error::Unaligned(e)) => {
        // Copy needed, would otherwise trap on some archs
        let words = e.copy();
        assert_eq!(*words,
                   [u16::from_be(0x0001), u16::from_be(0x1224)]);
    },
    Err(e) => panic!("Unexpected error: {}", e),
}

Since one may not always be able to ensure that a slice of bytes is well aligned for reading data of different constraints, such as from u8 to u16, the operation may fail without a trivial way of preventing it.

As a remedy, the data can instead be copied byte-for-byte to a new vector, with the help of the try_copy!() macro.

let bytes = &[0x00, 0x01, 0x12, 0x24, 0x00];
let words = try_copy!(transmute_many::<u16, SingleManyGuard>(bytes));

assert_eq!(*words,
           [u16::from_be(0x0001), u16::from_be(0x1224)]);

View all bytes as a series of u16s:

// Assuming little-endian
let bytes = &[0x00, 0x01, 0x12, 0x34];
let words = try_copy!(transmute_many_pedantic::<u16>(bytes));

assert_eq!(*words, [0x0100, 0x3412]);

View a byte slice as a single f64:

assert_eq!(transmute_one::<f64>(
    &[0x00, 0x00, 0x00, 0x00,
      0x00, 0x00, 0x00, 0x40])?,
    2.0);

View a series of u16s as bytes:

assert_eq!(transmute_to_bytes(&[0x0001u16,
                                0x1234u16]),
           &[0x01, 0x00, 0x34, 0x12].le_to_native::<u16>());

Re-exports

pub use self::guard::SingleValueGuard;
pub use self::guard::PermissiveGuard;
pub use self::guard::SingleManyGuard;
pub use self::guard::PedanticGuard;
pub use self::guard::Guard;
pub use self::error::UnalignedError;
pub use self::error::ErrorReason;
pub use self::error::GuardError;
pub use self::error::Error;
pub use self::error::IncompatibleVecTargetError;
pub use self::trivial::TriviallyTransmutable;
pub use self::to_bytes::transmute_one_to_bytes;
pub use self::to_bytes::transmute_to_bytes;
pub use self::to_bytes::transmute_to_bytes_vec;
pub use self::bool::transmute_bool_vec_permissive;
pub use self::bool::transmute_bool_vec_pedantic;
pub use self::bool::transmute_bool_permissive;
pub use self::bool::transmute_bool_pedantic;

Modules

align

Alignment checking primitives.

base

Primitives for object and array transmutation.

bool

Functions for safe transmutation to bool.

error

Detectable and recoverable-from transmutation precondition errors.

guard

The guard module exposes an API for memory boundary checking.

to_bytes

Functions for transmutation from a concrete type to bytes.

trivial

Transmutation of trivial objects

util

Module containing various utility functions.

Macros

try_copy

Retrieve the result of a transmutation, copying the data if it could not be safely performed due to memory alignment constraints.

try_copy_unchecked

Retrieve the result of a non-trivial transmutation, copying the data if it could not be safely performed due to memory alignment constraints.

Functions

transmute_many

Transmute a byte slice into a sequence of values of the given type.

transmute_many_pedantic

Transmute a byte slice into a sequence of values of the given type.

transmute_many_permissive

Transmute a byte slice into a sequence of values of the given type.

transmute_one

Transmute a byte slice into a single instance of a trivially transmutable type.

transmute_one_pedantic

Transmute a byte slice into a single instance of a trivially transmutable type.

transmute_vec

Transform a vector into a vector of values with the given target type.