Trait zerocopy::FromZeroes

source ·
pub unsafe trait FromZeroes {
    // Provided methods
    fn zero(&mut self) { ... }
    fn new_zeroed() -> Self
       where Self: Sized { ... }
    fn new_box_zeroed() -> Box<Self>
       where Self: Sized { ... }
    fn new_box_slice_zeroed(len: usize) -> Box<[Self]>
       where Self: Sized { ... }
    fn new_vec_zeroed(len: usize) -> Vec<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]);
source

fn new_box_zeroed() -> Box<Self>
where Self: Sized,

Available on crate feature alloc only.

Creates a Box<Self> from zeroed bytes.

This function is useful for allocating large values on the heap and zero-initializing them, without ever creating a temporary instance of Self on the stack. For example, <[u8; 1048576]>::new_box_zeroed() will allocate [u8; 1048576] directly on the heap; it does not require storing [u8; 1048576] in a temporary variable on the stack.

On systems that use a heap implementation that supports allocating from pre-zeroed memory, using new_box_zeroed (or related functions) may have performance benefits.

Note that Box<Self> can be converted to Arc<Self> and other container types without reallocation.

§Panics

Panics if allocation of size_of::<Self>() bytes fails.

source

fn new_box_slice_zeroed(len: usize) -> Box<[Self]>
where Self: Sized,

Available on crate feature alloc only.

Creates a Box<[Self]> (a boxed slice) from zeroed bytes.

This function is useful for allocating large values of [Self] on the heap and zero-initializing them, without ever creating a temporary instance of [Self; _] on the stack. For example, u8::new_box_slice_zeroed(1048576) will allocate the slice directly on the heap; it does not require storing the slice on the stack.

On systems that use a heap implementation that supports allocating from pre-zeroed memory, using new_box_slice_zeroed may have performance benefits.

If Self is a zero-sized type, then this function will return a Box<[Self]> that has the correct len. Such a box cannot contain any actual information, but its len() property will report the correct value.

§Panics
  • Panics if size_of::<Self>() * len overflows.
  • Panics if allocation of size_of::<Self>() * len bytes fails.
source

fn new_vec_zeroed(len: usize) -> Vec<Self>
where Self: Sized,

Available on crate feature new_vec_zeroed only.

Creates a Vec<Self> from zeroed bytes.

This function is useful for allocating large values of Vecs and zero-initializing them, without ever creating a temporary instance of [Self; _] (or many temporary instances of Self) on the stack. For example, u8::new_vec_zeroed(1048576) will allocate directly on the heap; it does not require storing intermediate values on the stack.

On systems that use a heap implementation that supports allocating from pre-zeroed memory, using new_vec_zeroed may have performance benefits.

If Self is a zero-sized type, then this function will return a Vec<Self> that has the correct len. Such a Vec cannot contain any actual information, but its len() property will report the correct value.

§Panics
  • Panics if size_of::<Self>() * len overflows.
  • Panics if allocation of size_of::<Self>() * len bytes fails.

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

Available on x86-64 and crate feature simd only.
source§

impl FromZeroes for __m128d

Available on x86-64 and crate feature simd only.
source§

impl FromZeroes for __m128i

Available on x86-64 and crate feature simd only.
source§

impl FromZeroes for __m256

Available on x86-64 and crate feature simd only.
source§

impl FromZeroes for __m256d

Available on x86-64 and crate feature simd only.
source§

impl FromZeroes for __m256i

Available on x86-64 and crate feature simd only.
source§

impl FromZeroes for __m512

Available on crate feature simd-nightly and x86-64 and crate feature simd only.
source§

impl FromZeroes for __m512bh

Available on crate feature simd-nightly and x86-64 and crate feature simd only.
source§

impl FromZeroes for __m512d

Available on crate feature simd-nightly and x86-64 and crate feature simd only.
source§

impl FromZeroes for __m512i

Available on crate feature simd-nightly and x86-64 and crate feature simd only.
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<Box<T>>

Available on crate feature alloc only.
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§

source§

impl<O> FromZeroes for F32<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for F64<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for I16<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for I32<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for I64<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for I128<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for U16<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for U32<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for U64<O>

Available on crate feature byteorder only.
source§

impl<O> FromZeroes for U128<O>

Available on crate feature byteorder only.
source§

impl<T> FromZeroes for Unalign<T>
where T: FromZeroes,