Trait zerocopy::FromZeroes

source ·
pub unsafe trait FromZeroes {
    // Provided methods
    fn zero(&mut self) { ... }
    fn new_zeroed() -> Self
       where Self: Sized { ... }
}
Expand description

Types for which a sequence of bytes all set to zero represents a valid instance of the type.

Any memory region of the appropriate length which is guaranteed to contain only zero bytes can be viewed as any FromZeroes type with no runtime overhead. This is useful whenever memory is known to be in a zeroed state, such memory returned from some allocation routines.

Implementation

Do not implement this trait yourself! Instead, use #[derive(FromZeroes)] (requires the derive Cargo feature); e.g.:

#[derive(FromZeroes)]
struct MyStruct {
    ...
}

#[derive(FromZeroes)]
#[repr(u8)]
enum MyEnum {
    ...
}

#[derive(FromZeroes)]
union MyUnion {
    ...
}

This derive performs a sophisticated, compile-time safety analysis to determine whether a type is FromZeroes.

Safety

This section describes what is required in order for T: FromZeroes, and what unsafe code may assume of such types. If you don’t plan on implementing FromZeroes manually, and you don’t plan on writing unsafe code that operates on FromZeroes types, then you don’t need to read this section.

If T: FromZeroes, then unsafe code may assume that:

  • It is sound to treat any initialized sequence of zero bytes of length size_of::<T>() as a T.
  • Given b: &[u8] where b.len() == size_of::<T>(), b is aligned to align_of::<T>(), and b contains only zero bytes, it is sound to construct a t: &T at the same address as b, and it is sound for both b and t to be live at the same time.

If a type is marked as FromZeroes which violates this contract, it may cause undefined behavior.

#[derive(FromZeroes)] only permits types which satisfy these requirements.

Provided Methods§

source

fn zero(&mut self)

Overwrites self with zeroes.

Sets every byte in self to 0. While this is similar to doing *self = Self::new_zeroed(), it differs in that zero does not semantically drop the current value and replace it with a new one - it simply modifies the bytes of the existing value.

Examples
#[derive(FromZeroes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

let mut header = PacketHeader {
    src_port: 100u16.to_be_bytes(),
    dst_port: 200u16.to_be_bytes(),
    length: 300u16.to_be_bytes(),
    checksum: 400u16.to_be_bytes(),
};

header.zero();

assert_eq!(header.src_port, [0, 0]);
assert_eq!(header.dst_port, [0, 0]);
assert_eq!(header.length, [0, 0]);
assert_eq!(header.checksum, [0, 0]);
source

fn new_zeroed() -> Self
where Self: Sized,

Creates an instance of Self from zeroed bytes.

Examples
#[derive(FromZeroes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

let header: PacketHeader = FromZeroes::new_zeroed();

assert_eq!(header.src_port, [0, 0]);
assert_eq!(header.dst_port, [0, 0]);
assert_eq!(header.length, [0, 0]);
assert_eq!(header.checksum, [0, 0]);

Implementations on Foreign Types§

source§

impl FromZeroes for Option<NonZeroI8>

source§

impl FromZeroes for Option<NonZeroI16>

source§

impl FromZeroes for Option<NonZeroI32>

source§

impl FromZeroes for Option<NonZeroI64>

source§

impl FromZeroes for Option<NonZeroI128>

source§

impl FromZeroes for Option<NonZeroIsize>

source§

impl FromZeroes for Option<NonZeroU8>

source§

impl FromZeroes for Option<NonZeroU16>

source§

impl FromZeroes for Option<NonZeroU32>

source§

impl FromZeroes for Option<NonZeroU64>

source§

impl FromZeroes for Option<NonZeroU128>

source§

impl FromZeroes for Option<NonZeroUsize>

source§

impl FromZeroes for bool

source§

impl FromZeroes for char

source§

impl FromZeroes for f32

source§

impl FromZeroes for f64

source§

impl FromZeroes for i8

source§

impl FromZeroes for i16

source§

impl FromZeroes for i32

source§

impl FromZeroes for i64

source§

impl FromZeroes for i128

source§

impl FromZeroes for isize

source§

impl FromZeroes for str

source§

impl FromZeroes for u8

source§

impl FromZeroes for u16

source§

impl FromZeroes for u32

source§

impl FromZeroes for u64

source§

impl FromZeroes for u128

source§

impl FromZeroes for ()

source§

impl FromZeroes for usize

source§

impl FromZeroes for __m128

source§

impl FromZeroes for __m128d

source§

impl FromZeroes for __m128i

source§

impl FromZeroes for __m256

source§

impl FromZeroes for __m256d

source§

impl FromZeroes for __m256i

source§

impl<A, B, C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: A, _: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<A, B, C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: A, _: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<B, C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<B, C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<C, D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<D, E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<E, F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<E, F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<F, G, H, I, J, K, L, M> FromZeroes for Option<fn(_: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<F, G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<G, H, I, J, K, L, M> FromZeroes for Option<fn(_: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<G, H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: G, _: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<H, I, J, K, L, M> FromZeroes for Option<fn(_: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<H, I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: H, _: I, _: J, _: K, _: L) -> M>

source§

impl<I, J, K, L, M> FromZeroes for Option<fn(_: I, _: J, _: K, _: L) -> M>

source§

impl<I, J, K, L, M> FromZeroes for Option<extern "C" fn(_: I, _: J, _: K, _: L) -> M>

source§

impl<J, K, L, M> FromZeroes for Option<fn(_: J, _: K, _: L) -> M>

source§

impl<J, K, L, M> FromZeroes for Option<extern "C" fn(_: J, _: K, _: L) -> M>

source§

impl<K, L, M> FromZeroes for Option<fn(_: K, _: L) -> M>

source§

impl<K, L, M> FromZeroes for Option<extern "C" fn(_: K, _: L) -> M>

source§

impl<L, M> FromZeroes for Option<fn(_: L) -> M>

source§

impl<L, M> FromZeroes for Option<extern "C" fn(_: L) -> M>

source§

impl<M> FromZeroes for Option<fn() -> M>

source§

impl<M> FromZeroes for Option<extern "C" fn() -> M>

source§

impl<T> FromZeroes for Option<&T>

source§

impl<T> FromZeroes for Option<&mut T>

source§

impl<T> FromZeroes for Option<NonNull<T>>

source§

impl<T> FromZeroes for *const T

source§

impl<T> FromZeroes for *mut T

source§

impl<T: FromZeroes> FromZeroes for [T]

source§

impl<T: FromZeroes> FromZeroes for Wrapping<T>

source§

impl<T: FromZeroes> FromZeroes for MaybeUninit<T>

source§

impl<T: ?Sized + FromZeroes> FromZeroes for ManuallyDrop<T>

source§

impl<T: ?Sized> FromZeroes for PhantomData<T>

source§

impl<const N: usize, T: FromZeroes> FromZeroes for [T; N]

Implementors§