Struct Split

pub struct Split<T> { /* private fields */ }

A T that has been split into two possibly-overlapping parts.

For some dynamically sized types, the padding that appears after the trailing slice field is a dynamic function of the trailing slice length. If T is split at a length that requires trailing padding, the trailing padding of the left part of the split T will overlap the right part. If T is a mutable reference or permits interior mutation, you must ensure that the left and right parts do not overlap. You can do this at zero-cost using using Self::via_immutable, Self::via_into_bytes, or Self::via_unaligned, or with a dynamic check by using Self::via_runtime_check.

Implementations

impl<'a, T> Split<&'a T> where T: ?Sized + SplitAt,

fn via_immutable(self) -> (&'a T, &'a [T::Elem])
where
    T: Immutable,

Produces the split parts of self, using Immutable to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

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

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

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

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

// Attempt to split `packet` at `length`.
let split = packet.split_at(packet.length as usize).unwrap();

// Use the `Immutable` bound on `Packet` to prove that it's okay to
// return concurrent references to `packet` and `rest`.
let (packet, rest) = split.via_immutable();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4]);
assert_eq!(rest, [5, 6, 7, 8, 9]);
§ 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:

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
 
use zerocopy::*;

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

#[unsafe(no_mangle)]
fn bench_split_via_immutable_dynamic_size(
   split: Split<&format::CocoPacket>,
) -> (&format::CocoPacket, &[[u8; 2]]) {
   split.via_immutable()
}
Assembly
 
bench_split_via_immutable_dynamic_size:
   mov rax, rdi
   mov rcx, qword ptr [rsi]
   mov rdx, qword ptr [rsi + 8]
   mov rsi, qword ptr [rsi + 16]
   lea rdi, [rcx + 2*rsi]
   add rdi, 4
   sub rdx, rsi
   mov qword ptr [rax], rcx
   mov qword ptr [rax + 8], rsi
   mov qword ptr [rax + 16], rdi
   mov qword ptr [rax + 24], rdx
   ret
Machine Code Analysis
 
Iterations:        100
Instructions:      1200
Total Cycles:      509
Total uOps:        1200

Dispatch Width:    4
uOps Per Cycle:    2.36
IPC:               2.36
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      1     0.33                        mov	rax, rdi
1      5     0.50    *                   mov	rcx, qword ptr [rsi]
1      5     0.50    *                   mov	rdx, qword ptr [rsi + 8]
1      5     0.50    *                   mov	rsi, qword ptr [rsi + 16]
1      1     0.50                        lea	rdi, [rcx + 2*rsi]
1      1     0.33                        add	rdi, 4
1      1     0.33                        sub	rdx, rsi
1      1     1.00           *            mov	qword ptr [rax], rcx
1      1     1.00           *            mov	qword ptr [rax + 8], rsi
1      1     1.00           *            mov	qword ptr [rax + 16], rdi
1      1     1.00           *            mov	qword ptr [rax + 24], rdx
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]  
-      -     1.66   1.66   4.00   1.68   3.50   3.50   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.34   0.33    -     0.33    -      -     mov	rax, rdi
-      -      -      -      -      -     0.49   0.51   mov	rcx, qword ptr [rsi]
-      -      -      -      -      -     0.51   0.49   mov	rdx, qword ptr [rsi + 8]
-      -      -      -      -      -     0.01   0.99   mov	rsi, qword ptr [rsi + 16]
-      -     0.33   0.67    -      -      -      -     lea	rdi, [rcx + 2*rsi]
-      -     0.63   0.34    -     0.03    -      -     add	rdi, 4
-      -     0.36   0.32    -     0.32    -      -     sub	rdx, rsi
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax], rcx
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax + 8], rsi
-      -      -      -     1.00    -     0.98   0.02   mov	qword ptr [rax + 16], rdi
-      -      -      -     1.00    -     0.51   0.49   mov	qword ptr [rax + 24], rdx
-      -      -      -      -     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
 
