Expand description

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:

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 allocation::*;
pub use checked::CheckedBitPattern;

Modules

Stuff to boost things in the alloc crate.

Checked versions of the casting functions exposed in crate root that support CheckedBitPattern types.

Macros

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

Enums

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

Traits

Marker trait for “plain old data” types that are valid for any bit pattern.

A trait indicating that:

Marker trait for “plain old data” types with no uninit (or padding) bytes.

Marker trait for “plain old data”.

Trait for types which are Pod when wrapped in Option.

A trait which indicates that a type is a #[repr(transparent)] wrapper around the Inner value.

Trait for types that can be safely created with zeroed.

Trait for types which are Zeroable when wrapped in Option.

Functions

Re-interprets &T as &[u8].

Re-interprets &mut T as &mut [u8].

Cast T into U

Cast &mut T into &mut U.

Cast &T into &U.

Cast &[A] into &[B].

Cast &mut [T] into &mut [U].

Re-interprets &[u8] as &T.

Re-interprets &mut [u8] as &mut T.

As align_to, but safe because of the Pod bound.

As align_to_mut, but safe because of the Pod bound.

Reads the slice into a T value.

Try to cast T into U.

Try to convert a &mut T into &mut U.

Try to convert a &T into &U.

Try to convert &[A] into &[B] (possibly with a change in length).

Try to convert &mut [A] into &mut [B] (possibly with a change in length).

Re-interprets &[u8] as &T.

Re-interprets &mut [u8] as &mut T.

Reads from the bytes as if they were a T.

Derive Macros

Derive the AnyBitPattern trait for a struct

Derive the CheckedBitPattern trait for a struct or enum.

Derive the Contiguous trait for an enum

Derive the NoUninit trait for a struct or enum

Derive the Pod trait for a struct

Derive the TransparentWrapper trait for a struct

Derive the Zeroable trait for a struct