Trait FromZeros

pub unsafe trait FromZeros: TryFromBytes {
    // 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 FromZeros 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.

Warning: Padding bytes

Note that, when a value is moved or copied, only the non-padding bytes of that value are guaranteed to be preserved. It is unsound to assume that values written to padding bytes are preserved after a move or copy. For more details, see the FromBytes docs.

Implementation

Do not implement this trait yourself! Instead, use #[derive(FromZeros)]; e.g.:

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

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

#[derive(FromZeros, Immutable)]
union MyUnion {
    ...
}

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

Safety

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

If T: FromZeros, then unsafe code may assume that it is sound to produce a T whose bytes are all initialized to zero. If a type is marked as FromZeros which violates this contract, it may cause undefined behavior.

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

Provided Methods

fn zero(&mut self)

Overwrites self with zeros.

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(FromZeros)]
#[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(FromZeros)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

let header: PacketHeader = FromZeros::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]);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl FromZeros for Option<NonZeroI8>

impl FromZeros for Option<NonZeroI16>

impl FromZeros for Option<NonZeroI32>

impl FromZeros for Option<NonZeroI64>

impl FromZeros for Option<NonZeroI128>

impl FromZeros for Option<NonZeroIsize>

impl FromZeros for Option<NonZeroU8>

impl FromZeros for Option<NonZeroU16>

impl FromZeros for Option<NonZeroU32>

impl FromZeros for Option<NonZeroU64>

impl FromZeros for Option<NonZeroU128>

impl FromZeros for Option<NonZeroUsize>

impl FromZeros for bool

impl FromZeros for char

impl FromZeros for f32

impl FromZeros for f64

impl FromZeros for i8

impl FromZeros for i16

impl FromZeros for i32

impl FromZeros for i64

impl FromZeros for i128

impl FromZeros for isize

impl FromZeros for str

impl FromZeros for u8

impl FromZeros for u16

impl FromZeros for u32

impl FromZeros for u64

impl FromZeros for u128

impl FromZeros for ()

impl FromZeros for usize

impl FromZeros for __m128

Available on x86-64 and crate feature simd only.

impl FromZeros for __m128d

Available on x86-64 and crate feature simd only.

impl FromZeros for __m128i

Available on x86-64 and crate feature simd only.

impl FromZeros for __m256

Available on x86-64 and crate feature simd only.

impl FromZeros for __m256d

Available on x86-64 and crate feature simd only.

impl FromZeros for __m256i

Available on x86-64 and crate feature simd only.

impl FromZeros for AtomicBool

Available on target_has_atomic="8" and rust="1.60.0" only.

impl FromZeros for AtomicI8

Available on target_has_atomic="8" and rust="1.60.0" only.

impl FromZeros for AtomicI16

Available on target_has_atomic="16" and rust="1.60.0" only.

impl FromZeros for AtomicI32

Available on target_has_atomic="32" and rust="1.60.0" only.

impl FromZeros for AtomicI64

Available on target_has_atomic="64" and rust="1.60.0" only.

impl FromZeros for AtomicIsize

Available on target_has_atomic="ptr" and rust="1.60.0" only.

impl FromZeros for AtomicU8

Available on target_has_atomic="8" and rust="1.60.0" only.

impl FromZeros for AtomicU16

Available on target_has_atomic="16" and rust="1.60.0" only.

impl FromZeros for AtomicU32

Available on target_has_atomic="32" and rust="1.60.0" only.

impl FromZeros for AtomicU64

Available on target_has_atomic="64" and rust="1.60.0" only.

impl FromZeros for AtomicUsize

Available on target_has_atomic="ptr" and rust="1.60.0" only.

impl<A, B, C, D, E, F, G, H, I, J, K, L, M> FromZeros 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> FromZeros 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> FromZeros 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> FromZeros 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> FromZeros 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> FromZeros 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> FromZeros for Option<fn(_: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<D, E, F, G, H, I, J, K, L, M> FromZeros 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> FromZeros for Option<fn(_: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

impl<T> FromZeros for Option<&T>

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

impl<T> FromZeros for Option<NonNull<T>>

impl<T> FromZeros for *const T

impl<T> FromZeros for *mut T

impl<T> FromZeros for AtomicPtr<T>

Available on target_has_atomic="ptr" and rust="1.60.0" only.

impl<T> FromZeros for MaybeUninit<T>

impl<T: FromZeros> FromZeros for [T]

impl<T: FromZeros> FromZeros for Wrapping<T>

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

impl<T: ?Sized + FromZeros> FromZeros for UnsafeCell<T>

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

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

Implementors

impl<O> FromZeros for F32<O>

impl<O> FromZeros for F64<O>

impl<O> FromZeros for I16<O>

impl<O> FromZeros for I32<O>

impl<O> FromZeros for I64<O>

impl<O> FromZeros for I128<O>

impl<O> FromZeros for Isize<O>

impl<O> FromZeros for U16<O>

impl<O> FromZeros for U32<O>

impl<O> FromZeros for U64<O>

impl<O> FromZeros for U128<O>

impl<O> FromZeros for Usize<O>

impl<T: FromZeros> FromZeros for Unalign<T>