Crate bytemuck

wplot::color

Crate bytemuck 

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

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.
  • pack1, which contains bytemuck-compatible packed little-endian, big-endian and native-endian integer and floating point number types.

Modules§

__core
The Rust Core Library
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.

Structs§

BoxBytes
As Box<[u8]>, but remembers the original alignment.

Enums§

PodCastError
The things that can go wrong when casting between Pod data forms.

Traits§

AnyBitPattern
Marker trait for “plain old data” types that are valid for any bit pattern.
CheckedBitPattern
A marker trait that allows types that have some invalid bit patterns to be used in places that otherwise require AnyBitPattern or Pod types by performing a runtime check on a perticular set of bits. This is particularly useful for types like fieldless (‘C-style’) enums, char, bool, and structs containing them.
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”.
PodInOption
Trait for types which are Pod when wrapped in Option.
TransparentWrapper
A trait which indicates that a type is a #[repr(transparent)] wrapper around the Inner value.
TransparentWrapperAlloc
An extension trait for TransparentWrapper and alloc types.
Zeroable
Trait for types that can be safely created with zeroed.
ZeroableInOption
Trait for types which are Zeroable when wrapped in Option.

Functions§

box_bytes_of
Re-interprets Box<T> as BoxBytes.
bytes_of
Re-interprets &T as &[u8].
bytes_of_mut
Re-interprets &mut T as &mut [u8].
cast
Cast A into B
cast_arc
As try_cast_arc, but unwraps for you.
cast_box
As try_cast_box, but unwraps for you.
cast_mut
Cast &mut A into &mut B.
cast_rc
As try_cast_rc, but unwraps for you.
cast_ref
Cast &A into &B.
cast_slice
Cast &[A] into &[B].
cast_slice_arc
As try_cast_slice_arc, but unwraps for you.
cast_slice_box
As try_cast_slice_box, but unwraps for you.
cast_slice_mut
Cast &mut [A] into &mut [B].
cast_slice_rc
As try_cast_slice_rc, but unwraps for you.
cast_vec
As try_cast_vec, but unwraps for you.
fill_zeroes
Fill all bytes of slice with zeroes (see Zeroable).
from_box_bytes
Re-interprets BoxBytes as Box<T>.
from_bytes
Re-interprets &[u8] as &T.
from_bytes_mut
Re-interprets &mut [u8] as &mut T.
pod_align_to
As align_to, but safe because of the Pod bound.
pod_align_to_mut
As align_to_mut, but safe because of the Pod bound.
pod_collect_to_vec
This “collects” a slice of pod data into a vec of a different pod type.
pod_read_unaligned
Reads the slice into a T value.
try_cast
Try to cast A into B.
try_cast_arc
Attempts to cast the content type of a Arc.
try_cast_box
Attempts to cast the content type of a Box.
try_cast_mut
Try to convert a &mut A into &mut B.
try_cast_rc
Attempts to cast the content type of a Rc.
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_arc
Attempts to cast the content type of a Arc<[T]>.
try_cast_slice_box
Attempts to cast the content type of a Box<[T]>.
try_cast_slice_mut
Try to convert &mut [A] into &mut [B] (possibly with a change in length).
try_cast_slice_rc
Attempts to cast the content type of a Rc<[T]>.
try_cast_vec
Attempts to cast the content type of a Vec.
try_from_box_bytes
Re-interprets BoxBytes as Box<T>.
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.
try_zeroed_box
Allocates a Box<T> with all of the contents being zeroed out.
try_zeroed_slice_box
Allocates a Box<[T]> with all contents being zeroed out.
try_zeroed_vec
Allocates a Vec<T> of length and capacity exactly equal to length and all elements zeroed.
write_zeroes
Fill all bytes of target with zeroes (see Zeroable).
zeroed_box
As try_zeroed_box, but unwraps for you.
zeroed_slice_box
As try_zeroed_slice_box, but unwraps for you.
zeroed_vec
As try_zeroed_vec but unwraps for you