Crate bytemuck

This crate gives small utilities for casting between plain data types.

Basics

Data comes in five basic forms in Rust, so we have five basic casting functions:

• T uses cast
• &T uses cast_ref
• &mut T uses cast_mut
• &[T] uses cast_slice
• &mut [T] uses cast_slice_mut

Some casts will never fail (eg: cast::<u32, f32> always works), other casts might fail (eg: cast_ref::<[u8; 4], u32> will fail if the reference isn’t already aligned to 4). Each casting function has a “try” version which will return a Result, and the “normal” version which will simply panic on invalid input.

Using Your Own Types

All the functions here are guarded by the Pod trait, which is a sub-trait of the Zeroable trait.

If you’re very sure that your type is eligible, you can implement those traits for your type and then they’ll have full casting support. However, these traits are unsafe, and you should carefully read the requirements before adding the them to your own types.

Features

• This crate is core only by default, but if you’re using Rust 1.36 or later you can enable the extern_crate_alloc cargo feature for some additional methods related to Box and Vec. Note that the docs.rs documentation is always built with extern_crate_alloc cargo feature enabled.

Re-exports

• pub use checked::CheckedBitPattern;
• pub use allocation::*;

Modules

• allocation
  Stuff to boost things in the alloc crate.
• checked
  Checked versions of the casting functions exposed in crate root that support CheckedBitPattern types.

Macros

• offset_of
  Find the offset in bytes of the given $field of $Type. Requires an already initialized $instance value to work with.

Enums

• PodCastError
  The things that can go wrong when casting between Pod data forms.

Traits

• AnyBitPattern
  Marker trait for “plain old data” types that are valid for any bit pattern.
• Contiguous
  A trait indicating that:
• NoUninit
  Marker trait for “plain old data” types with no uninit (or padding) bytes.
• Pod
  Marker trait for “plain old data”.
• PodInOption
  Trait for types which are Pod when wrapped in Option.
• TransparentWrapper
  A trait which indicates that a type is a #[repr(transparent)] wrapper around the Inner value.
• Zeroable
  Trait for types that can be safely created with zeroed.
• ZeroableInOption
  Trait for types which are Zeroable when wrapped in Option.

Functions

• bytes_of
  Re-interprets &T as &[u8].
• bytes_of_mut
  Re-interprets &mut T as &mut [u8].
• cast
  Cast T into U
• cast_mut
  Cast &mut T into &mut U.
• cast_ref
  Cast &T into &U.
• cast_slice
  Cast &[A] into &[B].
• cast_slice_mut
  Cast &mut [T] into &mut [U].
• from_bytes
  Re-interprets &[u8] as &T.
• from_bytes_mut
  Re-interprets &mut [u8] as &mut T.
• pod_align_to
  As align_to, but safe because of the Pod bound.
• pod_align_to_mut
  As align_to_mut, but safe because of the Pod bound.
• pod_read_unaligned
  Reads the slice into a T value.
• try_cast
  Try to cast T into U.
• try_cast_mut
  Try to convert a &mut T into &mut U.
• try_cast_ref
  Try to convert a &T into &U.
• try_cast_slice
  Try to convert &[A] into &[B] (possibly with a change in length).
• try_cast_slice_mut
  Try to convert &mut [A] into &mut [B] (possibly with a change in length).
• try_from_bytes
  Re-interprets &[u8] as &T.
• try_from_bytes_mut
  Re-interprets &mut [u8] as &mut T.
• try_pod_read_unaligned
  Reads from the bytes as if they were a T.

Derive Macros

• AnyBitPattern
  Derive the AnyBitPattern trait for a struct
• ByteEq
  Derive the PartialEq and Eq trait for a type
• ByteHash
  Derive the Hash trait for a type
• CheckedBitPattern
  Derive the CheckedBitPattern trait for a struct or enum.
• Contiguous
  Derive the Contiguous trait for an enum
• NoUninit
  Derive the NoUninit trait for a struct or enum
• Pod
  Derive the Pod trait for a struct
• TransparentWrapper
  Derive the TransparentWrapper trait for a struct
• Zeroable
  Derive the Zeroable trait for a struct