Trait `FromBytes`

pub unsafe trait FromBytes: FromZeros

Types for which any bit pattern is valid.

Any memory region of the appropriate length which contains initialized bytes can be viewed as any FromBytes type with no runtime overhead. This is useful for efficiently parsing bytes as structured data.

Warning: Padding bytes

Note that, when a value is moved or copied, only the non-padding bytes of that value are guaranteed to be preserved. It is unsound to assume that values written to padding bytes are preserved after a move or copy. For example, the following is unsound:

use core::mem::{size_of, transmute};
use zerocopy::FromZeros;
# use zerocopy_derive::*;

// Assume `Foo` is a type with padding bytes.
#[derive(FromZeros, Default)]
struct Foo {
# /*
    ...
# */
}

let mut foo: Foo = Foo::default();
FromZeros::zero(&mut foo);
// UNSOUND: Although `FromZeros::zero` writes zeros to all bytes of `foo`,
// those writes are not guaranteed to be preserved in padding bytes when
// `foo` is moved, so this may expose padding bytes as `u8`s.
let foo_bytes: [u8; size_of::<Foo>()] = unsafe { transmute(foo) };

Implementation

Do not implement this trait yourself! Instead, use #[derive(FromBytes)]; e.g.:

# use zerocopy_derive::{FromBytes, Immutable};
#[derive(FromBytes)]
struct MyStruct {
# /*
    ...
# */
}

#[derive(FromBytes)]
#[repr(u8)]
enum MyEnum {
#   V00, V01, V02, V03, V04, V05, V06, V07, V08, V09, V0A, V0B, V0C, V0D, V0E,
#   V0F, V10, V11, V12, V13, V14, V15, V16, V17, V18, V19, V1A, V1B, V1C, V1D,
#   V1E, V1F, V20, V21, V22, V23, V24, V25, V26, V27, V28, V29, V2A, V2B, V2C,
#   V2D, V2E, V2F, V30, V31, V32, V33, V34, V35, V36, V37, V38, V39, V3A, V3B,
#   V3C, V3D, V3E, V3F, V40, V41, V42, V43, V44, V45, V46, V47, V48, V49, V4A,
#   V4B, V4C, V4D, V4E, V4F, V50, V51, V52, V53, V54, V55, V56, V57, V58, V59,
#   V5A, V5B, V5C, V5D, V5E, V5F, V60, V61, V62, V63, V64, V65, V66, V67, V68,
#   V69, V6A, V6B, V6C, V6D, V6E, V6F, V70, V71, V72, V73, V74, V75, V76, V77,
#   V78, V79, V7A, V7B, V7C, V7D, V7E, V7F, V80, V81, V82, V83, V84, V85, V86,
#   V87, V88, V89, V8A, V8B, V8C, V8D, V8E, V8F, V90, V91, V92, V93, V94, V95,
#   V96, V97, V98, V99, V9A, V9B, V9C, V9D, V9E, V9F, VA0, VA1, VA2, VA3, VA4,
#   VA5, VA6, VA7, VA8, VA9, VAA, VAB, VAC, VAD, VAE, VAF, VB0, VB1, VB2, VB3,
#   VB4, VB5, VB6, VB7, VB8, VB9, VBA, VBB, VBC, VBD, VBE, VBF, VC0, VC1, VC2,
#   VC3, VC4, VC5, VC6, VC7, VC8, VC9, VCA, VCB, VCC, VCD, VCE, VCF, VD0, VD1,
#   VD2, VD3, VD4, VD5, VD6, VD7, VD8, VD9, VDA, VDB, VDC, VDD, VDE, VDF, VE0,
#   VE1, VE2, VE3, VE4, VE5, VE6, VE7, VE8, VE9, VEA, VEB, VEC, VED, VEE, VEF,
#   VF0, VF1, VF2, VF3, VF4, VF5, VF6, VF7, VF8, VF9, VFA, VFB, VFC, VFD, VFE,
#   VFF,
# /*
    ...
# */
}

#[derive(FromBytes, Immutable)]
union MyUnion {
#   variant: u8,
# /*
    ...
# */
}

This derive performs a sophisticated, compile-time safety analysis to determine whether a type is FromBytes.

Safety

This section describes what is required in order for T: FromBytes, and what unsafe code may assume of such types. If you don't plan on implementing FromBytes manually, and you don't plan on writing unsafe code that operates on FromBytes types, then you don't need to read this section.

If T: FromBytes, then unsafe code may assume that it is sound to produce a T whose bytes are initialized to any sequence of valid u8s (in other words, any byte value which is not uninitialized). If a type is marked as FromBytes which violates this contract, it may cause undefined behavior.

#[derive(FromBytes)] only permits types which satisfy these requirements.

Provided Methods

fn ref_from_bytes(source: &[u8]) -> Result<&Self, CastError<&[u8], Self>> where Self: KnownLayout + Immutable,

Interprets the given source as a &Self.

This method attempts to return a reference to source interpreted as a Self. If the length of source is not a valid size of Self, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = ZSTy::ref_from_bytes(0u16.as_bytes()); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes, KnownLayout, Immutable)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

#[derive(FromBytes, KnownLayout, Immutable)]
#[repr(C)]
struct Packet {
    header: PacketHeader,
    body: [u8],
}

// These bytes encode a `Packet`.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11][..];

let packet = Packet::ref_from_bytes(bytes).unwrap();

assert_eq!(packet.header.src_port, [0, 1]);
assert_eq!(packet.header.dst_port, [2, 3]);
assert_eq!(packet.header.length, [4, 5]);
assert_eq!(packet.header.checksum, [6, 7]);
assert_eq!(packet.body, [8, 9, 10, 11]);

§ Code Generation

This abstraction is safe and cheap, but does not necessarily have zero runtime cost. The codegen you experience in practice will depend on optimization level, the layout of the destination type, and what the compiler can prove about the source.

The below examples illustrate typical codegen for increasingly complex types:

Sized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [u8; 2],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_static_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_bytes_static_size(source: &[u8]) -> Option<&format::LocoPacket> {
   zerocopy::FromBytes::ref_from_bytes(source).ok()
}

Assembly

bench_ref_from_bytes_static_size:
   mov ecx, edi
   and ecx, 1
   xor rsi, 6
   xor eax, eax
   or rsi, rcx
   cmove rax, rdi
   ret

Machine Code Analysis

Iterations:        100
Instructions:      700
Total Cycles:      240
Total uOps:        800

Dispatch Width:    4
uOps Per Cycle:    3.33
IPC:               2.92
Block RThroughput: 2.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        mov	ecx, edi
1      1     0.33                        and	ecx, 1
1      1     0.33                        xor	rsi, 6
1      0     0.25                        xor	eax, eax
1      1     0.33                        or	rsi, rcx
2      2     0.67                        cmove	rax, rdi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     2.33   2.33    -     2.34    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.01   0.98    -     0.01    -      -     mov	ecx, edi
-      -     0.02   0.66    -     0.32    -      -     and	ecx, 1
-      -     0.33   0.66    -     0.01    -      -     xor	rsi, 6
-      -      -      -      -      -      -      -     xor	eax, eax
-      -     0.98   0.02    -      -      -      -     or	rsi, rcx
-      -     0.99   0.01    -     1.00    -      -     cmove	rax, rdi
-      -      -      -      -     1.00    -      -     ret

Unsized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes, SplitAt)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [[u8; 2]],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_dynamic_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_bytes_dynamic_size(source: &[u8]) -> Option<&format::LocoPacket> {
   zerocopy::FromBytes::ref_from_bytes(source).ok()
}

Assembly

bench_ref_from_bytes_dynamic_size:
   mov rdx, rsi
   cmp rsi, 4
   setb al
   or al, dil
   test al, 1
   je .LBB5_2
   xor eax, eax
   ret
.LBB5_2:
   lea rcx, [rdx - 4]
   mov rsi, rcx
   and rsi, -2
   add rsi, 4
   shr rcx
   xor eax, eax
   cmp rdx, rsi
   cmove rdx, rcx
   cmove rax, rdi
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1800
Total Cycles:      704
Total uOps:        2000

Dispatch Width:    4
uOps Per Cycle:    2.84
IPC:               2.56
Block RThroughput: 5.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        mov	rdx, rsi
1      1     0.33                        cmp	rsi, 4
1      1     0.50                        setb	al
1      1     0.33                        or	al, dil
1      1     0.33                        test	al, 1
1      1     1.00                        je	.LBB5_2
1      0     0.25                        xor	eax, eax
1      1     1.00                  U     ret
1      1     0.50                        lea	rcx, [rdx - 4]
1      1     0.33                        mov	rsi, rcx
1      1     0.33                        and	rsi, -2
1      1     0.33                        add	rsi, 4
1      1     0.50                        shr	rcx
1      0     0.25                        xor	eax, eax
1      1     0.33                        cmp	rdx, rsi
2      2     0.67                        cmove	rdx, rcx
2      2     0.67                        cmove	rax, rdi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     5.97   5.98    -     6.05    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.97   0.01    -     0.02    -      -     mov	rdx, rsi
-      -     0.01   0.02    -     0.97    -      -     cmp	rsi, 4
-      -     0.03    -      -     0.97    -      -     setb	al
-      -     0.01   0.02    -     0.97    -      -     or	al, dil
-      -      -     0.98    -     0.02    -      -     test	al, 1
-      -      -      -      -     1.00    -      -     je	.LBB5_2
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -      -      -     1.00    -      -     ret
-      -     0.98   0.02    -      -      -      -     lea	rcx, [rdx - 4]
-      -     0.01   0.99    -      -      -      -     mov	rsi, rcx
-      -      -     0.98    -     0.02    -      -     and	rsi, -2
-      -     0.98   0.01    -     0.01    -      -     add	rsi, 4
-      -     0.99    -      -     0.01    -      -     shr	rcx
-      -      -      -      -      -      -      -     xor	eax, eax
-      -     0.02   0.97    -     0.01    -      -     cmp	rdx, rsi
-      -     0.99   0.99    -     0.02    -      -     cmove	rdx, rcx
-      -     0.98   0.99    -     0.03    -      -     cmove	rax, rdi
-      -      -      -      -     1.00    -      -     ret

