Trait IntoBytes

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 { ... }
}

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

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]);

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],
});

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]);

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 insufficent_bytes = &mut [0, 0][..];

let write_result = header.write_to_suffix(insufficent_bytes);

assert!(write_result.is_err());
assert_eq!(insufficent_bytes, [0, 0]);

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 insufficent_bytes = &mut [0, 0][..];

let write_result = header.write_to_suffix(insufficent_bytes);

assert!(write_result.is_err());
assert_eq!(insufficent_bytes, [0, 0]);

If insufficient target bytes are provided, write_to_suffix returns Err 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_err());
assert_eq!(insufficent_bytes, [0, 0]);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl IntoBytes for Option<NonZeroI8>

impl IntoBytes for Option<NonZeroI16>

impl IntoBytes for Option<NonZeroI32>

impl IntoBytes for Option<NonZeroI64>

impl IntoBytes for Option<NonZeroI128>

impl IntoBytes for Option<NonZeroIsize>

impl IntoBytes for Option<NonZeroU8>

impl IntoBytes for Option<NonZeroU16>

impl IntoBytes for Option<NonZeroU32>

impl IntoBytes for Option<NonZeroU64>

impl IntoBytes for Option<NonZeroU128>

impl IntoBytes for Option<NonZeroUsize>

impl IntoBytes for bool

impl IntoBytes for char

impl IntoBytes for f32

impl IntoBytes for f64

impl IntoBytes for i8

impl IntoBytes for i16

impl IntoBytes for i32

impl IntoBytes for i64

impl IntoBytes for i128

impl IntoBytes for isize

impl IntoBytes for str

impl IntoBytes for u8

impl IntoBytes for u16

impl IntoBytes for u32

impl IntoBytes for u64

impl IntoBytes for u128

impl IntoBytes for ()

impl IntoBytes for usize

impl IntoBytes for __m128

Available on x86-64 and crate feature simd only.

impl IntoBytes for __m128d

Available on x86-64 and crate feature simd only.

impl IntoBytes for __m128i

Available on x86-64 and crate feature simd only.

impl IntoBytes for __m256

Available on x86-64 and crate feature simd only.

impl IntoBytes for __m256d

Available on x86-64 and crate feature simd only.

impl IntoBytes for __m256i

Available on x86-64 and crate feature simd only.

impl IntoBytes for AtomicBool

Available on target_has_atomic="8" and rust="1.60.0" only.

impl IntoBytes for AtomicI8

Available on target_has_atomic="8" and rust="1.60.0" only.

impl IntoBytes for AtomicI16

Available on target_has_atomic="16" and rust="1.60.0" only.

impl IntoBytes for AtomicI32

Available on target_has_atomic="32" and rust="1.60.0" only.

impl IntoBytes for AtomicI64

Available on target_has_atomic="64" and rust="1.60.0" only.

impl IntoBytes for AtomicIsize

Available on target_has_atomic="ptr" and rust="1.60.0" only.

impl IntoBytes for AtomicU8

Available on target_has_atomic="8" and rust="1.60.0" only.

impl IntoBytes for AtomicU16

Available on target_has_atomic="16" and rust="1.60.0" only.

impl IntoBytes for AtomicU32

Available on target_has_atomic="32" and rust="1.60.0" only.

impl IntoBytes for AtomicU64

Available on target_has_atomic="64" and rust="1.60.0" only.

impl IntoBytes for AtomicUsize

Available on target_has_atomic="ptr" and rust="1.60.0" only.

impl IntoBytes for NonZeroI8

impl IntoBytes for NonZeroI16

impl IntoBytes for NonZeroI32

impl IntoBytes for NonZeroI64

impl IntoBytes for NonZeroI128

impl IntoBytes for NonZeroIsize

impl IntoBytes for NonZeroU8

impl IntoBytes for NonZeroU16

impl IntoBytes for NonZeroU32

impl IntoBytes for NonZeroU64

impl IntoBytes for NonZeroU128

impl IntoBytes for NonZeroUsize

impl<T: IntoBytes> IntoBytes for [T]

impl<T: IntoBytes> IntoBytes for Wrapping<T>

impl<T: IntoBytes, const N: usize> IntoBytes for [T; N]

impl<T: ?Sized + IntoBytes> IntoBytes for UnsafeCell<T>

impl<T: ?Sized + IntoBytes> IntoBytes for ManuallyDrop<T>

impl<T: ?Sized> IntoBytes for PhantomData<T>

Implementors

impl<O> IntoBytes for F32<O>

impl<O> IntoBytes for F64<O>

impl<O> IntoBytes for I16<O>

impl<O> IntoBytes for I32<O>

impl<O> IntoBytes for I64<O>

impl<O> IntoBytes for I128<O>

impl<O> IntoBytes for Isize<O>

impl<O> IntoBytes for U16<O>

impl<O> IntoBytes for U32<O>

impl<O> IntoBytes for U64<O>

impl<O> IntoBytes for U128<O>

impl<O> IntoBytes for Usize<O>

impl<T: IntoBytes> IntoBytes for Unalign<T>