use zerocopy::*;

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

#[unsafe(no_mangle)]
fn bench_split_via_immutable_dynamic_padding(
   split: Split<&format::CocoPacket>,
) -> (&format::CocoPacket, &[[u8; 3]]) {
   split.via_immutable()
}
Assembly
 
bench_split_via_immutable_dynamic_padding:
   mov rax, rdi
   mov rcx, qword ptr [rsi]
   mov rdx, qword ptr [rsi + 8]
   mov rsi, qword ptr [rsi + 16]
   lea rdi, [rsi + 2*rsi]
   add rdi, rcx
   add rdi, 9
   sub rdx, rsi
   mov qword ptr [rax], rcx
   mov qword ptr [rax + 8], rsi
   mov qword ptr [rax + 16], rdi
   mov qword ptr [rax + 24], rdx
   ret
Machine Code Analysis
 
Iterations:        100
Instructions:      1300
Total Cycles:      510
Total uOps:        1300

Dispatch Width:    4
uOps Per Cycle:    2.55
IPC:               2.55
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      1     0.33                        mov	rax, rdi
1      5     0.50    *                   mov	rcx, qword ptr [rsi]
1      5     0.50    *                   mov	rdx, qword ptr [rsi + 8]
1      5     0.50    *                   mov	rsi, qword ptr [rsi + 16]
1      1     0.50                        lea	rdi, [rsi + 2*rsi]
1      1     0.33                        add	rdi, rcx
1      1     0.33                        add	rdi, 9
1      1     0.33                        sub	rdx, rsi
1      1     1.00           *            mov	qword ptr [rax], rcx
1      1     1.00           *            mov	qword ptr [rax + 8], rsi
1      1     1.00           *            mov	qword ptr [rax + 16], rdi
1      1     1.00           *            mov	qword ptr [rax + 24], rdx
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.00   2.00   4.00   2.00   3.50   3.50   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.03   0.93    -     0.04    -      -     mov	rax, rdi
-      -      -      -      -      -     0.49   0.51   mov	rcx, qword ptr [rsi]
-      -      -      -      -      -     1.00    -     mov	rdx, qword ptr [rsi + 8]
-      -      -      -      -      -     0.01   0.99   mov	rsi, qword ptr [rsi + 16]
-      -     0.93   0.07    -      -      -      -     lea	rdi, [rsi + 2*rsi]
-      -     0.05   0.02    -     0.93    -      -     add	rdi, rcx
-      -     0.49   0.49    -     0.02    -      -     add	rdi, 9
-      -     0.50   0.49    -     0.01    -      -     sub	rdx, rsi
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax], rcx
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax + 8], rsi
-      -      -      -     1.00    -     0.49   0.51   mov	qword ptr [rax + 16], rdi
-      -      -      -     1.00    -     0.51   0.49   mov	qword ptr [rax + 24], rdx
-      -      -      -      -     1.00    -      -     ret


fn via_into_bytes(self) -> (&'a T, &'a [T::Elem])
where
    T: IntoBytes,

Produces the split parts of self, using IntoBytes to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(C)]
struct Packet<B: ?Sized> {
    length: u8,
    body: B,
}

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

let packet = Packet::<[u8]>::ref_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

// Attempt to split `packet` at `length`.
let split = packet.split_at(packet.length as usize).unwrap();

// Use the `IntoBytes` bound on `Packet` to prove that it's okay to
// return concurrent references to `packet` and `rest`.
let (packet, rest) = split.via_into_bytes();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4]);
assert_eq!(rest, [5, 6, 7, 8, 9]);
§ Code Generation

See Split::via_immutable.

fn via_unaligned(self) -> (&'a T, &'a [T::Elem])
where
    T: Unaligned,

Produces the split parts of self, using Unaligned to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C)]
struct Packet {
    length: u8,
    body: [u8],
}

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

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

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