Dynamically Padded

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

#[derive(FromBytes, KnownLayout, Immutable, SplitAt)]
#[repr(C, align(4))]
pub struct Packet<Magic> {
   magic_number: Magic,
   milk: u8,
   mug_size: u8,
   temperature: [u8; 5],
   marshmallows: [[u8; 3]],
}

/// A packet begining with the magic number `0xC0C0`.
pub type CocoPacket = Packet<C0C0>;

/// A packet beginning with any two initialized bytes.
pub type LocoPacket = Packet<[u8; 2]>;

Benchmark

#[path = "formats/coco_dynamic_padding.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_bytes_dynamic_padding(source: &[u8]) -> Option<&format::LocoPacket> {
   zerocopy::FromBytes::ref_from_bytes(source).ok()
}

Assembly

bench_ref_from_bytes_dynamic_padding:
   test dil, 3
   jne .LBB5_3
   movabs rax, 9223372036854775804
   and rax, rsi
   cmp rax, 9
   jb .LBB5_3
   add rax, -9
   movabs rcx, -6148914691236517205
   mul rcx
   shr rdx
   lea rax, [rdx + 2*rdx]
   or rax, 3
   add rax, 9
   cmp rsi, rax
   je .LBB5_4
.LBB5_3:
   xor edi, edi
   mov rdx, rsi
.LBB5_4:
   mov rax, rdi
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1900
Total Cycles:      645
Total uOps:        2000

Dispatch Width:    4
uOps Per Cycle:    3.10
IPC:               2.95
Block RThroughput: 5.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        test	dil, 3
1      1     1.00                        jne	.LBB5_3
1      1     0.33                        movabs	rax, 9223372036854775804
1      1     0.33                        and	rax, rsi
1      1     0.33                        cmp	rax, 9
1      1     1.00                        jb	.LBB5_3
1      1     0.33                        add	rax, -9
1      1     0.33                        movabs	rcx, -6148914691236517205
2      4     1.00                        mul	rcx
1      1     0.50                        shr	rdx
1      1     0.50                        lea	rax, [rdx + 2*rdx]
1      1     0.33                        or	rax, 3
1      1     0.33                        add	rax, 9
1      1     0.33                        cmp	rsi, rax
1      1     1.00                        je	.LBB5_4
1      0     0.25                        xor	edi, edi
1      1     0.33                        mov	rdx, rsi
1      1     0.33                        mov	rax, rdi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     6.32   6.33    -     6.35    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.64   0.35    -     0.01    -      -     test	dil, 3
-      -      -      -      -     1.00    -      -     jne	.LBB5_3
-      -     0.34   0.65    -     0.01    -      -     movabs	rax, 9223372036854775804
-      -     0.35   0.65    -      -      -      -     and	rax, rsi
-      -     0.33   0.34    -     0.33    -      -     cmp	rax, 9
-      -      -      -      -     1.00    -      -     jb	.LBB5_3
-      -     0.35    -      -     0.65    -      -     add	rax, -9
-      -     0.97   0.01    -     0.02    -      -     movabs	rcx, -6148914691236517205
-      -     1.00   1.00    -      -      -      -     mul	rcx
-      -     0.99    -      -     0.01    -      -     shr	rdx
-      -     0.33   0.67    -      -      -      -     lea	rax, [rdx + 2*rdx]
-      -     0.34   0.66    -      -      -      -     or	rax, 3
-      -     0.33   0.66    -     0.01    -      -     add	rax, 9
-      -     0.01   0.99    -      -      -      -     cmp	rsi, rax
-      -      -      -      -     1.00    -      -     je	.LBB5_4
-      -      -      -      -      -      -      -     xor	edi, edi
-      -     0.32   0.01    -     0.67    -      -     mov	rdx, rsi
-      -     0.02   0.34    -     0.64    -      -     mov	rax, rdi
-      -      -      -      -     1.00    -      -     ret

fn ref_from_prefix(source: &[u8]) -> Result<(&Self, &[u8]), CastError<&[u8], Self>> where Self: KnownLayout + Immutable,

Interprets the prefix of the given source as a &Self without copying.

This method computes the largest possible size of Self that can fit in the leading bytes of source, then attempts to return both a reference to those bytes interpreted as a Self, and a reference to the remaining bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. See ref_from_prefix_with_elems, which does support such types. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = ZSTy::ref_from_prefix(0u16.as_bytes()); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes, KnownLayout, Immutable)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

#[derive(FromBytes, KnownLayout, Immutable)]
#[repr(C)]
struct Packet {
    header: PacketHeader,
    body: [[u8; 2]],
}

// These are more bytes than are needed to encode a `Packet`.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14][..];

let (packet, suffix) = Packet::ref_from_prefix(bytes).unwrap();

assert_eq!(packet.header.src_port, [0, 1]);
assert_eq!(packet.header.dst_port, [2, 3]);
assert_eq!(packet.header.length, [4, 5]);
assert_eq!(packet.header.checksum, [6, 7]);
assert_eq!(packet.body, [[8, 9], [10, 11], [12, 13]]);
assert_eq!(suffix, &[14u8][..]);

§ Code Generation

The below examples illustrate typical codegen for increasingly complex types:

