pub unsafe trait IntoBytes {
// Provided methods
fn as_bytes(&self) -> &[u8] ⓘ
where Self: Immutable { ... }
fn as_mut_bytes(&mut self) -> &mut [u8] ⓘ
where Self: FromBytes { ... }
fn write_to(
&self,
dst: &mut [u8],
) -> Result<(), SizeError<&Self, &mut [u8]>>
where Self: Immutable { ... }
fn write_to_prefix(
&self,
dst: &mut [u8],
) -> Result<(), SizeError<&Self, &mut [u8]>>
where Self: Immutable { ... }
fn write_to_suffix(
&self,
dst: &mut [u8],
) -> Result<(), SizeError<&Self, &mut [u8]>>
where Self: Immutable { ... }
fn write_to_io<W>(&self, dst: W) -> Result<(), Error>
where Self: Immutable,
W: Write { ... }
}Expand description
Types that can be converted to an immutable slice of initialized bytes.
Any IntoBytes type can be converted to a slice of initialized bytes of the
same size. This is useful for efficiently serializing structured data as raw
bytes.
§Implementation
Do not implement this trait yourself! Instead, use
#[derive(IntoBytes)]; e.g.:
#[derive(IntoBytes)]
#[repr(C)]
struct MyStruct {
...
}
#[derive(IntoBytes)]
#[repr(u8)]
enum MyEnum {
...
}This derive performs a sophisticated, compile-time safety analysis to
determine whether a type is IntoBytes. See the derive
documentation for guidance on how to interpret error messages
produced by the derive’s analysis.
§Safety
This section describes what is required in order for T: IntoBytes, and
what unsafe code may assume of such types. If you don’t plan on implementing
IntoBytes manually, and you don’t plan on writing unsafe code that
operates on IntoBytes types, then you don’t need to read this section.
If T: IntoBytes, then unsafe code may assume that it is sound to treat any
t: T as an immutable [u8] of length size_of_val(t). If a type is
marked as IntoBytes which violates this contract, it may cause undefined
behavior.
#[derive(IntoBytes)] only permits types which satisfy these
requirements.
Provided Methods§
Sourcefn as_bytes(&self) -> &[u8] ⓘwhere
Self: Immutable,
fn as_bytes(&self) -> &[u8] ⓘwhere
Self: Immutable,
Gets the bytes of this value.
§Examples
use zerocopy::IntoBytes;
#[derive(IntoBytes, Immutable)]
#[repr(C)]
struct PacketHeader {
src_port: [u8; 2],
dst_port: [u8; 2],
length: [u8; 2],
checksum: [u8; 2],
}
let header = PacketHeader {
src_port: [0, 1],
dst_port: [2, 3],
length: [4, 5],
checksum: [6, 7],
};
let bytes = header.as_bytes();
assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 6, 7]);Sourcefn as_mut_bytes(&mut self) -> &mut [u8] ⓘwhere
Self: FromBytes,
fn as_mut_bytes(&mut self) -> &mut [u8] ⓘwhere
Self: FromBytes,
Gets the bytes of this value mutably.
§Examples
use zerocopy::IntoBytes;
#[derive(FromBytes, IntoBytes, Immutable)]
#[repr(C)]
struct PacketHeader {
src_port: [u8; 2],
dst_port: [u8; 2],
length: [u8; 2],
checksum: [u8; 2],
}
let mut header = PacketHeader {
src_port: [0, 1],
dst_port: [2, 3],
length: [4, 5],
checksum: [6, 7],
};
let bytes = header.as_mut_bytes();
assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 6, 7]);
bytes.reverse();
assert_eq!(header, PacketHeader {
src_port: [7, 6],
dst_port: [5, 4],
length: [3, 2],
checksum: [1, 0],
});§ Code Generation
See IntoBytes::as_bytes.
Sourcefn write_to(&self, dst: &mut [u8]) -> Result<(), SizeError<&Self, &mut [u8]>>where
Self: Immutable,
fn write_to(&self, dst: &mut [u8]) -> Result<(), SizeError<&Self, &mut [u8]>>where
Self: Immutable,
Writes a copy of self to dst.
If dst.len() != size_of_val(self), write_to returns Err.
§Examples
use zerocopy::IntoBytes;
#[derive(IntoBytes, Immutable)]
#[repr(C)]
struct PacketHeader {
src_port: [u8; 2],
dst_port: [u8; 2],
length: [u8; 2],
checksum: [u8; 2],
}
let header = PacketHeader {
src_port: [0, 1],
dst_port: [2, 3],
length: [4, 5],
checksum: [6, 7],
};
let mut bytes = [0, 0, 0, 0, 0, 0, 0, 0];
header.write_to(&mut bytes[..]);
assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 6, 7]);If too many or too few target bytes are provided, write_to returns
Err and leaves the target bytes unmodified:
let mut excessive_bytes = &mut [0u8; 128][..];
let write_result = header.write_to(excessive_bytes);
assert!(write_result.is_err());
assert_eq!(excessive_bytes, [0u8; 128]);Sourcefn write_to_prefix(
&self,
dst: &mut [u8],
) -> Result<(), SizeError<&Self, &mut [u8]>>where
Self: Immutable,
fn write_to_prefix(
&self,
dst: &mut [u8],
) -> Result<(), SizeError<&Self, &mut [u8]>>where
Self: Immutable,
Writes a copy of self to the prefix of dst.
write_to_prefix writes self to the first size_of_val(self) bytes
of dst. If dst.len() < size_of_val(self), it returns Err.
§Examples
use zerocopy::IntoBytes;
#[derive(IntoBytes, Immutable)]
#[repr(C)]
struct PacketHeader {
src_port: [u8; 2],
dst_port: [u8; 2],
length: [u8; 2],
checksum: [u8; 2],
}
let header = PacketHeader {
src_port: [0, 1],
dst_port: [2, 3],
length: [4, 5],
checksum: [6, 7],
};
let mut bytes = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
header.write_to_prefix(&mut bytes[..]);
assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 6, 7, 0, 0]);If insufficient target bytes are provided, write_to_prefix returns
Err and leaves the target bytes unmodified:
let mut insufficient_bytes = &mut [0, 0][..];
let write_result = header.write_to_suffix(insufficient_bytes);
assert!(write_result.is_err());
assert_eq!(insufficient_bytes, [0, 0]);Sourcefn write_to_suffix(
&self,
dst: &mut [u8],
) -> Result<(), SizeError<&Self, &mut [u8]>>where
Self: Immutable,
fn write_to_suffix(
&self,
dst: &mut [u8],
) -> Result<(), SizeError<&Self, &mut [u8]>>where
Self: Immutable,
Writes a copy of self to the suffix of dst.
write_to_suffix writes self to the last size_of_val(self) bytes of
dst. If dst.len() < size_of_val(self), it returns Err.
§Examples
use zerocopy::IntoBytes;
#[derive(IntoBytes, Immutable)]
#[repr(C)]
struct PacketHeader {
src_port: [u8; 2],
dst_port: [u8; 2],
length: [u8; 2],
checksum: [u8; 2],
}
let header = PacketHeader {
src_port: [0, 1],
dst_port: [2, 3],
length: [4, 5],
checksum: [6, 7],
};
let mut bytes = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
header.write_to_suffix(&mut bytes[..]);
assert_eq!(bytes, [0, 0, 0, 1, 2, 3, 4, 5, 6, 7]);
let mut insufficient_bytes = &mut [0, 0][..];
let write_result = header.write_to_suffix(insufficient_bytes);
assert!(write_result.is_err());
assert_eq!(insufficient_bytes, [0, 0]);If insufficient target bytes are provided, write_to_suffix returns
Err and leaves the target bytes unmodified:
let mut insufficient_bytes = &mut [0, 0][..];
let write_result = header.write_to_suffix(insufficient_bytes);
assert!(write_result.is_err());
assert_eq!(insufficient_bytes, [0, 0]);Sourcefn write_to_io<W>(&self, dst: W) -> Result<(), Error>
fn write_to_io<W>(&self, dst: W) -> Result<(), Error>
Writes a copy of self to an io::Write.
This is a shorthand for dst.write_all(self.as_bytes()), and is useful
for interfacing with operating system byte sinks (files, sockets, etc.).
§Examples
use zerocopy::{byteorder::big_endian::U16, FromBytes, IntoBytes};
use std::fs::File;
#[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
#[repr(C, packed)]
struct GrayscaleImage {
height: U16,
width: U16,
pixels: [U16],
}
let image = GrayscaleImage::ref_from_bytes(&[0, 0, 0, 0][..]).unwrap();
let mut file = File::create("image.bin").unwrap();
image.write_to_io(&mut file).unwrap();If the write fails, write_to_io returns Err and a partial write may
have occurred; e.g.:
let src = u128::MAX;
let mut dst = [0u8; 2];
let write_result = src.write_to_io(&mut dst[..]);
assert!(write_result.is_err());
assert_eq!(dst, [255, 255]);Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".