// Attempt to split `packet` at `length`.
let split = packet.split_at(packet.length as usize).unwrap();

// Use the `Unaligned` bound on `Packet` to prove that it's okay to
// return concurrent references to `packet` and `rest`.
let (packet, rest) = split.via_unaligned();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4]);
assert_eq!(rest, [5, 6, 7, 8, 9]);
§ Code Generation

See Split::via_immutable.

fn via_runtime_check(self) -> Result<(&'a T, &'a [T::Elem]), Self>

Produces the split parts of self, using a dynamic check to ensure that it is sound to have concurrent references to both parts. You should prefer using Self::via_immutable, Self::via_into_bytes, or Self::via_unaligned, which have no runtime cost.

Note that this check is overly conservative if T is Immutable; for some types, this check will reject some splits which Self::via_immutable will accept.

Examples

use zerocopy::{SplitAt, FromBytes, IntoBytes, network_endian::U16};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, Immutable, Debug)]
#[repr(C, align(2))]
struct Packet {
    length: U16,
    body: [u8],
}

// These bytes encode a `Packet`.
let bytes = [
    4u16.to_be(),
    1u16.to_be(),
    2u16.to_be(),
    3u16.to_be(),
    4u16.to_be()
];

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

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [0, 1, 0, 2, 0, 3, 0, 4]);

// Attempt to split `packet` at `length`.
let split = packet.split_at(packet.length.into()).unwrap();

// Use a dynamic check to prove that it's okay to return concurrent
// references to `packet` and `rest`.
let (packet, rest) = split.via_runtime_check().unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [0, 1, 0, 2]);
assert_eq!(rest, [0, 3, 0, 4]);

// Attempt to split `packet` at `length - 1`.
let idx = packet.length.get() - 1;
let split = packet.split_at(idx as usize).unwrap();

// Attempt (and fail) to use a dynamic check to prove that it's okay
// to return concurrent references to `packet` and `rest`. Note that
// this is a case of `via_runtime_check` being overly conservative.
// Although the left and right parts indeed overlap, the `Immutable`
// bound ensures that concurrently referencing these overlapping
// parts is sound.
assert!(split.via_runtime_check().is_err());
§ 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:

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
 
use zerocopy::*;

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

#[unsafe(no_mangle)]
fn bench_split_via_runtime_check_dynamic_size(
   split: Split<&format::CocoPacket>,
) -> Option<(&format::CocoPacket, &[[u8; 2]])> {
   split.via_runtime_check().ok()
}
Assembly
 
bench_split_via_runtime_check_dynamic_size:
   mov rax, rdi
   mov rcx, qword ptr [rsi]
   mov rdx, qword ptr [rsi + 8]
   mov rsi, qword ptr [rsi + 16]
   lea rdi, [rcx + 2*rsi]
   add rdi, 4
   sub rdx, rsi
   mov qword ptr [rax], rcx
   mov qword ptr [rax + 8], rsi
   mov qword ptr [rax + 16], rdi
   mov qword ptr [rax + 24], rdx
   ret
Machine Code Analysis
 
Iterations:        100
Instructions:      1200
Total Cycles:      509
Total uOps:        1200

