Trait zerocopy::FromZeroes
source · pub unsafe trait FromZeroes {
// Provided methods
fn zero(&mut self) { ... }
fn new_zeroed() -> 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 aT. - Given
b: &[u8]whereb.len() == size_of::<T>(),bis aligned toalign_of::<T>(), andbcontains only zero bytes, it is sound to construct at: &Tat the same address asb, and it is sound for bothbandtto 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§
sourcefn zero(&mut self)
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]);sourcefn new_zeroed() -> Selfwhere
Self: Sized,
fn new_zeroed() -> Selfwhere
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]);