Trait zerocopy::AsBytes

source ·

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 length size_of_val(t).
Given t: &T, it is sound to construct a b: &[u8] where b.len() == size_of_val(t) at the same address as t, and it is sound for both b and t 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§

source

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

source

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

source

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

source

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

source

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

Object Safety§

This trait is not object safe.

Trait zerocopy::AsBytesCopy item path

§Implementation

§Safety

Provided Methods§

fn as_bytes(&self) -> &[u8]

§Examples

fn as_bytes_mut(&mut self) -> &mut [u8]where Self: FromBytes,

§Examples

fn write_to(&self, bytes: &mut [u8]) -> Option<()>

§Examples

fn write_to_prefix(&self, bytes: &mut [u8]) -> Option<()>

§Examples

fn write_to_suffix(&self, bytes: &mut [u8]) -> Option<()>

§Examples

Object Safety§

Implementations on Foreign Types§

impl AsBytes for Option<NonZeroI8>

impl AsBytes for Option<NonZeroI16>

impl AsBytes for Option<NonZeroI32>

impl AsBytes for Option<NonZeroI64>

impl AsBytes for Option<NonZeroI128>

impl AsBytes for Option<NonZeroIsize>

impl AsBytes for Option<NonZeroU8>

impl AsBytes for Option<NonZeroU16>

impl AsBytes for Option<NonZeroU32>

impl AsBytes for Option<NonZeroU64>

impl AsBytes for Option<NonZeroU128>

impl AsBytes for Option<NonZeroUsize>

impl AsBytes for bool

impl AsBytes for char

impl AsBytes for f32

impl AsBytes for f64

impl AsBytes for i8

impl AsBytes for i16

impl AsBytes for i32

impl AsBytes for i64

impl AsBytes for i128

impl AsBytes for isize

impl AsBytes for str

impl AsBytes for u8

impl AsBytes for u16

impl AsBytes for u32

impl AsBytes for u64

impl AsBytes for u128

impl AsBytes for ()

impl AsBytes for usize

impl AsBytes for __m128

impl AsBytes for __m128d

impl AsBytes for __m128i

impl AsBytes for __m256

impl AsBytes for __m256d

impl AsBytes for __m256i

impl AsBytes for __m512

impl AsBytes for __m512bh

impl AsBytes for __m512d

impl AsBytes for __m512i

impl AsBytes for NonZeroI8

impl AsBytes for NonZeroI16

impl AsBytes for NonZeroI32

impl AsBytes for NonZeroI64

impl AsBytes for NonZeroI128

impl AsBytes for NonZeroIsize

impl AsBytes for NonZeroU8

impl AsBytes for NonZeroU16

impl AsBytes for NonZeroU32

impl AsBytes for NonZeroU64

impl AsBytes for NonZeroU128

impl AsBytes for NonZeroUsize

impl<T: AsBytes> AsBytes for [T]

impl<T: AsBytes> AsBytes for Wrapping<T>

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

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

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

Implementors§

impl<O> AsBytes for F32<O>where [u8; 4]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for F64<O>where [u8; 8]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for I16<O>where [u8; 2]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for I32<O>where [u8; 4]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for I64<O>where [u8; 8]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for I128<O>where [u8; 16]: AsBytes, PhantomData<O>: AsBytes,

Trait zerocopy::AsBytes

fn as_bytes_mut(&mut self) -> &mut [u8]
where Self: FromBytes,

impl<O> AsBytes for F32<O>
where [u8; 4]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for F64<O>
where [u8; 8]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for I16<O>
where [u8; 2]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for I32<O>
where [u8; 4]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for I64<O>
where [u8; 8]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for I128<O>
where [u8; 16]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for U16<O>
where [u8; 2]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for U32<O>
where [u8; 4]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for U64<O>
where [u8; 8]: AsBytes, PhantomData<O>: AsBytes,

impl<O> AsBytes for U128<O>
where [u8; 16]: AsBytes, PhantomData<O>: AsBytes,

impl<T> AsBytes for Unalign<T>
where T: AsBytes,