Dispatch Width:    4
uOps Per Cycle:    2.36
IPC:               2.36
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      1     0.33                        mov	rax, rdi
1      5     0.50    *                   mov	rcx, qword ptr [rsi]
1      5     0.50    *                   mov	rdx, qword ptr [rsi + 8]
1      5     0.50    *                   mov	rsi, qword ptr [rsi + 16]
1      1     0.50                        lea	rdi, [rcx + 2*rsi]
1      1     0.33                        add	rdi, 4
1      1     0.33                        sub	rdx, rsi
1      1     1.00           *            mov	qword ptr [rax], rcx
1      1     1.00           *            mov	qword ptr [rax + 8], rsi
1      1     1.00           *            mov	qword ptr [rax + 16], rdi
1      1     1.00           *            mov	qword ptr [rax + 24], rdx
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]  
-      -     1.66   1.66   4.00   1.68   3.50   3.50   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.34   0.33    -     0.33    -      -     mov	rax, rdi
-      -      -      -      -      -     0.49   0.51   mov	rcx, qword ptr [rsi]
-      -      -      -      -      -     0.51   0.49   mov	rdx, qword ptr [rsi + 8]
-      -      -      -      -      -     0.01   0.99   mov	rsi, qword ptr [rsi + 16]
-      -     0.33   0.67    -      -      -      -     lea	rdi, [rcx + 2*rsi]
-      -     0.63   0.34    -     0.03    -      -     add	rdi, 4
-      -     0.36   0.32    -     0.32    -      -     sub	rdx, rsi
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax], rcx
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax + 8], rsi
-      -      -      -     1.00    -     0.98   0.02   mov	qword ptr [rax + 16], rdi
-      -      -      -     1.00    -     0.51   0.49   mov	qword ptr [rax + 24], rdx
-      -      -      -      -     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
 
use zerocopy::*;

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

#[unsafe(no_mangle)]
fn bench_split_via_runtime_check_dynamic_padding(
   split: Split<&format::CocoPacket>,
) -> Option<(&format::CocoPacket, &[[u8; 3]])> {
   split.via_runtime_check().ok()
}
Assembly
 
bench_split_via_runtime_check_dynamic_padding:
   mov rax, rdi
   mov rdx, qword ptr [rsi + 16]
   mov ecx, edx
   and ecx, 3
   cmp ecx, 1
   jne .LBB5_1
   mov rcx, qword ptr [rsi]
   mov rsi, qword ptr [rsi + 8]
   lea rdi, [rdx + 2*rdx]
   add rdi, rcx
   add rdi, 9
   sub rsi, rdx
   mov qword ptr [rax + 8], rdx
   mov qword ptr [rax + 16], rdi
   mov qword ptr [rax + 24], rsi
   mov qword ptr [rax], rcx
   ret
.LBB5_1:
   xor ecx, ecx
   mov qword ptr [rax], rcx
   ret
Machine Code Analysis
 
Iterations:        100
Instructions:      2000
Total Cycles:      708
Total uOps:        2000

