Macro transmute 

macro_rules! transmute {
    (#![allow(shrink)] $e:expr) => { ... };
    ($e:expr) => { ... };
}

Safely transmutes a value of one type to a value of another type of the same size.

This macro behaves like an invocation of this function:

const fn transmute<Src, Dst>(src: Src) -> Dst
where
    Src: IntoBytes,
    Dst: FromBytes,
    size_of::<Src>() == size_of::<Dst>(),
{
    ...
}

However, unlike a function, this macro can only be invoked when the types of Src and Dst are completely concrete. The types Src and Dst are inferred from the calling context; they cannot be explicitly specified in the macro invocation.

Note that the Src produced by the expression $e will not be dropped. Semantically, its bits will be copied into a new value of type Dst, the original Src will be forgotten, and the value of type Dst will be returned.

#![allow(shrink)]

If #![allow(shrink)] is provided, transmute! additionally supports transmutations that shrink the size of the value; e.g.:

let u: u32 = transmute!(#![allow(shrink)] 0u64);
assert_eq!(u, 0u32);

Examples

let one_dimensional: [u8; 8] = [0, 1, 2, 3, 4, 5, 6, 7];

let two_dimensional: [[u8; 4]; 2] = transmute!(one_dimensional);

assert_eq!(two_dimensional, [[0, 1, 2, 3], [4, 5, 6, 7]]);

Use in const contexts

This macro can be invoked in const contexts.

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.

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)]
#[repr(C, align(2))]
pub struct Packet<Magic> {
   magic_number: Magic,
   mug_size: u8,
   temperature: u8,
   marshmallows: [u8; 2],
}

/// 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::Unalign;
use zerocopy_derive::*;

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

#[derive(IntoBytes, KnownLayout, Immutable)]
#[repr(C)]
struct MinimalViableSource {
   bytes: [u8; 6],
}

#[unsafe(no_mangle)]
fn bench_transmute(source: MinimalViableSource) -> Unalign<format::LocoPacket> {
   zerocopy::transmute!(source)
}

Assembly

bench_transmute:
   mov rax, rdi
   ret

Machine Code Analysis

Iterations:        100
Instructions:      200
Total Cycles:      104
Total uOps:        200

Dispatch Width:    4
uOps Per Cycle:    1.92
IPC:               1.92
Block RThroughput: 1.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      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]  
-      -     0.49   0.50    -     1.01    -      -     

Resource pressure by instruction:
[0]    [1]    [2]    [3]    [4]    [5]    [6.0]  [6.1]  Instructions:
-      -     0.49   0.50    -     0.01    -      -     mov	rax, rdi
-      -      -      -      -     1.00    -      -     ret