Trait FromZeros

Source

pub unsafe trait FromZeros: TryFromBytes {
    // Provided methods
    fn zero(&mut self) { ... }
    fn new_zeroed() -> Self
       where Self: Sized { ... }
    fn new_box_zeroed() -> Result<Box<Self>, AllocError>
       where Self: Sized { ... }
    fn new_box_zeroed_with_elems(count: usize) -> Result<Box<Self>, AllocError>
       where Self: KnownLayout<PointerMetadata = usize> { ... }
    fn new_vec_zeroed(len: usize) -> Result<Vec<Self>, AllocError>
       where Self: Sized { ... }
    fn extend_vec_zeroed(
        v: &mut Vec<Self>,
        additional: usize,
    ) -> Result<(), AllocError>
       where Self: Sized { ... }
    fn insert_vec_zeroed(
        v: &mut Vec<Self>,
        position: usize,
        additional: usize,
    ) -> Result<(), AllocError>
       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 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§

Source

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

Source

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

Source

fn new_box_zeroed() -> Result<Box<Self>, AllocError>
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.

§Errors

Returns an error on allocation failure. Allocation failure is guaranteed never to cause a panic or an abort.

Source

fn new_box_zeroed_with_elems(count: usize) -> Result<Box<Self>, AllocError>
where Self: KnownLayout<PointerMetadata = usize>,

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.

§Errors

Returns an error on allocation failure. Allocation failure is guaranteed never to cause a panic or an abort.

Source

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

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

§Errors

Returns an error on allocation failure. Allocation failure is guaranteed never to cause a panic or an abort.

Source

fn extend_vec_zeroed( v: &mut Vec<Self>, additional: usize, ) -> Result<(), AllocError>
where Self: Sized,

Available on rust="1.57.0" and crate feature alloc only.

Extends a Vec<Self> by pushing additional new items onto the end of the vector. The new items are initialized with zeros.

Source

fn insert_vec_zeroed( v: &mut Vec<Self>, position: usize, additional: usize, ) -> Result<(), AllocError>
where Self: Sized,

Available on rust="1.57.0" and crate feature alloc only.

Inserts additional new items into Vec<Self> at position. The new items are initialized with zeros.

§Panics

Panics if position > v.len().

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.

Trait FromZerosCopy item path

§Warning: Padding bytes

§Implementation

§Safety

Provided Methods§

fn zero(&mut self)

§Examples

fn new_zeroed() -> Selfwhere Self: Sized,

§Examples

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

§Errors

fn new_box_zeroed_with_elems(count: usize) -> Result<Box<Self>, AllocError>where Self: KnownLayout<PointerMetadata = usize>,

§Errors

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

§Errors

fn extend_vec_zeroed( v: &mut Vec<Self>, additional: usize, ) -> Result<(), AllocError>where Self: Sized,

fn insert_vec_zeroed( v: &mut Vec<Self>, position: usize, additional: usize, ) -> Result<(), AllocError>where Self: Sized,

§Panics

Dyn Compatibility§

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 f16

impl FromZeros for f32

impl FromZeros for f64

impl FromZeros for f128

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

impl FromZeros for __m128d

impl FromZeros for __m128i

impl FromZeros for __m256

impl FromZeros for __m256d

impl FromZeros for __m256i

impl FromZeros for __m512

impl FromZeros for __m512bh

impl FromZeros for __m512d

impl FromZeros for __m512i

impl FromZeros for AtomicBool

impl FromZeros for AtomicI8

impl FromZeros for AtomicI16

impl FromZeros for AtomicI32

impl FromZeros for AtomicI64

impl FromZeros for AtomicIsize

impl FromZeros for AtomicU8

impl FromZeros for AtomicU16

impl FromZeros for AtomicU32

impl FromZeros for AtomicU64

impl FromZeros for AtomicUsize

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>

Trait FromZeros

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

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

fn new_box_zeroed_with_elems(count: usize) -> Result<Box<Self>, AllocError>
where Self: KnownLayout<PointerMetadata = usize>,

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

fn extend_vec_zeroed( v: &mut Vec<Self>, additional: usize, ) -> Result<(), AllocError>
where Self: Sized,

fn insert_vec_zeroed( v: &mut Vec<Self>, position: usize, additional: usize, ) -> Result<(), AllocError>
where Self: Sized,

impl<O> FromZeros for F32<O>
where [u8; 4]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for F64<O>
where [u8; 8]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for I16<O>
where [u8; 2]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for I32<O>
where [u8; 4]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for I64<O>
where [u8; 8]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for I128<O>
where [u8; 16]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for Isize<O>
where [u8; 4]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for U16<O>
where [u8; 2]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for U32<O>
where [u8; 4]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for U64<O>
where [u8; 8]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for U128<O>
where [u8; 16]: FromZeros, PhantomData<O>: FromZeros,

impl<O> FromZeros for Usize<O>
where [u8; 4]: FromZeros, PhantomData<O>: FromZeros,

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