Dispatch Width:    4
uOps Per Cycle:    2.82
IPC:               2.82
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	rax, rdi
1      5     0.50    *                   mov	rdx, qword ptr [rsi + 16]
1      1     0.33                        mov	ecx, edx
1      1     0.33                        and	ecx, 3
1      1     0.33                        cmp	ecx, 1
1      1     1.00                        jne	.LBB5_1
1      5     0.50    *                   mov	rcx, qword ptr [rsi]
1      5     0.50    *                   mov	rsi, qword ptr [rsi + 8]
1      1     0.50                        lea	rdi, [rdx + 2*rdx]
1      1     0.33                        add	rdi, rcx
1      1     0.33                        add	rdi, 9
1      1     0.33                        sub	rsi, rdx
1      1     1.00           *            mov	qword ptr [rax + 8], rdx
1      1     1.00           *            mov	qword ptr [rax + 16], rdi
1      1     1.00           *            mov	qword ptr [rax + 24], rsi
1      1     1.00           *            mov	qword ptr [rax], rcx
1      1     1.00                  U     ret
1      0     0.25                        xor	ecx, ecx
1      1     1.00           *            mov	qword ptr [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.00   3.02   5.00   4.98   4.00   4.00   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -      -     0.99    -     0.01    -      -     mov	rax, rdi
-      -      -      -      -      -      -     1.00   mov	rdx, qword ptr [rsi + 16]
-      -     0.99   0.01    -      -      -      -     mov	ecx, edx
-      -     0.99   0.01    -      -      -      -     and	ecx, 3
-      -     0.97   0.03    -      -      -      -     cmp	ecx, 1
-      -      -      -      -     1.00    -      -     jne	.LBB5_1
-      -      -      -      -      -     1.00    -     mov	rcx, qword ptr [rsi]
-      -      -      -      -      -     0.99   0.01   mov	rsi, qword ptr [rsi + 8]
-      -     0.01   0.99    -      -      -      -     lea	rdi, [rdx + 2*rdx]
-      -      -     0.96    -     0.04    -      -     add	rdi, rcx
-      -     0.03    -      -     0.97    -      -     add	rdi, 9
-      -     0.01   0.03    -     0.96    -      -     sub	rsi, rdx
-      -      -      -     1.00    -     1.00    -     mov	qword ptr [rax + 8], rdx
-      -      -      -     1.00    -      -     1.00   mov	qword ptr [rax + 16], rdi
-      -      -      -     1.00    -     0.01   0.99   mov	qword ptr [rax + 24], rsi
-      -      -      -     1.00    -     0.99   0.01   mov	qword ptr [rax], rcx
-      -      -      -      -     1.00    -      -     ret
-      -      -      -      -      -      -      -     xor	ecx, ecx
-      -      -      -     1.00    -     0.01   0.99   mov	qword ptr [rax], rcx
-      -      -      -      -     1.00    -      -     ret


unsafe fn via_unchecked(self) -> (&'a T, &'a [T::Elem])

Unsafely produces the split parts of self.

Safety

If T permits interior mutation, the trailing padding bytes of the left portion must not overlap the right portion. For some dynamically sized types, the padding that appears after the trailing slice field is a dynamic function of the trailing slice length. Thus, for some types, this condition is dependent on the length of the left portion.

§ 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:

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
 
use zerocopy::*;

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

#[unsafe(no_mangle)]
unsafe fn bench_split_via_unchecked_dynamic_size(
   split: Split<&format::CocoPacket>,
) -> (&format::CocoPacket, &[[u8; 2]]) {
   unsafe { split.via_unchecked() }
}
Assembly
 
bench_split_via_unchecked_dynamic_size:
   mov rax, rdi
   mov rcx, qword ptr [rsi]
   mov rdx, qword ptr [rsi + 8]
   mov rsi, qword ptr [rsi + 16]
   lea rdi, [rcx + 2*rsi]
   add rdi, 4
   sub rdx, rsi
   mov qword ptr [rax], rcx
   mov qword ptr [rax + 8], rsi
   mov qword ptr [rax + 16], rdi
   mov qword ptr [rax + 24], rdx
   ret
Machine Code Analysis
 
Iterations:        100
Instructions:      1200
Total Cycles:      509
Total uOps:        1200

Dispatch Width:    4
uOps Per Cycle:    2.36
IPC:               2.36
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      1     0.33                        mov	rax, rdi
1      5     0.50    *                   mov	rcx, qword ptr [rsi]
1      5     0.50    *                   mov	rdx, qword ptr [rsi + 8]
1      5     0.50    *                   mov	rsi, qword ptr [rsi + 16]
1      1     0.50                        lea	rdi, [rcx + 2*rsi]
1      1     0.33                        add	rdi, 4
1      1     0.33                        sub	rdx, rsi
1      1     1.00           *            mov	qword ptr [rax], rcx
1      1     1.00           *            mov	qword ptr [rax + 8], rsi
1      1     1.00           *            mov	qword ptr [rax + 16], rdi
1      1     1.00           *            mov	qword ptr [rax + 24], rdx
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]  
-      -     1.66   1.66   4.00   1.68   3.50   3.50   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.34   0.33    -     0.33    -      -     mov	rax, rdi
-      -      -      -      -      -     0.49   0.51   mov	rcx, qword ptr [rsi]
-      -      -      -      -      -     0.51   0.49   mov	rdx, qword ptr [rsi + 8]
-      -      -      -      -      -     0.01   0.99   mov	rsi, qword ptr [rsi + 16]
-      -     0.33   0.67    -      -      -      -     lea	rdi, [rcx + 2*rsi]
-      -     0.63   0.34    -     0.03    -      -     add	rdi, 4
-      -     0.36   0.32    -     0.32    -      -     sub	rdx, rsi
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax], rcx
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax + 8], rsi
-      -      -      -     1.00    -     0.98   0.02   mov	qword ptr [rax + 16], rdi
-      -      -      -     1.00    -     0.51   0.49   mov	qword ptr [rax + 24], rdx
-      -      -      -      -     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
 
