| allocation.rs |
Stuff to boost things in the `alloc` crate.
* You must enable the `extern_crate_alloc` feature of `bytemuck` or you will
not be able to use this module! This is generally done by adding the
feature to the dependency in Cargo.toml like so:
`bytemuck = { version = "VERSION_YOU_ARE_USING", features =
["extern_crate_alloc"]}` |
36803 |
| anybitpattern.rs |
|
3011 |
| checked.rs |
Checked versions of the casting functions exposed in crate root
that support [`CheckedBitPattern`] types. |
16443 |
| contiguous.rs |
|
8420 |
| internal.rs |
Internal implementation of casting functions not bound by marker traits
and therefore marked as unsafe. This is used so that we don't need to
duplicate the business logic contained in these functions between the
versions exported in the crate root, `checked`, and `relaxed` modules. |
13278 |
| lib.rs |
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` uses [`cast`]
* `&T` uses [`cast_ref`]
* `&mut T` uses [`cast_mut`]
* `&[T]` uses [`cast_slice`]
* `&mut [T]` uses [`cast_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 (and [`f32::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 for `alloc` related types such as
Box and Vec.
* `zeroable_maybe_uninit` and `zeroable_atomics`: Provide more [`Zeroable`]
impls.
* `pod_saturating`: Provide more [`Pod`] and [`Zeroable`] impls.
* `wasm_simd` and `aarch64_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 the `must_` functions, which will compile error if
the requested cast can't be statically verified.
* `const_zeroed`: Provides a const version of the `zeroed` function.
## Related Crates
- [`pack1`](https://docs.rs/pack1), which contains `bytemuck`-compatible
packed little-endian, big-endian and native-endian integer and floating
point number types. |
19000 |
| must.rs |
|
7320 |
| no_uninit.rs |
|
3969 |
| offset_of.rs |
|
4997 |
| pod.rs |
|
7028 |
| pod_in_option.rs |
|
1020 |
| transparent.rs |
|
12031 |
| zeroable.rs |
|
9194 |
| zeroable_in_option.rs |
|
1408 |