Trait dataview::Pod

source · [−]
pub unsafe trait Pod: 'static {
    fn zeroed() -> Self
    where
        Self: Sized,
    { ... }
    fn as_bytes(&self) -> &[u8] { ... }
    fn as_bytes_mut(&mut self) -> &mut [u8] { ... }
    fn as_data_view(&self) -> &DataView { ... }
    fn as_data_view_mut(&mut self) -> &mut DataView { ... }
    fn transmute<T: Pod>(self) -> T
    where
        Self: Sized,
    { ... }
    fn transmute_ref<T: Pod>(&self) -> &T
    where
        Self: Sized,
    { ... }
    fn transmute_mut<T: Pod>(&mut self) -> &mut T
    where
        Self: Sized,
    { ... }
}
Expand description

Defines types which can be safely transmuted from any bit pattern.

Examples

use dataview::Pod;

#[derive(Pod)]
#[repr(C)]
struct MyType {
	field: i32,
}

// Construct a zero initialized instance.
let mut inst = MyType::zeroed();
assert_eq!(inst.field, 0);

// Use the DataView interface to access the instance.
inst.as_data_view_mut().write(2, &255_u8);

// Returns a byte view over the instance.
assert_eq!(inst.as_bytes(), &[0, 0, 255, 0]);

Safety

It must be safe to transmute between any bit pattern (with length equal to the size of the type) and Self.

This is true for these primitive types: i8, i16, i32, i64, i128, u8, u16, u32, u64, u128, f32, f64 and the raw pointer types. Primitives such as str and bool are not pod because not every valid bit pattern is a valid instance of these types. Reference types are never pod.

Arrays and slices of pod types are also pod themselves.

When Pod is implemented for a user defined struct it must meet the following requirements:

  • Must be annotated with repr(C) or repr(transparent).
  • Must have every field’s type implement Pod itself.
  • Must not have any padding between its fields, define dummy fields to cover the padding.

Derive macro

To help with safely implementing this trait for structs, a proc-macro is provided to implement the Pod trait if the requirements are satisfied.

Provided Methods

Returns a zero-initialized instance of the type.

Returns the object’s memory as a byte slice.

Returns the object’s memory as a mutable byte slice.

Returns a data view into the object’s memory.

Returns a mutable data view into the object’s memory.

Safely transmutes to another type.

Panics

This method panics if sizeof(Self) != sizeof(T).

Ideally this method would assert the compatibility of the two types statically, unfortunately this is not currently possible. If Rust gains support for asserting this with where bounds the runtime panic may be changed to a compiletime error in the future.

Safely transmutes references to another type.

Panics

This method panics if sizeof(Self) != sizeof(T) or alignof(Self) < alignof(T).

Ideally this method would assert the compatibility of the two types statically, unfortunately this is not currently possible. If Rust gains support for asserting this with where bounds the runtime panic may be changed to a compiletime error in the future.

Safely transmutes references to another type.

Panics

This method panics if sizeof(Self) != sizeof(T) or alignof(Self) < alignof(T).

Ideally this method would assert the compatibility of the two types statically, unfortunately this is not currently possible. If Rust gains support for asserting this with where bounds the runtime panic may be changed to a compiletime error in the future.

Implementations on Foreign Types

Implementors