use zerocopy::*;

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

#[unsafe(no_mangle)]
unsafe fn bench_split_via_unchecked_dynamic_padding(
   split: Split<&format::CocoPacket>,
) -> (&format::CocoPacket, &[[u8; 3]]) {
   unsafe { split.via_unchecked() }
}
Assembly
 
bench_split_via_unchecked_dynamic_padding:
   mov rax, rdi
   mov rcx, qword ptr [rsi]
   mov rdx, qword ptr [rsi + 8]
   mov rsi, qword ptr [rsi + 16]
   lea rdi, [rsi + 2*rsi]
   add rdi, rcx
   add rdi, 9
   sub rdx, rsi
   mov qword ptr [rax], rcx
   mov qword ptr [rax + 8], rsi
   mov qword ptr [rax + 16], rdi
   mov qword ptr [rax + 24], rdx
   ret
Machine Code Analysis
 
Iterations:        100
Instructions:      1300
Total Cycles:      510
Total uOps:        1300

Dispatch Width:    4
uOps Per Cycle:    2.55
IPC:               2.55
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      1     0.33                        mov	rax, rdi
1      5     0.50    *                   mov	rcx, qword ptr [rsi]
1      5     0.50    *                   mov	rdx, qword ptr [rsi + 8]
1      5     0.50    *                   mov	rsi, qword ptr [rsi + 16]
1      1     0.50                        lea	rdi, [rsi + 2*rsi]
1      1     0.33                        add	rdi, rcx
1      1     0.33                        add	rdi, 9
1      1     0.33                        sub	rdx, rsi
1      1     1.00           *            mov	qword ptr [rax], rcx
1      1     1.00           *            mov	qword ptr [rax + 8], rsi
1      1     1.00           *            mov	qword ptr [rax + 16], rdi
1      1     1.00           *            mov	qword ptr [rax + 24], rdx
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.00   2.00   4.00   2.00   3.50   3.50   

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.03   0.93    -     0.04    -      -     mov	rax, rdi
-      -      -      -      -      -     0.49   0.51   mov	rcx, qword ptr [rsi]
-      -      -      -      -      -     1.00    -     mov	rdx, qword ptr [rsi + 8]
-      -      -      -      -      -     0.01   0.99   mov	rsi, qword ptr [rsi + 16]
-      -     0.93   0.07    -      -      -      -     lea	rdi, [rsi + 2*rsi]
-      -     0.05   0.02    -     0.93    -      -     add	rdi, rcx
-      -     0.49   0.49    -     0.02    -      -     add	rdi, 9
-      -     0.50   0.49    -     0.01    -      -     sub	rdx, rsi
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax], rcx
-      -      -      -     1.00    -     0.50   0.50   mov	qword ptr [rax + 8], rsi
-      -      -      -     1.00    -     0.49   0.51   mov	qword ptr [rax + 16], rdi
-      -      -      -     1.00    -     0.51   0.49   mov	qword ptr [rax + 24], rdx
-      -      -      -      -     1.00    -      -     ret

impl<'a, T> Split<&'a mut T> where T: ?Sized + SplitAt,

fn via_into_bytes(self) -> (&'a mut T, &'a mut [T::Elem])
where
    T: IntoBytes,

Produces the split parts of self, using IntoBytes to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, IntoBytes)]
#[repr(C)]
struct Packet<B: ?Sized> {
    length: u8,
    body: B,
}

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

