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

• T usescast
• &T usescast_ref
• &mut T usescast_mut
• &[T] usescast_slice
• &mut [T] usescast_slice_mut

Depending on the function, theNoUninit and/orAnyBitPattern traitsare used to maintain memory safety.

Historical Note: When the crate first started thePod trait was usedinstead, and so you may hear people refer to that, but it has the strongestrequirements and people eventually wanted the more fine-grained system, sohere we are. All types that implPod have a blanket impl to also supportNoUninit andAnyBitPattern. The traits unfortunately do not have aperfectly clean hierarchy for semver reasons.

§Failures

Some casts will never fail, and other casts might fail.

• cast::<u32, f32> always works (andf32::from_bits).
• cast_ref::<[u8; 4], u32> might fail if the specific array referencegiven at runtime doesn’t have alignment 4.

In addition to the “normal” forms of each function, which will panic oninvalid input, there’s alsotry_ versions which will return aResult.

If you would like to statically ensure that a cast will work at runtime youcan use themust_cast crate feature and themust_ casting functions. A“must cast” that can’t be statically known to be valid will cause acompilation error (and sometimes a very hard to read compilation error).

§Using Your Own Types

All the functions listed above are guarded by thePod trait, which is asub-trait of theZeroable trait.

If you enable the crate’sderive feature then these traits can be derivedon your own types. The derive macros will perform the necessary checks onyour type declaration, and trigger an error if your type does not qualify.

The derive macros might not cover all edge cases, and sometimes they willerror when actually everything is fine. As a last resort you can impl thesetraits manually. However, these traits areunsafe, and you shouldcarefully read the requirements before using a manual implementation.

§Cargo Features

The crate supports Rust 1.34 when no features are enabled, and so there’scargo features for thing that you might consider “obvious”.

The cargo featuresdo not promise any particular MSRV, and they mayincrease their MSRV in new versions.

• derive: Provide derive macros for the various traits.
• extern_crate_alloc: Provide utilities foralloc related types such asBox and Vec.
• zeroable_maybe_uninit andzeroable_atomics: Provide moreZeroableimpls.
• pod_saturating: Provide morePod andZeroable impls.
• wasm_simd andaarch64_simd: Support more SIMD types.
• min_const_generics: Provides appropriate impls for arrays of all lengthsinstead of just for a select list of array lengths.
• must_cast: Provides themust_ functions, which will compile error ifthe requested cast can’t be statically verified.
• const_zeroed: Provides a const version of thezeroed function.

§Related Crates

• pack1, which containsbytemuck-compatiblepacked little-endian, big-endian and native-endian integer and floatingpoint number types.