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
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 toBox
andVec
. Note that thedocs.rs
documentation is always built withextern_crate_alloc
cargo feature enabled.
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]
. - Re-interprets
&[u8]
as&T
. - Re-interprets
&mut [u8]
as&mut T
. - As
align_to
, but safe because of thePod
bound. - 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
.