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:
T
usescast
&T
usescast_ref
&mut T
usescast_mut
&[T]
usescast_slice
&mut [T]
usescast_slice_mut
Depending on the function, the NoUninit
and/or AnyBitPattern
traits
are used to maintain memory safety.
Historical Note: When the crate first started the Pod
trait was used
instead, and so you may hear people refer to that, but it has the strongest
requirements and people eventually wanted the more fine-grained system, so
here we are. All types that impl Pod
have a blanket impl to also support
NoUninit
and AnyBitPattern
. The traits unfortunately do not have a
perfectly 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 reference given at runtime doesn’t have alignment 4.
In addition to the “normal” forms of each function, which will panic on
invalid input, there’s also try_
versions which will return a Result
.
If you would like to statically ensure that a cast will work at runtime you
can use the must_cast
crate feature and the must_
casting functions. A
“must cast” that can’t be statically known to be valid will cause a
compilation error (and sometimes a very hard to read compilation error).
§Using Your Own Types
All the functions listed above are guarded by the Pod
trait, which is a
sub-trait of the Zeroable
trait.
If you enable the crate’s derive
feature then these traits can be derived
on your own types. The derive macros will perform the necessary checks on
your type declaration, and trigger an error if your type does not qualify.
The derive macros might not cover all edge cases, and sometimes they will
error when actually everything is fine. As a last resort you can impl these
traits manually. However, these traits are unsafe
, and you should
carefully read the requirements before using a manual implementation.
§Cargo Features
The crate supports Rust 1.34 when no features are enabled, and so there’s cargo features for thing that you might consider “obvious”.
The cargo features do not promise any particular MSRV, and they may increase their MSRV in new versions.
derive
: Provide derive macros for the various traits.extern_crate_alloc
: Provide utilities foralloc
related types such as Box and Vec.zeroable_maybe_uninit
andzeroable_atomics
: Provide moreZeroable
impls.wasm_simd
andaarch64_simd
: Support more SIMD types.min_const_generics
: Provides appropriate impls for arrays of all lengths instead of just for a select list of array lengths.must_cast
: Provides themust_
functions, which will compile error if the requested cast can’t be statically verified.const_zeroed
: Provides a const version of thezeroed
function.
Re-exports§
pub use checked::CheckedBitPattern;
pub use allocation::*;
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”.
- A trait which indicates that a type is a
#[repr(transparent)]
wrapper around theInner
value. - Trait for types that can be safely created with
zeroed
.
Functions§
- Re-interprets
&T
as&[u8]
. - Re-interprets
&mut T
as&mut [u8]
. - Cast
T
intoU
- Cast
&mut T
into&mut U
. - Cast
&T
into&U
. - Cast
&[A]
into&[B]
. - Cast
&mut [T]
into&mut [U]
. - Fill all bytes of
slice
with zeroes (seeZeroable
). - Re-interprets
&[u8]
as&T
. - Re-interprets
&mut [u8]
as&mut T
. - Cast
A
intoB
if infalliable, or fail to compile. - Convert a
&mut A
into&mut B
if infalliable, or fail to compile. - Convert
&A
into&B
if infalliable, or fail to compile. - Convert
&[A]
into&[B]
(possibly with a change in length) if infalliable, or fail to compile. - Convert
&mut [A]
into&mut [B]
(possibly with a change in length) if infalliable, or fail to compile. - As
align_to_mut
, but safe because of thePod
bound. - Reads the slice into a
T
value. - Try to cast
T
intoU
. - 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
. - Fill all bytes of
target
with zeroes (seeZeroable
).
Derive Macros§
- Derive the
AnyBitPattern
trait for a struct - Derive the
PartialEq
andEq
trait for a type - Derive the
Hash
trait for a type - 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