Trait FromZeroes

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

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

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]);

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

impl FromZeroes for Option<NonZeroI8>

impl FromZeroes for Option<NonZeroI16>

impl FromZeroes for Option<NonZeroI32>

impl FromZeroes for Option<NonZeroI64>

impl FromZeroes for Option<NonZeroI128>

impl FromZeroes for Option<NonZeroIsize>

impl FromZeroes for Option<NonZeroU8>

impl FromZeroes for Option<NonZeroU16>

impl FromZeroes for Option<NonZeroU32>

impl FromZeroes for Option<NonZeroU64>

impl FromZeroes for Option<NonZeroU128>

impl FromZeroes for Option<NonZeroUsize>

impl FromZeroes for bool

impl FromZeroes for char

impl FromZeroes for f32

impl FromZeroes for f64

impl FromZeroes for i8

impl FromZeroes for i16

impl FromZeroes for i32

impl FromZeroes for i64

impl FromZeroes for i128

impl FromZeroes for isize

impl FromZeroes for str

impl FromZeroes for u8

impl FromZeroes for u16

impl FromZeroes for u32

impl FromZeroes for u64

impl FromZeroes for u128

impl FromZeroes for ()

impl FromZeroes for usize

impl FromZeroes for __m128

Available on x86-64 and crate feature simd only.

impl FromZeroes for __m128d

Available on x86-64 and crate feature simd only.

impl FromZeroes for __m128i

Available on x86-64 and crate feature simd only.

impl FromZeroes for __m256

Available on x86-64 and crate feature simd only.

impl FromZeroes for __m256d

Available on x86-64 and crate feature simd only.

impl FromZeroes for __m256i

Available on x86-64 and crate feature simd only.

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>

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>

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>

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>

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>

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>

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>

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>

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

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>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

impl<T> FromZeroes for Option<&T>

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

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

impl<T> FromZeroes for *const T

impl<T> FromZeroes for *mut T

impl<T: FromZeroes> FromZeroes for [T]

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

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

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

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

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

Implementors

impl<O> FromZeroes for F32<O>

where [u8; 4]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for F64<O>

where [u8; 8]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for I16<O>

where [u8; 2]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for I32<O>

where [u8; 4]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for I64<O>

where [u8; 8]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for I128<O>

where [u8; 16]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for U16<O>

where [u8; 2]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for U32<O>

where [u8; 4]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for U64<O>

where [u8; 8]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<O> FromZeroes for U128<O>

where [u8; 16]: FromZeroes, PhantomData<O>: FromZeroes,

Available on crate feature byteorder only.

impl<T> FromZeroes for Unalign<T>

where T: FromZeroes,