let packet = Packet::<[u8]>::mut_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

{
    // Attempt to split `packet` at `length`.
    let split = packet.split_at_mut(packet.length as usize).unwrap();

    // Use the `IntoBytes` bound on `Packet` to prove that it's okay to
    // return concurrent references to `packet` and `rest`.
    let (packet, rest) = split.via_into_bytes();

    assert_eq!(packet.length, 4);
    assert_eq!(packet.body, [1, 2, 3, 4]);
    assert_eq!(rest, [5, 6, 7, 8, 9]);

    rest.fill(0);
}

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 0, 0, 0, 0, 0]);

Code Generation

See Split::via_immutable.

fn via_unaligned(self) -> (&'a mut T, &'a mut [T::Elem])
where
    T: Unaligned,

Produces the split parts of self, using Unaligned to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, IntoBytes, Unaligned)]
#[repr(C)]
struct Packet<B: ?Sized> {
    length: u8,
    body: B,
}

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

let packet = Packet::<[u8]>::mut_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

{
    // Attempt to split `packet` at `length`.
    let split = packet.split_at_mut(packet.length as usize).unwrap();

    // Use the `Unaligned` bound on `Packet` to prove that it's okay to
    // return concurrent references to `packet` and `rest`.
    let (packet, rest) = split.via_unaligned();

    assert_eq!(packet.length, 4);
    assert_eq!(packet.body, [1, 2, 3, 4]);
    assert_eq!(rest, [5, 6, 7, 8, 9]);

    rest.fill(0);
}

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 0, 0, 0, 0, 0]);

Code Generation

See Split::via_immutable.

fn via_runtime_check(self) -> Result<(&'a mut T, &'a mut [T::Elem]), Self>

Produces the split parts of self, using a dynamic check to ensure that it is sound to have concurrent references to both parts. You should prefer using Self::via_into_bytes or Self::via_unaligned, which have no runtime cost.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, IntoBytes, Debug)]
#[repr(C)]
struct Packet<B: ?Sized> {
    length: u8,
    body: B,
}

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

let packet = Packet::<[u8]>::mut_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

{
    // Attempt to split `packet` at `length`.
    let split = packet.split_at_mut(packet.length as usize).unwrap();

    // Use a dynamic check to prove that it's okay to return concurrent
    // references to `packet` and `rest`.
    let (packet, rest) = split.via_runtime_check().unwrap();

    assert_eq!(packet.length, 4);
    assert_eq!(packet.body, [1, 2, 3, 4]);
    assert_eq!(rest, [5, 6, 7, 8, 9]);

    rest.fill(0);
}

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 0, 0, 0, 0, 0]);

Code Generation

See Split::via_runtime_check.

unsafe fn via_unchecked(self) -> (&'a mut T, &'a mut [T::Elem])

Unsafely produces the split parts of self.

Safety

The trailing padding bytes of the left portion must not overlap the right portion. For some dynamically sized types, the padding that appears after the trailing slice field is a dynamic function of the trailing slice length. Thus, for some types, this condition is dependent on the length of the left portion.

Code Generation

See Split::via_unchecked.

Trait Implementations

impl<T: Debug> Debug for Split<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Auto Trait Implementations

impl<T> Freeze for Split<T> where T: Freeze,

impl<T> RefUnwindSafe for Split<T> where T: RefUnwindSafe,

impl<T> Send for Split<T> where T: Send,

impl<T> Sync for Split<T> where T: Sync,

impl<T> Unpin for Split<T> where T: Unpin,

impl<T> UnsafeUnpin for Split<T> where T: UnsafeUnpin,

impl<T> UnwindSafe for Split<T> where T: UnwindSafe,

Blanket Implementations

impl<T> Any for Split<T> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Split<T> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Split<T> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for Split<T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into<U> for Split<T> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for Split<T> where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for Split<T> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>