pub unsafe trait AsBytes {
// Provided methods
fn as_bytes(&self) -> &[u8] ⓘ { ... }
fn as_bytes_mut(&mut self) -> &mut [u8] ⓘ
where Self: FromBytes { ... }
fn write_to(&self, bytes: &mut [u8]) -> Option<()> { ... }
fn write_to_prefix(&self, bytes: &mut [u8]) -> Option<()> { ... }
fn write_to_suffix(&self, bytes: &mut [u8]) -> Option<()> { ... }
}
Expand description
Types that can be viewed as an immutable slice of initialized bytes.
Any AsBytes
type can be viewed as 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(AsBytes)]
(requires the derive
Cargo feature); e.g.:
#[derive(AsBytes)]
#[repr(C)]
struct MyStruct {
...
}
#[derive(AsBytes)]
#[repr(u8)]
enum MyEnum {
...
}
#[derive(AsBytes)]
#[repr(C)]
union MyUnion {
...
}
This derive performs a sophisticated, compile-time safety analysis to
determine whether a type is AsBytes
. 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: AsBytes
, and
what unsafe code may assume of such types. If you don’t plan on implementing
AsBytes
manually, and you don’t plan on writing unsafe code that
operates on AsBytes
types, then you don’t need to read this section.
If T: AsBytes
, then unsafe code may assume that:
- It is sound to treat any
t: T
as an immutable[u8]
of lengthsize_of_val(t)
. - Given
t: &T
, it is sound to construct ab: &[u8]
whereb.len() == size_of_val(t)
at the same address ast
, and it is sound for bothb
andt
to be live at the same time.
If a type is marked as AsBytes
which violates this contract, it may cause
undefined behavior.
#[derive(AsBytes)]
only permits types which satisfy these
requirements.
Provided Methods§
sourcefn as_bytes(&self) -> &[u8] ⓘ
fn as_bytes(&self) -> &[u8] ⓘ
Gets the bytes of this value.
as_bytes
provides access to the bytes of this value as an immutable
byte slice.
§Examples
use zerocopy::AsBytes;
#[derive(AsBytes)]
#[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_bytes_mut(&mut self) -> &mut [u8] ⓘwhere
Self: FromBytes,
fn as_bytes_mut(&mut self) -> &mut [u8] ⓘwhere
Self: FromBytes,
Gets the bytes of this value mutably.
as_bytes_mut
provides access to the bytes of this value as a mutable
byte slice.
§Examples
use zerocopy::AsBytes;
#[derive(AsBytes, FromZeroes, FromBytes)]
#[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_bytes_mut();
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],
});
sourcefn write_to(&self, bytes: &mut [u8]) -> Option<()>
fn write_to(&self, bytes: &mut [u8]) -> Option<()>
Writes a copy of self
to bytes
.
If bytes.len() != size_of_val(self)
, write_to
returns None
.
§Examples
use zerocopy::AsBytes;
#[derive(AsBytes)]
#[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
None
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_none());
assert_eq!(excessive_bytes, [0u8; 128]);
sourcefn write_to_prefix(&self, bytes: &mut [u8]) -> Option<()>
fn write_to_prefix(&self, bytes: &mut [u8]) -> Option<()>
Writes a copy of self
to the prefix of bytes
.
write_to_prefix
writes self
to the first size_of_val(self)
bytes
of bytes
. If bytes.len() < size_of_val(self)
, it returns None
.
§Examples
use zerocopy::AsBytes;
#[derive(AsBytes)]
#[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
None
and leaves the target bytes unmodified:
let mut insufficent_bytes = &mut [0, 0][..];
let write_result = header.write_to_suffix(insufficent_bytes);
assert!(write_result.is_none());
assert_eq!(insufficent_bytes, [0, 0]);
sourcefn write_to_suffix(&self, bytes: &mut [u8]) -> Option<()>
fn write_to_suffix(&self, bytes: &mut [u8]) -> Option<()>
Writes a copy of self
to the suffix of bytes
.
write_to_suffix
writes self
to the last size_of_val(self)
bytes of
bytes
. If bytes.len() < size_of_val(self)
, it returns None
.
§Examples
use zerocopy::AsBytes;
#[derive(AsBytes)]
#[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 insufficent_bytes = &mut [0, 0][..];
let write_result = header.write_to_suffix(insufficent_bytes);
assert!(write_result.is_none());
assert_eq!(insufficent_bytes, [0, 0]);
If insufficient target bytes are provided, write_to_suffix
returns
None
and leaves the target bytes unmodified:
let mut insufficent_bytes = &mut [0, 0][..];
let write_result = header.write_to_suffix(insufficent_bytes);
assert!(write_result.is_none());
assert_eq!(insufficent_bytes, [0, 0]);