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§
- 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§
- PodCast
Error - The things that can go wrong when casting between
Pod
data forms.
Traits§
- AnyBit
Pattern - 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”.
- PodIn
Option - Trait for types which are Pod when wrapped in Option.
- Transparent
Wrapper - A trait which indicates that a type is a
#[repr(transparent)]
wrapper around theInner
value. - Zeroable
- Trait for types that can be safely created with
zeroed
. - Zeroable
InOption - 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
A
intoB
- cast_
mut - Cast
&mut A
into&mut B
. - cast_
ref - Cast
&A
into&B
. - cast_
slice - Cast
&[A]
into&[B]
. - cast_
slice_ mut - Cast
&mut [A]
into&mut [B]
. - fill_
zeroes - Fill all bytes of
slice
with zeroes (seeZeroable
). - from_
bytes - Re-interprets
&[u8]
as&T
. - from_
bytes_ mut - Re-interprets
&mut [u8]
as&mut T
. - must_
cast - Cast
A
intoB
if infalliable, or fail to compile. - must_
cast_ mut - Convert a
&mut A
into&mut B
if infalliable, or fail to compile. - must_
cast_ ref - Convert
&A
into&B
if infalliable, or fail to compile. - must_
cast_ slice - Convert
&[A]
into&[B]
(possibly with a change in length) if infalliable, or fail to compile. - must_
cast_ slice_ mut - Convert
&mut [A]
into&mut [B]
(possibly with a change in length) if infalliable, or fail to compile. - pod_
align_ to - As
align_to
, but safe because of thePod
bound. - pod_
align_ to_ mut - As
align_to_mut
, but safe because of thePod
bound. - pod_
read_ unaligned - Reads the slice into a
T
value. - try_
cast - Try to cast
A
intoB
. - try_
cast_ mut - Try to convert a
&mut A
into&mut B
. - try_
cast_ ref - Try to convert a
&A
into&B
. - 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
. - write_
zeroes - Fill all bytes of
target
with zeroes (seeZeroable
).
Derive Macros§
- AnyBit
Pattern - Derive the
AnyBitPattern
trait for a struct - ByteEq
- Derive the
PartialEq
andEq
trait for a type - Byte
Hash - Derive the
Hash
trait for a type - Checked
BitPattern - 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 - Transparent
Wrapper - Derive the
TransparentWrapper
trait for a struct - Zeroable
- Derive the
Zeroable
trait for a type.