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 which are safe to treat as an immutable byte slice.
WARNING: Do not implement this trait yourself! Instead, use
#[derive(AsBytes)] (requires the derive Cargo feature).
AsBytes types can be safely viewed as a slice of bytes. In particular,
this means that, in any valid instance of the type, none of the bytes of the
instance are uninitialized. This precludes the following types:
- Structs with internal padding
- Unions in which not all variants have the same length
AsBytes is ignorant of byte order. For byte order-aware types, see the
[byteorder] module.
Custom Derive Errors
Due to the way that the custom derive for AsBytes is implemented, you may
get an error like this:
error[E0277]: the trait bound `HasPadding<Foo, true>: ShouldBe<false>` is not satisfied
--> lib.rs:23:10
|
1 | #[derive(AsBytes)]
| ^^^^^^^ the trait `ShouldBe<false>` is not implemented for `HasPadding<Foo, true>`
|
= help: the trait `ShouldBe<VALUE>` is implemented for `HasPadding<T, VALUE>`
This error indicates that the type being annotated has padding bytes, which
is illegal for AsBytes types. Consider reducing the alignment of some
fields by using types in the [byteorder] module, adding explicit struct
fields where those padding bytes would be, or using #[repr(packed)]. See
the Rust Reference’s page on type layout for more information
about type layout and padding.
Safety
This section describes what is required in order for T: AsBytes, and what
unsafe code may assume of such types. #[derive(AsBytes)] only permits
types which satisfy these requirements. 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: Tas 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 bothbandtto be live at the same time.
If a type is marked as AsBytes which violates this contract, it may cause
undefined behavior.
If a type has the following properties, then it is sound to implement
AsBytes for that type:
- If the type is a struct:
- It must have a defined representation (
repr(C),repr(transparent), orrepr(packed)). - All of its fields must satisfy the requirements to be
AsBytes(they do not actually have to beAsBytes). - Its layout must have no padding. This is always true for
repr(transparent)andrepr(packed). Forrepr(C), see the layout algorithm described in the Rust Reference.
- It must have a defined representation (
- If the type is an enum:
- It must be a C-like enum (meaning that all variants have no fields).
- It must have a defined representation (
reprsC,u8,u16,u32,u64,usize,i8,i16,i32,i64, orisize).
- The type must not contain any
UnsafeCells (this is required in order for it to be sound to construct a&[u8]and a&Tto the same region of memory). The type may contain references or pointers toUnsafeCells so long as those values can themselves be initialized from zeroes (AsBytesis not currently implemented for, e.g.,Option<&UnsafeCell<_>>, but it could be one day).
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.
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.
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.
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.
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.