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<B: ByteSliceMut>(&self, bytes: B) -> Option<()> { ... }
fn write_to_prefix<B: ByteSliceMut>(&self, bytes: B) -> Option<()> { ... }
fn write_to_suffix<B: ByteSliceMut>(&self, bytes: B) -> 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)].
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[E0080]: evaluation of constant value failed
--> lib.rs:1:10
|
1 | #[derive(AsBytes)]
| ^^^^^^^ attempt to divide by zero
This error means that the type being annotated has padding bytes, which is
illegal for AsBytes types. Consider either adding explicit struct fields
where those padding bytes would be or using #[repr(packed)].
Safety
If T: AsBytes, then unsafe code may assume that it is sound to treat any
instance of the type as an immutable [u8] of length size_of::<T>(). 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 safe 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 be
AsBytes - 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).
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<B: ByteSliceMut>(&self, bytes: B) -> Option<()>
fn write_to<B: ByteSliceMut>(&self, bytes: B) -> Option<()>
Writes a copy of self to bytes.
If bytes.len() != size_of_val(self), write_to returns None.
sourcefn write_to_prefix<B: ByteSliceMut>(&self, bytes: B) -> Option<()>
fn write_to_prefix<B: ByteSliceMut>(&self, bytes: B) -> 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<B: ByteSliceMut>(&self, bytes: B) -> Option<()>
fn write_to_suffix<B: ByteSliceMut>(&self, bytes: B) -> 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.