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 0 bytes is a valid instance.
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§
Sourcefn zero(&mut self)
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]);Sourcefn new_zeroed() -> Selfwhere
Self: Sized,
fn new_zeroed() -> Selfwhere
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]);Sourcefn new_box_zeroed() -> Result<Box<Self>, AllocError>where
Self: Sized,
fn new_box_zeroed() -> Result<Box<Self>, AllocError>where
Self: Sized,
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.
Sourcefn new_box_zeroed_with_elems(count: usize) -> Result<Box<Self>, AllocError>where
Self: KnownLayout<PointerMetadata = usize>,
fn new_box_zeroed_with_elems(count: usize) -> Result<Box<Self>, AllocError>where
Self: KnownLayout<PointerMetadata = usize>,
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.
Sourcefn new_vec_zeroed(len: usize) -> Result<Vec<Self>, AllocError>where
Self: Sized,
fn new_vec_zeroed(len: usize) -> Result<Vec<Self>, AllocError>where
Self: Sized,
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.
Sourcefn extend_vec_zeroed(
v: &mut Vec<Self>,
additional: usize,
) -> Result<(), AllocError>where
Self: Sized,
fn extend_vec_zeroed(
v: &mut Vec<Self>,
additional: usize,
) -> Result<(), AllocError>where
Self: Sized,
Extends a Vec<Self> by pushing additional new items onto the end of
the vector. The new items are initialized with zeros.
Sourcefn insert_vec_zeroed(
v: &mut Vec<Self>,
position: usize,
additional: usize,
) -> Result<(), AllocError>where
Self: Sized,
fn insert_vec_zeroed(
v: &mut Vec<Self>,
position: usize,
additional: usize,
) -> Result<(), AllocError>where
Self: Sized,
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.