Sized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [u8; 2],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_static_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_prefix_static_size(source: &[u8]) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_prefix(source) {
       Ok((packet, _rest)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_prefix_static_size:
   xor eax, eax
   cmp rsi, 6
   mov rcx, rdi
   cmovb rcx, rax
   test dil, 1
   cmove rax, rcx
   ret

Machine Code Analysis

Iterations:        100
Instructions:      700
Total Cycles:      274
Total uOps:        900

Dispatch Width:    4
uOps Per Cycle:    3.28
IPC:               2.55
Block RThroughput: 2.3


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      0     0.25                        xor	eax, eax
1      1     0.33                        cmp	rsi, 6
1      1     0.33                        mov	rcx, rdi
2      2     0.67                        cmovb	rcx, rax
1      1     0.33                        test	dil, 1
2      2     0.67                        cmove	rax, rcx
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     2.66   2.67    -     2.67    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -     0.01    -     0.99    -      -     cmp	rsi, 6
-      -     0.01   0.67    -     0.32    -      -     mov	rcx, rdi
-      -     1.00   0.99    -     0.01    -      -     cmovb	rcx, rax
-      -     0.66   0.01    -     0.33    -      -     test	dil, 1
-      -     0.99   0.99    -     0.02    -      -     cmove	rax, rcx
-      -      -      -      -     1.00    -      -     ret

Unsized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes, SplitAt)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [[u8; 2]],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_dynamic_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_prefix_dynamic_size(source: &[u8]) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_prefix(source) {
       Ok((packet, _rest)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_prefix_dynamic_size:
   xor edx, edx
   mov eax, 0
   test dil, 1
   jne .LBB5_4
   cmp rsi, 4
   jae .LBB5_3
   mov edx, 1
   xor eax, eax
   ret
.LBB5_3:
   add rsi, -4
   shr rsi
   mov rdx, rsi
   mov rax, rdi
.LBB5_4:
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1400
Total Cycles:      405
Total uOps:        1400

Dispatch Width:    4
uOps Per Cycle:    3.46
IPC:               3.46
Block RThroughput: 4.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      0     0.25                        xor	edx, edx
1      1     0.33                        mov	eax, 0
1      1     0.33                        test	dil, 1
1      1     1.00                        jne	.LBB5_4
1      1     0.33                        cmp	rsi, 4
1      1     1.00                        jae	.LBB5_3
1      1     0.33                        mov	edx, 1
1      0     0.25                        xor	eax, eax
1      1     1.00                  U     ret
1      1     0.33                        add	rsi, -4
1      1     0.50                        shr	rsi
1      1     0.33                        mov	rdx, rsi
1      1     0.33                        mov	rax, rdi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     3.99   3.99    -     4.02    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -      -      -      -      -      -     xor	edx, edx
-      -     0.01   0.98    -     0.01    -      -     mov	eax, 0
-      -     0.98   0.02    -      -      -      -     test	dil, 1
-      -      -      -      -     1.00    -      -     jne	.LBB5_4
-      -     0.02   0.98    -      -      -      -     cmp	rsi, 4
-      -      -      -      -     1.00    -      -     jae	.LBB5_3
-      -     0.98   0.01    -     0.01    -      -     mov	edx, 1
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -      -      -     1.00    -      -     ret
-      -     0.01   0.99    -      -      -      -     add	rsi, -4
-      -     1.00    -      -      -      -      -     shr	rsi
-      -      -     1.00    -      -      -      -     mov	rdx, rsi
-      -     0.99   0.01    -      -      -      -     mov	rax, rdi
-      -      -      -      -     1.00    -      -     ret

Dynamically Padded

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

#[derive(FromBytes, KnownLayout, Immutable, SplitAt)]
#[repr(C, align(4))]
pub struct Packet<Magic> {
   magic_number: Magic,
   milk: u8,
   mug_size: u8,
   temperature: [u8; 5],
   marshmallows: [[u8; 3]],
}

/// A packet begining with the magic number `0xC0C0`.
pub type CocoPacket = Packet<C0C0>;

/// A packet beginning with any two initialized bytes.
pub type LocoPacket = Packet<[u8; 2]>;

Benchmark

#[path = "formats/coco_dynamic_padding.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_prefix_dynamic_padding(source: &[u8]) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_prefix(source) {
       Ok((packet, _rest)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_prefix_dynamic_padding:
   xor edx, edx
   mov eax, 0
   test dil, 3
   je .LBB5_1
   ret
.LBB5_1:
   movabs rax, 9223372036854775804
   and rsi, rax
   cmp rsi, 9
   jae .LBB5_3
   mov edx, 1
   xor eax, eax
   ret
.LBB5_3:
   add rsi, -9
   movabs rcx, -6148914691236517205
   mov rax, rsi
   mul rcx
   shr rdx
   mov rax, rdi
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1900
Total Cycles:      608
Total uOps:        2000

Dispatch Width:    4
uOps Per Cycle:    3.29
IPC:               3.13
Block RThroughput: 5.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      0     0.25                        xor	edx, edx
1      1     0.33                        mov	eax, 0
1      1     0.33                        test	dil, 3
1      1     1.00                        je	.LBB5_1
1      1     1.00                  U     ret
1      1     0.33                        movabs	rax, 9223372036854775804
1      1     0.33                        and	rsi, rax
1      1     0.33                        cmp	rsi, 9
1      1     1.00                        jae	.LBB5_3
1      1     0.33                        mov	edx, 1
1      0     0.25                        xor	eax, eax
1      1     1.00                  U     ret
1      1     0.33                        add	rsi, -9
1      1     0.33                        movabs	rcx, -6148914691236517205
1      1     0.33                        mov	rax, rsi
2      4     1.00                        mul	rcx
1      1     0.50                        shr	rdx
1      1     0.33                        mov	rax, rdi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     6.00   6.00    -     6.00    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -      -      -      -      -      -     xor	edx, edx
-      -     0.01   0.98    -     0.01    -      -     mov	eax, 0
-      -     0.98   0.01    -     0.01    -      -     test	dil, 3
-      -      -      -      -     1.00    -      -     je	.LBB5_1
-      -      -      -      -     1.00    -      -     ret
-      -     0.01   0.99    -      -      -      -     movabs	rax, 9223372036854775804
-      -      -     1.00    -      -      -      -     and	rsi, rax
-      -      -     1.00    -      -      -      -     cmp	rsi, 9
-      -      -      -      -     1.00    -      -     jae	.LBB5_3
-      -     1.00    -      -      -      -      -     mov	edx, 1
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -      -      -     1.00    -      -     ret
-      -     0.02   0.02    -     0.96    -      -     add	rsi, -9
-      -     0.99   0.01    -      -      -      -     movabs	rcx, -6148914691236517205
-      -     0.01   0.99    -      -      -      -     mov	rax, rsi
-      -     1.00   1.00    -      -      -      -     mul	rcx
-      -     1.00    -      -      -      -      -     shr	rdx
-      -     0.98    -      -     0.02    -      -     mov	rax, rdi
-      -      -      -      -     1.00    -      -     ret

fn ref_from_suffix(source: &[u8]) -> Result<(&[u8], &Self), CastError<&[u8], Self>> where Self: Immutable + KnownLayout,

Interprets the suffix of the given bytes as a &Self.

This method computes the largest possible size of Self that can fit in the trailing bytes of source, then attempts to return both a reference to those bytes interpreted as a Self, and a reference to the preceding bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. See ref_from_suffix_with_elems, which does support such types. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = ZSTy::ref_from_suffix(0u16.as_bytes()); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct PacketTrailer {
    frame_check_sequence: [u8; 4],
}

// These are more bytes than are needed to encode a `PacketTrailer`.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (prefix, trailer) = PacketTrailer::ref_from_suffix(bytes).unwrap();

assert_eq!(prefix, &[0, 1, 2, 3, 4, 5][..]);
assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

§ Code Generation

The below examples illustrate typical codegen for increasingly complex types:

Sized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [u8; 2],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_static_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_suffix_static_size(source: &[u8]) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_suffix(source) {
       Ok((_rest, packet)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_suffix_static_size:
   lea eax, [rsi + rdi]
   cmp rsi, 6
   setb cl
   or cl, al
   test cl, 1
   je .LBB5_2
   xor eax, eax
   ret
.LBB5_2:
   lea rax, [rdi + rsi]
   add rax, -6
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1100
Total Cycles:      338
Total uOps:        1100

Dispatch Width:    4
uOps Per Cycle:    3.25
IPC:               3.25
Block RThroughput: 3.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.50                        lea	eax, [rsi + rdi]
1      1     0.33                        cmp	rsi, 6
1      1     0.50                        setb	cl
1      1     0.33                        or	cl, al
1      1     0.33                        test	cl, 1
1      1     1.00                        je	.LBB5_2
1      0     0.25                        xor	eax, eax
1      1     1.00                  U     ret
1      1     0.50                        lea	rax, [rdi + rsi]
1      1     0.33                        add	rax, -6
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     3.32   3.33    -     3.35    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.97   0.03    -      -      -      -     lea	eax, [rsi + rdi]
-      -     0.33   0.32    -     0.35    -      -     cmp	rsi, 6
-      -     1.00    -      -      -      -      -     setb	cl
-      -      -     1.00    -      -      -      -     or	cl, al
-      -      -     1.00    -      -      -      -     test	cl, 1
-      -      -      -      -     1.00    -      -     je	.LBB5_2
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -      -      -     1.00    -      -     ret
-      -     0.34   0.66    -      -      -      -     lea	rax, [rdi + rsi]
-      -     0.68   0.32    -      -      -      -     add	rax, -6
-      -      -      -      -     1.00    -      -     ret

Unsized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes, SplitAt)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [[u8; 2]],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_dynamic_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_suffix_dynamic_size(source: &[u8]) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_suffix(source) {
       Ok((_rest, packet)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_suffix_dynamic_size:
   mov rdx, rsi
   lea ecx, [rsi + rdi]
   mov eax, edx
   and eax, 1
   add rax, rdi
   xor esi, esi
   sub rdx, 4
   cmovb rax, rsi
   shr rdx
   test cl, 1
   cmovne rax, rsi
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1200
Total Cycles:      439
Total uOps:        1400

Dispatch Width:    4
uOps Per Cycle:    3.19
IPC:               2.73
Block RThroughput: 3.5


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        mov	rdx, rsi
1      1     0.50                        lea	ecx, [rsi + rdi]
1      1     0.33                        mov	eax, edx
1      1     0.33                        and	eax, 1
1      1     0.33                        add	rax, rdi
1      0     0.25                        xor	esi, esi
1      1     0.33                        sub	rdx, 4
2      2     0.67                        cmovb	rax, rsi
1      1     0.50                        shr	rdx
1      1     0.33                        test	cl, 1
2      2     0.67                        cmovne	rax, rsi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     4.33   4.33    -     4.34    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.02   0.32    -     0.66    -      -     mov	rdx, rsi
-      -     0.32   0.68    -      -      -      -     lea	ecx, [rsi + rdi]
-      -     0.66    -      -     0.34    -      -     mov	eax, edx
-      -     0.02   0.33    -     0.65    -      -     and	eax, 1
-      -      -     0.99    -     0.01    -      -     add	rax, rdi
-      -      -      -      -      -      -      -     xor	esi, esi
-      -     0.65    -      -     0.35    -      -     sub	rdx, 4
-      -     1.00   1.00    -      -      -      -     cmovb	rax, rsi
-      -     0.66    -      -     0.34    -      -     shr	rdx
-      -      -     0.01    -     0.99    -      -     test	cl, 1
-      -     1.00   1.00    -      -      -      -     cmovne	rax, rsi
-      -      -      -      -     1.00    -      -     ret

Dynamically Padded

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

#[derive(FromBytes, KnownLayout, Immutable, SplitAt)]
#[repr(C, align(4))]
pub struct Packet<Magic> {
   magic_number: Magic,
   milk: u8,
   mug_size: u8,
   temperature: [u8; 5],
   marshmallows: [[u8; 3]],
}

/// A packet begining with the magic number `0xC0C0`.
pub type CocoPacket = Packet<C0C0>;

/// A packet beginning with any two initialized bytes.
pub type LocoPacket = Packet<[u8; 2]>;

Benchmark

#[path = "formats/coco_dynamic_padding.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_suffix_dynamic_padding(source: &[u8]) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_suffix(source) {
       Ok((_rest, packet)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_suffix_dynamic_padding:
   lea eax, [rsi + rdi]
   test al, 3
   jne .LBB5_1
   movabs rax, 9223372036854775804
   and rax, rsi
   cmp rax, 9
   jae .LBB5_3
.LBB5_1:
   xor eax, eax
   ret
.LBB5_3:
   add rax, -9
   movabs rcx, -6148914691236517205
   mul rcx
   shr rdx
   lea rax, [rdx + 2*rdx]
   sub rsi, rax
   or rax, -4
   add rsi, rdi
   add rax, rsi
   add rax, -8
   ret

Machine Code Analysis

Iterations:        100
Instructions:      2000
Total Cycles:      682
Total uOps:        2100

Dispatch Width:    4
uOps Per Cycle:    3.08
IPC:               2.93
Block RThroughput: 5.3


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.50                        lea	eax, [rsi + rdi]
1      1     0.33                        test	al, 3
1      1     1.00                        jne	.LBB5_1
1      1     0.33                        movabs	rax, 9223372036854775804
1      1     0.33                        and	rax, rsi
1      1     0.33                        cmp	rax, 9
1      1     1.00                        jae	.LBB5_3
1      0     0.25                        xor	eax, eax
1      1     1.00                  U     ret
1      1     0.33                        add	rax, -9
1      1     0.33                        movabs	rcx, -6148914691236517205
2      4     1.00                        mul	rcx
1      1     0.50                        shr	rdx
1      1     0.50                        lea	rax, [rdx + 2*rdx]
1      1     0.33                        sub	rsi, rax
1      1     0.33                        or	rax, -4
1      1     0.33                        add	rsi, rdi
1      1     0.33                        add	rax, rsi
1      1     0.33                        add	rax, -8
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     6.65   6.67    -     6.68    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.90   0.10    -      -      -      -     lea	eax, [rsi + rdi]
-      -     0.93    -      -     0.07    -      -     test	al, 3
-      -      -      -      -     1.00    -      -     jne	.LBB5_1
-      -     0.51   0.47    -     0.02    -      -     movabs	rax, 9223372036854775804
-      -      -      -      -     1.00    -      -     and	rax, rsi
-      -      -     0.09    -     0.91    -      -     cmp	rax, 9
-      -      -      -      -     1.00    -      -     jae	.LBB5_3
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -      -      -     1.00    -      -     ret
-      -     0.43   0.47    -     0.10    -      -     add	rax, -9
-      -     0.42   0.39    -     0.19    -      -     movabs	rcx, -6148914691236517205
-      -     1.00   1.00    -      -      -      -     mul	rcx
-      -     0.69    -      -     0.31    -      -     shr	rdx
-      -     0.54   0.46    -      -      -      -     lea	rax, [rdx + 2*rdx]
-      -     0.07   0.91    -     0.02    -      -     sub	rsi, rax
-      -     0.91   0.05    -     0.04    -      -     or	rax, -4
-      -     0.08   0.90    -     0.02    -      -     add	rsi, rdi
-      -     0.09   0.91    -      -      -      -     add	rax, rsi
-      -     0.08   0.92    -      -      -      -     add	rax, -8
-      -      -      -      -     1.00    -      -     ret

fn mut_from_bytes(source: &mut [u8]) -> Result<&mut Self, CastError<&mut [u8], Self>> where Self: IntoBytes + KnownLayout,

Interprets the given source as a &mut Self.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. See mut_from_prefix_with_elems, which does support such types. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let mut source = [85, 85];
let _ = ZSTy::mut_from_bytes(&mut source[..]); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These bytes encode a `PacketHeader`.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7][..];

let header = PacketHeader::mut_from_bytes(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);

header.checksum = [0, 0];

assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 0, 0]);

§ Code Generation

See FromBytes::ref_from_bytes.

fn mut_from_prefix(source: &mut [u8]) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>> where Self: IntoBytes + KnownLayout,

Interprets the prefix of the given source as a &mut Self without copying.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. See mut_from_suffix_with_elems, which does support such types. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let mut source = [85, 85];
let _ = ZSTy::mut_from_prefix(&mut source[..]); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These are more bytes than are needed to encode a `PacketHeader`.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (header, body) = PacketHeader::mut_from_prefix(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);
assert_eq!(body, &[8, 9][..]);

header.checksum = [0, 0];
body.fill(1);

assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 0, 0, 1, 1]);

§ Code Generation

See FromBytes::ref_from_prefix.

fn mut_from_suffix(source: &mut [u8]) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>> where Self: IntoBytes + KnownLayout,

Interprets the suffix of the given source as a &mut Self without copying.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let mut source = [85, 85];
let _ = ZSTy::mut_from_suffix(&mut source[..]); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct PacketTrailer {
    frame_check_sequence: [u8; 4],
}

// These are more bytes than are needed to encode a `PacketTrailer`.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (prefix, trailer) = PacketTrailer::mut_from_suffix(bytes).unwrap();

assert_eq!(prefix, &[0u8, 1, 2, 3, 4, 5][..]);
assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

prefix.fill(0);
trailer.frame_check_sequence.fill(1);

assert_eq!(bytes, [0, 0, 0, 0, 0, 0, 1, 1, 1, 1]);

§ Code Generation

See FromBytes::ref_from_suffix.

fn ref_from_bytes_with_elems(source: &[u8], count: usize) -> Result<&Self, CastError<&[u8], Self>> where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the given source as a &Self with a DST length equal to count.

This method attempts to return a reference to source interpreted as a Self with count trailing elements. If the length of source is not equal to the size of Self with count elements, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

# #[derive(Debug, PartialEq, Eq)]
#[derive(FromBytes, Immutable)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

let bytes = &[0, 1, 2, 3, 4, 5, 6, 7][..];

let pixels = <[Pixel]>::ref_from_bytes_with_elems(bytes, 2).unwrap();

assert_eq!(pixels, &[
    Pixel { r: 0, g: 1, b: 2, a: 3 },
    Pixel { r: 4, g: 5, b: 6, a: 7 },
]);

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as ref_from_bytes which do not take an explicit count do not support such types.

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &[85, 85][..];
let zsty = ZSTy::ref_from_bytes_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

§ Code Generation

The below examples illustrate typical codegen for increasingly complex types:

Unsized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes, SplitAt)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [[u8; 2]],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_dynamic_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_bytes_with_elems_dynamic_size(
   source: &[u8],
   count: usize,
) -> Option<&format::LocoPacket> {
   zerocopy::FromBytes::ref_from_bytes_with_elems(source, count).ok()
}

Assembly

bench_ref_from_bytes_with_elems_dynamic_size:
   movabs rax, 4611686018427387901
   cmp rdx, rax
   seta cl
   mov rax, rdi
   or dil, cl
   test dil, 1
   jne .LBB5_2
   lea rcx, [2*rdx + 4]
   cmp rsi, rcx
   je .LBB5_3
.LBB5_2:
   xor eax, eax
   mov rdx, rsi
.LBB5_3:
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1300
Total Cycles:      439
Total uOps:        1400

Dispatch Width:    4
uOps Per Cycle:    3.19
IPC:               2.96
Block RThroughput: 3.5


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        movabs	rax, 4611686018427387901
1      1     0.33                        cmp	rdx, rax
2      2     1.00                        seta	cl
1      1     0.33                        mov	rax, rdi
1      1     0.33                        or	dil, cl
1      1     0.33                        test	dil, 1
1      1     1.00                        jne	.LBB5_2
1      1     0.50                        lea	rcx, [2*rdx + 4]
1      1     0.33                        cmp	rsi, rcx
1      1     1.00                        je	.LBB5_3
1      0     0.25                        xor	eax, eax
1      1     0.33                        mov	rdx, rsi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     4.32   4.33    -     4.35    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -     0.99    -     0.01    -      -     movabs	rax, 4611686018427387901
-      -     0.33   0.67    -      -      -      -     cmp	rdx, rax
-      -     1.98    -      -     0.02    -      -     seta	cl
-      -     0.01   0.99    -      -      -      -     mov	rax, rdi
-      -     1.00    -      -      -      -      -     or	dil, cl
-      -     0.99   0.01    -      -      -      -     test	dil, 1
-      -      -      -      -     1.00    -      -     jne	.LBB5_2
-      -      -     1.00    -      -      -      -     lea	rcx, [2*rdx + 4]
-      -     0.01    -      -     0.99    -      -     cmp	rsi, rcx
-      -      -      -      -     1.00    -      -     je	.LBB5_3
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -     0.67    -     0.33    -      -     mov	rdx, rsi
-      -      -      -      -     1.00    -      -     ret

Dynamically Padded

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

#[derive(FromBytes, KnownLayout, Immutable, SplitAt)]
#[repr(C, align(4))]
pub struct Packet<Magic> {
   magic_number: Magic,
   milk: u8,
   mug_size: u8,
   temperature: [u8; 5],
   marshmallows: [[u8; 3]],
}

/// A packet begining with the magic number `0xC0C0`.
pub type CocoPacket = Packet<C0C0>;

/// A packet beginning with any two initialized bytes.
pub type LocoPacket = Packet<[u8; 2]>;

Benchmark

#[path = "formats/coco_dynamic_padding.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_bytes_with_elems_dynamic_padding(
   source: &[u8],
   count: usize,
) -> Option<&format::LocoPacket> {
   zerocopy::FromBytes::ref_from_bytes_with_elems(source, count).ok()
}

Assembly

bench_ref_from_bytes_with_elems_dynamic_padding:
   movabs rax, 3074457345618258598
   cmp rdx, rax
   seta cl
   mov rax, rdi
   test al, 3
   setne dil
   or dil, cl
   jne .LBB5_2
   lea rcx, [rdx + 2*rdx]
   or rcx, 3
   add rcx, 9
   cmp rsi, rcx
   je .LBB5_3
.LBB5_2:
   xor eax, eax
   mov rdx, rsi
.LBB5_3:
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1600
Total Cycles:      539
Total uOps:        1700

Dispatch Width:    4
uOps Per Cycle:    3.15
IPC:               2.97
Block RThroughput: 4.3


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        movabs	rax, 3074457345618258598
1      1     0.33                        cmp	rdx, rax
2      2     1.00                        seta	cl
1      1     0.33                        mov	rax, rdi
1      1     0.33                        test	al, 3
1      1     0.50                        setne	dil
1      1     0.33                        or	dil, cl
1      1     1.00                        jne	.LBB5_2
1      1     0.50                        lea	rcx, [rdx + 2*rdx]
1      1     0.33                        or	rcx, 3
1      1     0.33                        add	rcx, 9
1      1     0.33                        cmp	rsi, rcx
1      1     1.00                        je	.LBB5_3
1      0     0.25                        xor	eax, eax
1      1     0.33                        mov	rdx, rsi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     5.33   5.32    -     5.35    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.01   0.98    -     0.01    -      -     movabs	rax, 3074457345618258598
-      -      -     1.00    -      -      -      -     cmp	rdx, rax
-      -     1.98    -      -     0.02    -      -     seta	cl
-      -     0.02   0.98    -      -      -      -     mov	rax, rdi
-      -      -     0.67    -     0.33    -      -     test	al, 3
-      -     0.67    -      -     0.33    -      -     setne	dil
-      -     0.99    -      -     0.01    -      -     or	dil, cl
-      -      -      -      -     1.00    -      -     jne	.LBB5_2
-      -     0.01   0.99    -      -      -      -     lea	rcx, [rdx + 2*rdx]
-      -      -     0.01    -     0.99    -      -     or	rcx, 3
-      -     0.65   0.02    -     0.33    -      -     add	rcx, 9
-      -     0.99   0.01    -      -      -      -     cmp	rsi, rcx
-      -      -      -      -     1.00    -      -     je	.LBB5_3
-      -      -      -      -      -      -      -     xor	eax, eax
-      -     0.01   0.66    -     0.33    -      -     mov	rdx, rsi
-      -      -      -      -     1.00    -      -     ret

fn ref_from_prefix_with_elems(source: &[u8], count: usize) -> Result<(&Self, &[u8]), CastError<&[u8], Self>> where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the prefix of the given source as a DST &Self with length equal to count.

This method attempts to return a reference to the prefix of source interpreted as a Self with count trailing elements, and a reference to the remaining bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

# #[derive(Debug, PartialEq, Eq)]
#[derive(FromBytes, Immutable)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These are more bytes than are needed to encode two `Pixel`s.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (pixels, suffix) = <[Pixel]>::ref_from_prefix_with_elems(bytes, 2).unwrap();

assert_eq!(pixels, &[
    Pixel { r: 0, g: 1, b: 2, a: 3 },
    Pixel { r: 4, g: 5, b: 6, a: 7 },
]);

assert_eq!(suffix, &[8, 9]);

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as ref_from_prefix which do not take an explicit count do not support such types.

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &[85, 85][..];
let (zsty, _) = ZSTy::ref_from_prefix_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

§ Code Generation

The below examples illustrate typical codegen for increasingly complex types:

Unsized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes, SplitAt)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [[u8; 2]],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_dynamic_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_prefix_with_elems_dynamic_size(
   source: &[u8],
   count: usize,
) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_prefix_with_elems(source, count) {
       Ok((packet, _rest)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_prefix_with_elems_dynamic_size:
   movabs rax, 4611686018427387901
   cmp rdx, rax
   ja .LBB5_1
   mov rcx, rdx
   xor edx, edx
   mov eax, 0
   test dil, 1
   jne .LBB5_4
   lea rax, [2*rcx + 4]
   xor r8d, r8d
   cmp rax, rsi
   mov edx, 1
   cmovbe rdx, rcx
   cmova rdi, r8
   mov rax, rdi
.LBB5_4:
   ret
.LBB5_1:
   mov edx, 1
   xor eax, eax
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1900
Total Cycles:      672
Total uOps:        2300

Dispatch Width:    4
uOps Per Cycle:    3.42
IPC:               2.83
Block RThroughput: 5.8


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        movabs	rax, 4611686018427387901
1      1     0.33                        cmp	rdx, rax
1      1     1.00                        ja	.LBB5_1
1      1     0.33                        mov	rcx, rdx
1      0     0.25                        xor	edx, edx
1      1     0.33                        mov	eax, 0
1      1     0.33                        test	dil, 1
1      1     1.00                        jne	.LBB5_4
1      1     0.50                        lea	rax, [2*rcx + 4]
1      0     0.25                        xor	r8d, r8d
1      1     0.33                        cmp	rax, rsi
1      1     0.33                        mov	edx, 1
3      3     1.00                        cmovbe	rdx, rcx
3      3     1.00                        cmova	rdi, r8
1      1     0.33                        mov	rax, rdi
1      1     1.00                  U     ret
1      1     0.33                        mov	edx, 1
1      0     0.25                        xor	eax, eax
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     6.66   6.66    -     6.68    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -     0.99    -     0.01    -      -     movabs	rax, 4611686018427387901
-      -     0.37   0.63    -      -      -      -     cmp	rdx, rax
-      -      -      -      -     1.00    -      -     ja	.LBB5_1
-      -     0.63   0.37    -      -      -      -     mov	rcx, rdx
-      -      -      -      -      -      -      -     xor	edx, edx
-      -     0.01   0.98    -     0.01    -      -     mov	eax, 0
-      -     0.98   0.02    -      -      -      -     test	dil, 1
-      -      -      -      -     1.00    -      -     jne	.LBB5_4
-      -     0.01   0.99    -      -      -      -     lea	rax, [2*rcx + 4]
-      -      -      -      -      -      -      -     xor	r8d, r8d
-      -     1.00    -      -      -      -      -     cmp	rax, rsi
-      -      -     0.67    -     0.33    -      -     mov	edx, 1
-      -     0.73   0.98    -     1.29    -      -     cmovbe	rdx, rcx
-      -     1.60   0.36    -     1.04    -      -     cmova	rdi, r8
-      -     0.99   0.01    -      -      -      -     mov	rax, rdi
-      -      -      -      -     1.00    -      -     ret
-      -     0.34   0.66    -      -      -      -     mov	edx, 1
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -      -      -     1.00    -      -     ret

Dynamically Padded

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

#[derive(FromBytes, KnownLayout, Immutable, SplitAt)]
#[repr(C, align(4))]
pub struct Packet<Magic> {
   magic_number: Magic,
   milk: u8,
   mug_size: u8,
   temperature: [u8; 5],
   marshmallows: [[u8; 3]],
}

/// A packet begining with the magic number `0xC0C0`.
pub type CocoPacket = Packet<C0C0>;

/// A packet beginning with any two initialized bytes.
pub type LocoPacket = Packet<[u8; 2]>;

Benchmark

#[path = "formats/coco_dynamic_padding.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_prefix_with_elems_dynamic_padding(
   source: &[u8],
   count: usize,
) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_prefix_with_elems(source, count) {
       Ok((packet, _rest)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_prefix_with_elems_dynamic_padding:
   movabs rax, 3074457345618258598
   cmp rdx, rax
   ja .LBB5_1
   xor ecx, ecx
   mov eax, 0
   test dil, 3
   je .LBB5_3
   mov rdx, rcx
   ret
.LBB5_1:
   mov edx, 1
   xor eax, eax
   ret
.LBB5_3:
   lea rax, [rdx + 2*rdx]
   or rax, 3
   add rax, 9
   xor r8d, r8d
   cmp rax, rsi
   mov ecx, 1
   cmovbe rcx, rdx
   cmova rdi, r8
   mov rax, rdi
   mov rdx, rcx
   ret

Machine Code Analysis

Iterations:        100
Instructions:      2300
Total Cycles:      807
Total uOps:        2700

Dispatch Width:    4
uOps Per Cycle:    3.35
IPC:               2.85
Block RThroughput: 6.8


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        movabs	rax, 3074457345618258598
1      1     0.33                        cmp	rdx, rax
1      1     1.00                        ja	.LBB5_1
1      0     0.25                        xor	ecx, ecx
1      1     0.33                        mov	eax, 0
1      1     0.33                        test	dil, 3
1      1     1.00                        je	.LBB5_3
1      1     0.33                        mov	rdx, rcx
1      1     1.00                  U     ret
1      1     0.33                        mov	edx, 1
1      0     0.25                        xor	eax, eax
1      1     1.00                  U     ret
1      1     0.50                        lea	rax, [rdx + 2*rdx]
1      1     0.33                        or	rax, 3
1      1     0.33                        add	rax, 9
1      0     0.25                        xor	r8d, r8d
1      1     0.33                        cmp	rax, rsi
1      1     0.33                        mov	ecx, 1
3      3     1.00                        cmovbe	rcx, rdx
3      3     1.00                        cmova	rdi, r8
1      1     0.33                        mov	rax, rdi
1      1     0.33                        mov	rdx, rcx
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     7.99   7.99    -     8.02    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.47   0.52    -     0.01    -      -     movabs	rax, 3074457345618258598
-      -     0.94   0.01    -     0.05    -      -     cmp	rdx, rax
-      -      -      -      -     1.00    -      -     ja	.LBB5_1
-      -      -      -      -      -      -      -     xor	ecx, ecx
-      -     0.03   0.97    -      -      -      -     mov	eax, 0
-      -     0.01   0.52    -     0.47    -      -     test	dil, 3
-      -      -      -      -     1.00    -      -     je	.LBB5_3
-      -     0.03   0.51    -     0.46    -      -     mov	rdx, rcx
-      -      -      -      -     1.00    -      -     ret
-      -     0.04   0.96    -      -      -      -     mov	edx, 1
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -      -      -     1.00    -      -     ret
-      -     0.01   0.99    -      -      -      -     lea	rax, [rdx + 2*rdx]
-      -     0.52   0.48    -      -      -      -     or	rax, 3
-      -     0.51   0.49    -      -      -      -     add	rax, 9
-      -      -      -      -      -      -      -     xor	r8d, r8d
-      -     0.97   0.03    -      -      -      -     cmp	rax, rsi
-      -     0.01   0.99    -      -      -      -     mov	ecx, 1
-      -     1.04   0.97    -     0.99    -      -     cmovbe	rcx, rdx
-      -     1.44   0.54    -     1.02    -      -     cmova	rdi, r8
-      -     0.97   0.01    -     0.02    -      -     mov	rax, rdi
-      -     1.00    -      -      -      -      -     mov	rdx, rcx
-      -      -      -      -     1.00    -      -     ret

fn ref_from_suffix_with_elems(source: &[u8], count: usize) -> Result<(&[u8], &Self), CastError<&[u8], Self>> where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the suffix of the given source as a DST &Self with length equal to count.

This method attempts to return a reference to the suffix of source interpreted as a Self with count trailing elements, and a reference to the preceding bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

# #[derive(Debug, PartialEq, Eq)]
#[derive(FromBytes, Immutable)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These are more bytes than are needed to encode two `Pixel`s.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (prefix, pixels) = <[Pixel]>::ref_from_suffix_with_elems(bytes, 2).unwrap();

assert_eq!(prefix, &[0, 1]);

assert_eq!(pixels, &[
    Pixel { r: 2, g: 3, b: 4, a: 5 },
    Pixel { r: 6, g: 7, b: 8, a: 9 },
]);

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as ref_from_suffix which do not take an explicit count do not support such types.

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &[85, 85][..];
let (_, zsty) = ZSTy::ref_from_suffix_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

§ Code Generation

The below examples illustrate typical codegen for increasingly complex types:

Unsized

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes, SplitAt)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [[u8; 2]],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_dynamic_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_suffix_with_elems_dynamic_size(
   source: &[u8],
   count: usize,
) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_suffix_with_elems(source, count) {
       Ok((_rest, packet)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_suffix_with_elems_dynamic_size:
   movabs rax, 4611686018427387901
   cmp rdx, rax
   ja .LBB5_1
   lea r8d, [rsi + rdi]
   xor ecx, ecx
   mov eax, 0
   test r8b, 1
   jne .LBB5_5
   lea rax, [2*rdx + 4]
   sub rsi, rax
   jae .LBB5_4
.LBB5_1:
   xor eax, eax
   mov edx, 1
   ret
.LBB5_4:
   add rdi, rsi
   mov rcx, rdx
   mov rax, rdi
.LBB5_5:
   mov rdx, rcx
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1900
Total Cycles:      571
Total uOps:        1900

Dispatch Width:    4
uOps Per Cycle:    3.33
IPC:               3.33
Block RThroughput: 5.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        movabs	rax, 4611686018427387901
1      1     0.33                        cmp	rdx, rax
1      1     1.00                        ja	.LBB5_1
1      1     0.50                        lea	r8d, [rsi + rdi]
1      0     0.25                        xor	ecx, ecx
1      1     0.33                        mov	eax, 0
1      1     0.33                        test	r8b, 1
1      1     1.00                        jne	.LBB5_5
1      1     0.50                        lea	rax, [2*rdx + 4]
1      1     0.33                        sub	rsi, rax
1      1     1.00                        jae	.LBB5_4
1      0     0.25                        xor	eax, eax
1      1     0.33                        mov	edx, 1
1      1     1.00                  U     ret
1      1     0.33                        add	rdi, rsi
1      1     0.33                        mov	rcx, rdx
1      1     0.33                        mov	rax, rdi
1      1     0.33                        mov	rdx, rcx
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     5.66   5.66    -     5.68    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.66   0.33    -     0.01    -      -     movabs	rax, 4611686018427387901
-      -     0.01   0.99    -      -      -      -     cmp	rdx, rax
-      -      -      -      -     1.00    -      -     ja	.LBB5_1
-      -     0.99   0.01    -      -      -      -     lea	r8d, [rsi + rdi]
-      -      -      -      -      -      -      -     xor	ecx, ecx
-      -     0.33   0.33    -     0.34    -      -     mov	eax, 0
-      -     0.33   0.34    -     0.33    -      -     test	r8b, 1
-      -      -      -      -     1.00    -      -     jne	.LBB5_5
-      -     0.34   0.66    -      -      -      -     lea	rax, [2*rdx + 4]
-      -      -     1.00    -      -      -      -     sub	rsi, rax
-      -      -      -      -     1.00    -      -     jae	.LBB5_4
-      -      -      -      -      -      -      -     xor	eax, eax
-      -     1.00    -      -      -      -      -     mov	edx, 1
-      -      -      -      -     1.00    -      -     ret
-      -      -     1.00    -      -      -      -     add	rdi, rsi
-      -     1.00    -      -      -      -      -     mov	rcx, rdx
-      -     0.32   0.68    -      -      -      -     mov	rax, rdi
-      -     0.68   0.32    -      -      -      -     mov	rdx, rcx
-      -      -      -      -     1.00    -      -     ret

Dynamically Padded

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

#[derive(FromBytes, KnownLayout, Immutable, SplitAt)]
#[repr(C, align(4))]
pub struct Packet<Magic> {
   magic_number: Magic,
   milk: u8,
   mug_size: u8,
   temperature: [u8; 5],
   marshmallows: [[u8; 3]],
}

/// A packet begining with the magic number `0xC0C0`.
pub type CocoPacket = Packet<C0C0>;

/// A packet beginning with any two initialized bytes.
pub type LocoPacket = Packet<[u8; 2]>;

Benchmark

#[path = "formats/coco_dynamic_padding.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_ref_from_suffix_with_elems_dynamic_padding(
   source: &[u8],
   count: usize,
) -> Option<&format::LocoPacket> {
   match zerocopy::FromBytes::ref_from_suffix_with_elems(source, count) {
       Ok((_rest, packet)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_ref_from_suffix_with_elems_dynamic_padding:
   movabs rax, 3074457345618258598
   cmp rdx, rax
   ja .LBB5_1
   lea r8d, [rsi + rdi]
   xor ecx, ecx
   mov eax, 0
   test r8b, 3
   je .LBB5_3
   mov rdx, rcx
   ret
.LBB5_3:
   lea rax, [rdx + 2*rdx]
   or rax, 3
   add rax, 9
   sub rsi, rax
   jae .LBB5_4
.LBB5_1:
   xor eax, eax
   mov edx, 1
   ret
.LBB5_4:
   add rdi, rsi
   mov rcx, rdx
   mov rax, rdi
   mov rdx, rcx
   ret

Machine Code Analysis

Iterations:        100
Instructions:      2300
Total Cycles:      706
Total uOps:        2300

Dispatch Width:    4
uOps Per Cycle:    3.26
IPC:               3.26
Block RThroughput: 6.0


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        movabs	rax, 3074457345618258598
1      1     0.33                        cmp	rdx, rax
1      1     1.00                        ja	.LBB5_1
1      1     0.50                        lea	r8d, [rsi + rdi]
1      0     0.25                        xor	ecx, ecx
1      1     0.33                        mov	eax, 0
1      1     0.33                        test	r8b, 3
1      1     1.00                        je	.LBB5_3
1      1     0.33                        mov	rdx, rcx
1      1     1.00                  U     ret
1      1     0.50                        lea	rax, [rdx + 2*rdx]
1      1     0.33                        or	rax, 3
1      1     0.33                        add	rax, 9
1      1     0.33                        sub	rsi, rax
1      1     1.00                        jae	.LBB5_4
1      0     0.25                        xor	eax, eax
1      1     0.33                        mov	edx, 1
1      1     1.00                  U     ret
1      1     0.33                        add	rdi, rsi
1      1     0.33                        mov	rcx, rdx
1      1     0.33                        mov	rax, rdi
1      1     0.33                        mov	rdx, rcx
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     6.99   7.00    -     7.01    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -     0.99    -     0.01    -      -     movabs	rax, 3074457345618258598
-      -     0.01   0.50    -     0.49    -      -     cmp	rdx, rax
-      -      -      -      -     1.00    -      -     ja	.LBB5_1
-      -      -     1.00    -      -      -      -     lea	r8d, [rsi + rdi]
-      -      -      -      -      -      -      -     xor	ecx, ecx
-      -     0.50   0.49    -     0.01    -      -     mov	eax, 0
-      -     0.49   0.51    -      -      -      -     test	r8b, 3
-      -      -      -      -     1.00    -      -     je	.LBB5_3
-      -     0.51   0.49    -      -      -      -     mov	rdx, rcx
-      -      -      -      -     1.00    -      -     ret
-      -     0.50   0.50    -      -      -      -     lea	rax, [rdx + 2*rdx]
-      -     1.00    -      -      -      -      -     or	rax, 3
-      -     1.00    -      -      -      -      -     add	rax, 9
-      -     0.99   0.01    -      -      -      -     sub	rsi, rax
-      -      -      -      -     1.00    -      -     jae	.LBB5_4
-      -      -      -      -      -      -      -     xor	eax, eax
-      -      -     1.00    -      -      -      -     mov	edx, 1
-      -      -      -      -     1.00    -      -     ret
-      -     1.00    -      -      -      -      -     add	rdi, rsi
-      -      -     1.00    -      -      -      -     mov	rcx, rdx
-      -     0.99   0.01    -      -      -      -     mov	rax, rdi
-      -      -     0.50    -     0.50    -      -     mov	rdx, rcx
-      -      -      -      -     1.00    -      -     ret

fn mut_from_bytes_with_elems(source: &mut [u8], count: usize) -> Result<&mut Self, CastError<&mut [u8], Self>> where Self: IntoBytes + KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the given source as a &mut Self with a DST length equal to count.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

# #[derive(Debug, PartialEq, Eq)]
#[derive(KnownLayout, FromBytes, IntoBytes, Immutable)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7][..];

let pixels = <[Pixel]>::mut_from_bytes_with_elems(bytes, 2).unwrap();

assert_eq!(pixels, &[
    Pixel { r: 0, g: 1, b: 2, a: 3 },
    Pixel { r: 4, g: 5, b: 6, a: 7 },
]);

pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };

assert_eq!(bytes, [0, 1, 2, 3, 0, 0, 0, 0]);

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as mut_from_bytes which do not take an explicit count do not support such types.

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &mut [85, 85][..];
let zsty = ZSTy::mut_from_bytes_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

§ Code Generation

See TryFromBytes::ref_from_bytes_with_elems.

fn mut_from_prefix_with_elems(source: &mut [u8], count: usize) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>> where Self: IntoBytes + KnownLayout<PointerMetadata = usize>,

Interprets the prefix of the given source as a &mut Self with DST length equal to count.

This method attempts to return a reference to the prefix of source interpreted as a Self with count trailing elements, and a reference to the preceding bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

# #[derive(Debug, PartialEq, Eq)]
#[derive(KnownLayout, FromBytes, IntoBytes, Immutable)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These are more bytes than are needed to encode two `Pixel`s.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (pixels, suffix) = <[Pixel]>::mut_from_prefix_with_elems(bytes, 2).unwrap();

assert_eq!(pixels, &[
    Pixel { r: 0, g: 1, b: 2, a: 3 },
    Pixel { r: 4, g: 5, b: 6, a: 7 },
]);

assert_eq!(suffix, &[8, 9]);

pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };
suffix.fill(1);

assert_eq!(bytes, [0, 1, 2, 3, 0, 0, 0, 0, 1, 1]);

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as mut_from_prefix which do not take an explicit count do not support such types.

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &mut [85, 85][..];
let (zsty, _) = ZSTy::mut_from_prefix_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

§ Code Generation

See TryFromBytes::ref_from_prefix_with_elems.

fn mut_from_suffix_with_elems(source: &mut [u8], count: usize) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>> where Self: IntoBytes + KnownLayout<PointerMetadata = usize>,

Interprets the suffix of the given source as a &mut Self with DST length equal to count.

This method attempts to return a reference to the suffix of source interpreted as a Self with count trailing elements, and a reference to the remaining bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

# #[derive(Debug, PartialEq, Eq)]
#[derive(FromBytes, IntoBytes, Immutable)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These are more bytes than are needed to encode two `Pixel`s.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (prefix, pixels) = <[Pixel]>::mut_from_suffix_with_elems(bytes, 2).unwrap();

assert_eq!(prefix, &[0, 1]);

assert_eq!(pixels, &[
    Pixel { r: 2, g: 3, b: 4, a: 5 },
    Pixel { r: 6, g: 7, b: 8, a: 9 },
]);

prefix.fill(9);
pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };

assert_eq!(bytes, [9, 9, 2, 3, 4, 5, 0, 0, 0, 0]);

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as mut_from_suffix which do not take an explicit count do not support such types.

use zerocopy::*;
# use zerocopy_derive::*;

#[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &mut [85, 85][..];
let (_, zsty) = ZSTy::mut_from_suffix_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

§ Code Generation

See TryFromBytes::ref_from_suffix_with_elems.

fn read_from_bytes(source: &[u8]) -> Result<Self, SizeError<&[u8], Self>> where Self: Sized,

Reads a copy of Self from the given source.

If source.len() != size_of::<Self>(), read_from_bytes returns Err.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These bytes encode a `PacketHeader`.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7][..];

let header = PacketHeader::read_from_bytes(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);

§ Code Generation

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [u8; 2],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_static_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_read_from_bytes_static_size(source: &[u8]) -> Option<format::LocoPacket> {
   zerocopy::FromBytes::read_from_bytes(source).ok()
}

Assembly

bench_read_from_bytes_static_size:
   mov rcx, rsi
   cmp rsi, 6
   jne .LBB5_2
   mov eax, dword ptr [rdi]
   movzx ecx, word ptr [rdi + 4]
   shl rcx, 32
   or rcx, rax
.LBB5_2:
   shl rcx, 16
   inc rcx
   xor eax, eax
   cmp rsi, 6
   cmove rax, rcx
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1300
Total Cycles:      377
Total uOps:        1400

Dispatch Width:    4
uOps Per Cycle:    3.71
IPC:               3.45
Block RThroughput: 3.5


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        mov	rcx, rsi
1      1     0.33                        cmp	rsi, 6
1      1     1.00                        jne	.LBB5_2
1      5     0.50    *                   mov	eax, dword ptr [rdi]
1      5     0.50    *                   movzx	ecx, word ptr [rdi + 4]
1      1     0.50                        shl	rcx, 32
1      1     0.33                        or	rcx, rax
1      1     0.50                        shl	rcx, 16
1      1     0.33                        inc	rcx
1      0     0.25                        xor	eax, eax
1      1     0.33                        cmp	rsi, 6
2      2     0.67                        cmove	rax, rcx
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     3.66   3.67    -     3.67   1.00   1.00   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.63   0.36    -     0.01    -      -     mov	rcx, rsi
-      -     0.05   0.05    -     0.90    -      -     cmp	rsi, 6
-      -      -      -      -     1.00    -      -     jne	.LBB5_2
-      -      -      -      -      -      -     1.00   mov	eax, dword ptr [rdi]
-      -      -      -      -      -     1.00    -     movzx	ecx, word ptr [rdi + 4]
-      -     0.97    -      -     0.03    -      -     shl	rcx, 32
-      -     0.02   0.35    -     0.63    -      -     or	rcx, rax
-      -     0.98    -      -     0.02    -      -     shl	rcx, 16
-      -      -     0.98    -     0.02    -      -     inc	rcx
-      -      -      -      -      -      -      -     xor	eax, eax
-      -     0.03   0.93    -     0.04    -      -     cmp	rsi, 6
-      -     0.98   1.00    -     0.02    -      -     cmove	rax, rcx
-      -      -      -      -     1.00    -      -     ret

fn read_from_prefix(source: &[u8]) -> Result<(Self, &[u8]), SizeError<&[u8], Self>> where Self: Sized,

Reads a copy of Self from the prefix of the given source.

This attempts to read a Self from the first size_of::<Self>() bytes of source, returning that Self and any remaining bytes. If source.len() < size_of::<Self>(), it returns Err.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These are more bytes than are needed to encode a `PacketHeader`.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (header, body) = PacketHeader::read_from_prefix(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);
assert_eq!(body, [8, 9]);

§ Code Generation

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [u8; 2],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_static_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_read_from_prefix_static_size(source: &[u8]) -> Option<format::LocoPacket> {
   match zerocopy::FromBytes::read_from_prefix(source) {
       Ok((packet, _rest)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_read_from_prefix_static_size:
   cmp rsi, 5
   jbe .LBB5_2
   mov eax, dword ptr [rdi]
   movzx edi, word ptr [rdi + 4]
   shl rdi, 32
   or rdi, rax
.LBB5_2:
   shl rdi, 16
   inc rdi
   xor eax, eax
   cmp rsi, 6
   cmovae rax, rdi
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1200
Total Cycles:      905
Total uOps:        1300

Dispatch Width:    4
uOps Per Cycle:    1.44
IPC:               1.33
Block RThroughput: 3.3


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        cmp	rsi, 5
1      1     1.00                        jbe	.LBB5_2
1      5     0.50    *                   mov	eax, dword ptr [rdi]
1      5     0.50    *                   movzx	edi, word ptr [rdi + 4]
1      1     0.50                        shl	rdi, 32
1      1     0.33                        or	rdi, rax
1      1     0.50                        shl	rdi, 16
1      1     0.33                        inc	rdi
1      0     0.25                        xor	eax, eax
1      1     0.33                        cmp	rsi, 6
2      2     0.67                        cmovae	rax, rdi
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     3.32   3.32    -     3.36   1.00   1.00   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.05   0.94    -     0.01    -      -     cmp	rsi, 5
-      -      -      -      -     1.00    -      -     jbe	.LBB5_2
-      -      -      -      -      -      -     1.00   mov	eax, dword ptr [rdi]
-      -      -      -      -      -     1.00    -     movzx	edi, word ptr [rdi + 4]
-      -     0.71    -      -     0.29    -      -     shl	rdi, 32
-      -      -     0.64    -     0.36    -      -     or	rdi, rax
-      -     1.00    -      -      -      -      -     shl	rdi, 16
-      -     0.31   0.40    -     0.29    -      -     inc	rdi
-      -      -      -      -      -      -      -     xor	eax, eax
-      -     0.34   0.35    -     0.31    -      -     cmp	rsi, 6
-      -     0.91   0.99    -     0.10    -      -     cmovae	rax, rdi
-      -      -      -      -     1.00    -      -     ret

fn read_from_suffix(source: &[u8]) -> Result<(&[u8], Self), SizeError<&[u8], Self>> where Self: Sized,

Reads a copy of Self from the suffix of the given source.

This attempts to read a Self from the last size_of::<Self>() bytes of source, returning that Self and any preceding bytes. If source.len() < size_of::<Self>(), it returns Err.

Examples

use zerocopy::FromBytes;
# use zerocopy_derive::*;

#[derive(FromBytes)]
#[repr(C)]
struct PacketTrailer {
    frame_check_sequence: [u8; 4],
}

// These are more bytes than are needed to encode a `PacketTrailer`.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (prefix, trailer) = PacketTrailer::read_from_suffix(bytes).unwrap();

assert_eq!(prefix, [0, 1, 2, 3, 4, 5]);
assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

§ Code Generation

Format

use zerocopy_derive::*;

// The only valid value of this type are the bytes `0xC0C0`.
#[derive(TryFromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(u16)]
pub enum C0C0 {
   _XC0C0 = 0xC0C0,
}

macro_rules! define_packet {
   ($name: ident, $trait: ident, $leading_field: ty) => {
       #[derive($trait, KnownLayout, Immutable, IntoBytes)]
       #[repr(C, align(2))]
       pub struct $name {
           magic_number: $leading_field,
           mug_size: u8,
           temperature: u8,
           marshmallows: [u8; 2],
       }
   };
}

/// Packet begins with bytes 0xC0C0.
define_packet!(CocoPacket, TryFromBytes, C0C0);

/// Packet begins with any two bytes.
define_packet!(LocoPacket, FromBytes, [u8; 2]);

Benchmark

#[path = "formats/coco_static_size.rs"]
mod format;

#[unsafe(no_mangle)]
fn bench_read_from_suffix_static_size(source: &[u8]) -> Option<format::LocoPacket> {
   match zerocopy::FromBytes::read_from_suffix(source) {
       Ok((_rest, packet)) => Some(packet),
       _ => None,
   }
}

Assembly

bench_read_from_suffix_static_size:
   mov rcx, rsi
   cmp rsi, 6
   jb .LBB5_2
   mov eax, dword ptr [rdi + rsi - 6]
   movzx ecx, word ptr [rdi + rsi - 2]
   shl rcx, 32
   or rcx, rax
.LBB5_2:
   shl rcx, 16
   inc rcx
   xor eax, eax
   cmp rsi, 6
   cmovae rax, rcx
   ret

Machine Code Analysis

Iterations:        100
Instructions:      1300
Total Cycles:      377
Total uOps:        1400

Dispatch Width:    4
uOps Per Cycle:    3.71
IPC:               3.45
Block RThroughput: 3.5


Instruction Info:
[1]: #uOps
[2]: Latency
[3]: RThroughput
[4]: MayLoad
[5]: MayStore
[6]: HasSideEffects (U)

[1]    [2]    [3]    [4]    [5]    [6]    Instructions:
1      1     0.33                        mov	rcx, rsi
1      1     0.33                        cmp	rsi, 6
1      1     1.00                        jb	.LBB5_2
1      5     0.50    *                   mov	eax, dword ptr [rdi + rsi - 6]
1      5     0.50    *                   movzx	ecx, word ptr [rdi + rsi - 2]
1      1     0.50                        shl	rcx, 32
1      1     0.33                        or	rcx, rax
1      1     0.50                        shl	rcx, 16
1      1     0.33                        inc	rcx
1      0     0.25                        xor	eax, eax
1      1     0.33                        cmp	rsi, 6
2      2     0.67                        cmovae	rax, rcx
1      1     1.00                  U     ret


Resources:
[0]   - SBDivider
[1]   - SBFPDivider
[2]   - SBPort0
[3]   - SBPort1
[4]   - SBPort4
[5]   - SBPort5
[6.0] - SBPort23
[6.1] - SBPort23


Resource pressure per iteration:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  
-      -     3.66   3.67    -     3.67   1.00   1.00   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.63   0.36    -     0.01    -      -     mov	rcx, rsi
-      -     0.05   0.05    -     0.90    -      -     cmp	rsi, 6
-      -      -      -      -     1.00    -      -     jb	.LBB5_2
-      -      -      -      -      -      -     1.00   mov	eax, dword ptr [rdi + rsi - 6]
-      -      -      -      -      -     1.00    -     movzx	ecx, word ptr [rdi + rsi - 2]
-      -     0.97    -      -     0.03    -      -     shl	rcx, 32
-      -     0.02   0.35    -     0.63    -      -     or	rcx, rax
-      -     0.98    -      -     0.02    -      -     shl	rcx, 16
-      -      -     0.98    -     0.02    -      -     inc	rcx
-      -      -      -      -      -      -      -     xor	eax, eax
-      -     0.03   0.93    -     0.04    -      -     cmp	rsi, 6
-      -     0.98   1.00    -     0.02    -      -     cmovae	rax, rcx
-      -      -      -      -     1.00    -      -     ret

Implementors

impl FromBytes for ()
impl FromBytes for AtomicI16
impl FromBytes for AtomicI32
impl FromBytes for AtomicI64
impl FromBytes for AtomicI8
impl FromBytes for AtomicIsize
impl FromBytes for AtomicU16
impl FromBytes for AtomicU32
impl FromBytes for AtomicU64
impl FromBytes for AtomicU8
impl FromBytes for AtomicUsize
impl FromBytes for Option<NonZeroI128>
impl FromBytes for Option<NonZeroI16>
impl FromBytes for Option<NonZeroI32>
impl FromBytes for Option<NonZeroI64>
impl FromBytes for Option<NonZeroI8>
impl FromBytes for Option<NonZeroIsize>
impl FromBytes for Option<NonZeroU128>
impl FromBytes for Option<NonZeroU16>
impl FromBytes for Option<NonZeroU32>
impl FromBytes for Option<NonZeroU64>
impl FromBytes for Option<NonZeroU8>
impl FromBytes for Option<NonZeroUsize>
impl FromBytes for __m128
impl FromBytes for __m128d
impl FromBytes for __m128i
impl FromBytes for __m256
impl FromBytes for __m256d
impl FromBytes for __m256i
impl FromBytes for __m512
impl FromBytes for __m512bh
impl FromBytes for __m512d
impl FromBytes for __m512i
impl FromBytes for f32
impl FromBytes for f64
impl FromBytes for i128
impl FromBytes for i16
impl FromBytes for i32
impl FromBytes for i64
impl FromBytes for i8
impl FromBytes for isize
impl FromBytes for u128
impl FromBytes for u16
impl FromBytes for u32
impl FromBytes for u64
impl FromBytes for u8
impl FromBytes for usize
impl<A: FromBytes> FromBytes for (A,)
impl<A: FromBytes, B: FromBytes> FromBytes for (A, B)
impl<A: FromBytes, B: FromBytes, C: FromBytes> FromBytes for (A, B, C)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes> FromBytes for (A, B, C, D)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes> FromBytes for (A, B, C, D, E)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes> FromBytes for (A, B, C, D, E, F)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes> FromBytes for (A, B, C, D, E, F, G)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes> FromBytes for (A, B, C, D, E, F, G, H)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes, S: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes, S: FromBytes, T: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes, S: FromBytes, T: FromBytes, U: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes, S: FromBytes, T: FromBytes, U: FromBytes, V: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes, S: FromBytes, T: FromBytes, U: FromBytes, V: FromBytes, W: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes, S: FromBytes, T: FromBytes, U: FromBytes, V: FromBytes, W: FromBytes, X: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes, S: FromBytes, T: FromBytes, U: FromBytes, V: FromBytes, W: FromBytes, X: FromBytes, Y: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y)
impl<A: FromBytes, B: FromBytes, C: FromBytes, D: FromBytes, E: FromBytes, F: FromBytes, G: FromBytes, H: FromBytes, I: FromBytes, J: FromBytes, K: FromBytes, L: FromBytes, M: FromBytes, N: FromBytes, O: FromBytes, P: FromBytes, Q: FromBytes, R: FromBytes, S: FromBytes, T: FromBytes, U: FromBytes, V: FromBytes, W: FromBytes, X: FromBytes, Y: FromBytes, Z: FromBytes> FromBytes for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)
impl<O> FromBytes for F32<O> where [u8; 4]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for F64<O> where [u8; 8]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for I128<O> where [u8; 16]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for I16<O> where [u8; 2]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for I32<O> where [u8; 4]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for I64<O> where [u8; 8]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for Isize<O> where [u8; 8]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for U128<O> where [u8; 16]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for U16<O> where [u8; 2]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for U32<O> where [u8; 4]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for U64<O> where [u8; 8]: FromBytes, PhantomData<O>: FromBytes,
impl<O> FromBytes for Usize<O> where [u8; 8]: FromBytes, PhantomData<O>: FromBytes,
impl<T> FromBytes for CoreMaybeUninit<T>
impl<T> FromBytes for Unalign<T> where T: FromBytes,
impl<T: ?Sized + FromBytes> FromBytes for Cell<T>
impl<T: ?Sized + FromBytes> FromBytes for ManuallyDrop<T>
impl<T: ?Sized + FromBytes> FromBytes for ReadOnly<T>
impl<T: ?Sized + FromBytes> FromBytes for UnsafeCell<T>
impl<T: ?Sized> FromBytes for PhantomData<T>
impl<T: FromBytes> FromBytes for Wrapping<T>
impl<T: FromBytes> FromBytes for [T]
impl<T: FromBytes, const N: usize> FromBytes for [T; N]