1 #![no_std]
2 #![warn(missing_docs)]
3
4 //! This crate gives small utilities for casting between plain data types.
5 //!
6 //! ## Basics
7 //!
8 //! Data comes in five basic forms in Rust, so we have five basic casting
9 //! functions:
10 //!
11 //! * `T` uses [`cast`]
12 //! * `&T` uses [`cast_ref`]
13 //! * `&mut T` uses [`cast_mut`]
14 //! * `&[T]` uses [`cast_slice`]
15 //! * `&mut [T]` uses [`cast_slice_mut`]
16 //!
17 //! Some casts will never fail (eg: `cast::<u32, f32>` always works), other
18 //! casts might fail (eg: `cast_ref::<[u8; 4], u32>` will fail if the reference
19 //! isn't already aligned to 4). Each casting function has a "try" version which
20 //! will return a `Result`, and the "normal" version which will simply panic on
21 //! invalid input.
22 //!
23 //! ## Using Your Own Types
24 //!
25 //! All the functions here are guarded by the [`Pod`] trait, which is a
26 //! sub-trait of the [`Zeroable`] trait.
27 //!
28 //! If you're very sure that your type is eligible, you can implement those
29 //! traits for your type and then they'll have full casting support. However,
30 //! these traits are `unsafe`, and you should carefully read the requirements
31 //! before adding the them to your own types.
32 //!
33 //! ## Features
34 //!
35 //! * This crate is core only by default, but if you're using Rust 1.36 or later
36 //! you can enable the `extern_crate_alloc` cargo feature for some additional
37 //! methods related to `Box` and `Vec`. Note that the `docs.rs` documentation
38 //! is always built with `extern_crate_alloc` cargo feature enabled.
39
40 #[cfg(target_arch = "x86")]
41 use core::arch::x86;
42 #[cfg(target_arch = "x86_64")]
43 use core::arch::x86_64;
44 //
45 use core::{marker::*, mem::*, num::*, ptr::*};
46
47 // Used from macros to ensure we aren't using some locally defined name and
48 // actually are referencing libcore. This also would allow pre-2018 edition
49 // crates to use our macros, but I'm not sure how important that is.
50 #[doc(hidden)]
51 pub use ::core as __core;
52
53 #[cfg(not(feature = "min_const_generics"))]
54 macro_rules! impl_unsafe_marker_for_array {
55 ( $marker:ident , $( $n:expr ),* ) => {
56 $(unsafe impl<T> $marker for [T; $n] where T: $marker {})*
57 }
58 }
59
60 /// A macro to transmute between two types without requiring knowing size statically.
61 macro_rules! transmute {
62 ($val:expr) => {
63 transmute_copy(&ManuallyDrop::new($val))
64 };
65 }
66
67 #[cfg(feature = "extern_crate_std")]
68 extern crate std;
69
70 #[cfg(feature = "extern_crate_alloc")]
71 extern crate alloc;
72 #[cfg(feature = "extern_crate_alloc")]
73 pub mod allocation;
74 #[cfg(feature = "extern_crate_alloc")]
75 pub use allocation::*;
76
77 mod zeroable;
78 pub use zeroable::*;
79
80 mod pod;
81 pub use pod::*;
82
83 mod contiguous;
84 pub use contiguous::*;
85
86 mod offset_of;
87 pub use offset_of::*;
88
89 mod transparent;
90 pub use transparent::*;
91
92 #[cfg(feature = "derive")]
93 pub use bytemuck_derive::{Contiguous, Pod, TransparentWrapper, Zeroable};
94
95 /*
96
97 Note(Lokathor): We've switched all of the `unwrap` to `match` because there is
98 apparently a bug: https://github.com/rust-lang/rust/issues/68667
99 and it doesn't seem to show up in simple godbolt examples but has been reported
100 as having an impact when there's a cast mixed in with other more complicated
101 code around it. Rustc/LLVM ends up missing that the `Err` can't ever happen for
102 particular type combinations, and then it doesn't fully eliminated the panic
103 possibility code branch.
104
105 */
106
107 /// Immediately panics.
108 #[cold]
109 #[inline(never)]
something_went_wrong(_src: &str, _err: PodCastError) -> !110 fn something_went_wrong(_src: &str, _err: PodCastError) -> ! {
111 // Note(Lokathor): Keeping the panic here makes the panic _formatting_ go
112 // here too, which helps assembly readability and also helps keep down
113 // the inline pressure.
114 #[cfg(not(target_arch = "spirv"))]
115 panic!("{src}>{err:?}", src = _src, err = _err);
116 // Note: On the spirv targets from [rust-gpu](https://github.com/EmbarkStudios/rust-gpu)
117 // panic formatting cannot be used. We we just give a generic error message
118 // The chance that the panicing version of these functions will ever get called
119 // on spir-v targets with invalid inputs is small, but giving a simple error
120 // message is better than no error message at all.
121 #[cfg(target_arch = "spirv")]
122 panic!("Called a panicing helper from bytemuck which paniced");
123 }
124
125 /// Re-interprets `&T` as `&[u8]`.
126 ///
127 /// Any ZST becomes an empty slice, and in that case the pointer value of that
128 /// empty slice might not match the pointer value of the input reference.
129 #[inline]
bytes_of<T: Pod>(t: &T) -> &[u8]130 pub fn bytes_of<T: Pod>(t: &T) -> &[u8] {
131 if size_of::<T>() == 0 {
132 &[]
133 } else {
134 match try_cast_slice::<T, u8>(core::slice::from_ref(t)) {
135 Ok(s) => s,
136 Err(_) => unreachable!(),
137 }
138 }
139 }
140
141 /// Re-interprets `&mut T` as `&mut [u8]`.
142 ///
143 /// Any ZST becomes an empty slice, and in that case the pointer value of that
144 /// empty slice might not match the pointer value of the input reference.
145 #[inline]
bytes_of_mut<T: Pod>(t: &mut T) -> &mut [u8]146 pub fn bytes_of_mut<T: Pod>(t: &mut T) -> &mut [u8] {
147 if size_of::<T>() == 0 {
148 &mut []
149 } else {
150 match try_cast_slice_mut::<T, u8>(core::slice::from_mut(t)) {
151 Ok(s) => s,
152 Err(_) => unreachable!(),
153 }
154 }
155 }
156
157 /// Re-interprets `&[u8]` as `&T`.
158 ///
159 /// ## Panics
160 ///
161 /// This is [`try_from_bytes`] but will panic on error.
162 #[inline]
from_bytes<T: Pod>(s: &[u8]) -> &T163 pub fn from_bytes<T: Pod>(s: &[u8]) -> &T {
164 match try_from_bytes(s) {
165 Ok(t) => t,
166 Err(e) => something_went_wrong("from_bytes", e),
167 }
168 }
169
170 /// Re-interprets `&mut [u8]` as `&mut T`.
171 ///
172 /// ## Panics
173 ///
174 /// This is [`try_from_bytes_mut`] but will panic on error.
175 #[inline]
from_bytes_mut<T: Pod>(s: &mut [u8]) -> &mut T176 pub fn from_bytes_mut<T: Pod>(s: &mut [u8]) -> &mut T {
177 match try_from_bytes_mut(s) {
178 Ok(t) => t,
179 Err(e) => something_went_wrong("from_bytes_mut", e),
180 }
181 }
182
183 /// Re-interprets `&[u8]` as `&T`.
184 ///
185 /// ## Failure
186 ///
187 /// * If the slice isn't aligned for the new type
188 /// * If the slice's length isn’t exactly the size of the new type
189 #[inline]
try_from_bytes<T: Pod>(s: &[u8]) -> Result<&T, PodCastError>190 pub fn try_from_bytes<T: Pod>(s: &[u8]) -> Result<&T, PodCastError> {
191 if s.len() != size_of::<T>() {
192 Err(PodCastError::SizeMismatch)
193 } else if (s.as_ptr() as usize) % align_of::<T>() != 0 {
194 Err(PodCastError::TargetAlignmentGreaterAndInputNotAligned)
195 } else {
196 Ok(unsafe { &*(s.as_ptr() as *const T) })
197 }
198 }
199
200 /// Re-interprets `&mut [u8]` as `&mut T`.
201 ///
202 /// ## Failure
203 ///
204 /// * If the slice isn't aligned for the new type
205 /// * If the slice's length isn’t exactly the size of the new type
206 #[inline]
try_from_bytes_mut<T: Pod>( s: &mut [u8], ) -> Result<&mut T, PodCastError>207 pub fn try_from_bytes_mut<T: Pod>(
208 s: &mut [u8],
209 ) -> Result<&mut T, PodCastError> {
210 if s.len() != size_of::<T>() {
211 Err(PodCastError::SizeMismatch)
212 } else if (s.as_ptr() as usize) % align_of::<T>() != 0 {
213 Err(PodCastError::TargetAlignmentGreaterAndInputNotAligned)
214 } else {
215 Ok(unsafe { &mut *(s.as_mut_ptr() as *mut T) })
216 }
217 }
218
219 /// The things that can go wrong when casting between [`Pod`] data forms.
220 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
221 pub enum PodCastError {
222 /// You tried to cast a slice to an element type with a higher alignment
223 /// requirement but the slice wasn't aligned.
224 TargetAlignmentGreaterAndInputNotAligned,
225 /// If the element size changes then the output slice changes length
226 /// accordingly. If the output slice wouldn't be a whole number of elements
227 /// then the conversion fails.
228 OutputSliceWouldHaveSlop,
229 /// When casting a slice you can't convert between ZST elements and non-ZST
230 /// elements. When casting an individual `T`, `&T`, or `&mut T` value the
231 /// source size and destination size must be an exact match.
232 SizeMismatch,
233 /// For this type of cast the alignments must be exactly the same and they
234 /// were not so now you're sad.
235 ///
236 /// This error is generated **only** by operations that cast allocated types
237 /// (such as `Box` and `Vec`), because in that case the alignment must stay
238 /// exact.
239 AlignmentMismatch,
240 }
241 #[cfg(not(target_arch = "spirv"))]
242 impl core::fmt::Display for PodCastError {
fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result243 fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
244 write!(f, "{:?}", self)
245 }
246 }
247 #[cfg(feature = "extern_crate_std")]
248 impl std::error::Error for PodCastError {}
249
250 /// Cast `T` into `U`
251 ///
252 /// ## Panics
253 ///
254 /// * This is like [`try_cast`](try_cast), but will panic on a size mismatch.
255 #[inline]
cast<A: Pod, B: Pod>(a: A) -> B256 pub fn cast<A: Pod, B: Pod>(a: A) -> B {
257 if size_of::<A>() == size_of::<B>() {
258 unsafe { transmute!(a) }
259 } else {
260 something_went_wrong("cast", PodCastError::SizeMismatch)
261 }
262 }
263
264 /// Cast `&mut T` into `&mut U`.
265 ///
266 /// ## Panics
267 ///
268 /// This is [`try_cast_mut`] but will panic on error.
269 #[inline]
cast_mut<A: Pod, B: Pod>(a: &mut A) -> &mut B270 pub fn cast_mut<A: Pod, B: Pod>(a: &mut A) -> &mut B {
271 if size_of::<A>() == size_of::<B>() && align_of::<A>() >= align_of::<B>() {
272 // Plz mr compiler, just notice that we can't ever hit Err in this case.
273 match try_cast_mut(a) {
274 Ok(b) => b,
275 Err(_) => unreachable!(),
276 }
277 } else {
278 match try_cast_mut(a) {
279 Ok(b) => b,
280 Err(e) => something_went_wrong("cast_mut", e),
281 }
282 }
283 }
284
285 /// Cast `&T` into `&U`.
286 ///
287 /// ## Panics
288 ///
289 /// This is [`try_cast_ref`] but will panic on error.
290 #[inline]
cast_ref<A: Pod, B: Pod>(a: &A) -> &B291 pub fn cast_ref<A: Pod, B: Pod>(a: &A) -> &B {
292 if size_of::<A>() == size_of::<B>() && align_of::<A>() >= align_of::<B>() {
293 // Plz mr compiler, just notice that we can't ever hit Err in this case.
294 match try_cast_ref(a) {
295 Ok(b) => b,
296 Err(_) => unreachable!(),
297 }
298 } else {
299 match try_cast_ref(a) {
300 Ok(b) => b,
301 Err(e) => something_went_wrong("cast_ref", e),
302 }
303 }
304 }
305
306 /// Cast `&[A]` into `&[B]`.
307 ///
308 /// ## Panics
309 ///
310 /// This is [`try_cast_slice`] but will panic on error.
311 #[inline]
cast_slice<A: Pod, B: Pod>(a: &[A]) -> &[B]312 pub fn cast_slice<A: Pod, B: Pod>(a: &[A]) -> &[B] {
313 match try_cast_slice(a) {
314 Ok(b) => b,
315 Err(e) => something_went_wrong("cast_slice", e),
316 }
317 }
318
319 /// Cast `&mut [T]` into `&mut [U]`.
320 ///
321 /// ## Panics
322 ///
323 /// This is [`try_cast_slice_mut`] but will panic on error.
324 #[inline]
cast_slice_mut<A: Pod, B: Pod>(a: &mut [A]) -> &mut [B]325 pub fn cast_slice_mut<A: Pod, B: Pod>(a: &mut [A]) -> &mut [B] {
326 match try_cast_slice_mut(a) {
327 Ok(b) => b,
328 Err(e) => something_went_wrong("cast_slice_mut", e),
329 }
330 }
331
332 /// As `align_to`, but safe because of the [`Pod`] bound.
333 #[inline]
pod_align_to<T: Pod, U: Pod>(vals: &[T]) -> (&[T], &[U], &[T])334 pub fn pod_align_to<T: Pod, U: Pod>(vals: &[T]) -> (&[T], &[U], &[T]) {
335 unsafe { vals.align_to::<U>() }
336 }
337
338 /// As `align_to_mut`, but safe because of the [`Pod`] bound.
339 #[inline]
pod_align_to_mut<T: Pod, U: Pod>( vals: &mut [T], ) -> (&mut [T], &mut [U], &mut [T])340 pub fn pod_align_to_mut<T: Pod, U: Pod>(
341 vals: &mut [T],
342 ) -> (&mut [T], &mut [U], &mut [T]) {
343 unsafe { vals.align_to_mut::<U>() }
344 }
345
346 /// Try to cast `T` into `U`.
347 ///
348 /// Note that for this particular type of cast, alignment isn't a factor. The
349 /// input value is semantically copied into the function and then returned to a
350 /// new memory location which will have whatever the required alignment of the
351 /// output type is.
352 ///
353 /// ## Failure
354 ///
355 /// * If the types don't have the same size this fails.
356 #[inline]
try_cast<A: Pod, B: Pod>(a: A) -> Result<B, PodCastError>357 pub fn try_cast<A: Pod, B: Pod>(a: A) -> Result<B, PodCastError> {
358 if size_of::<A>() == size_of::<B>() {
359 Ok(unsafe { transmute!(a) })
360 } else {
361 Err(PodCastError::SizeMismatch)
362 }
363 }
364
365 /// Try to convert a `&T` into `&U`.
366 ///
367 /// ## Failure
368 ///
369 /// * If the reference isn't aligned in the new type
370 /// * If the source type and target type aren't the same size.
371 #[inline]
try_cast_ref<A: Pod, B: Pod>(a: &A) -> Result<&B, PodCastError>372 pub fn try_cast_ref<A: Pod, B: Pod>(a: &A) -> Result<&B, PodCastError> {
373 // Note(Lokathor): everything with `align_of` and `size_of` will optimize away
374 // after monomorphization.
375 if align_of::<B>() > align_of::<A>()
376 && (a as *const A as usize) % align_of::<B>() != 0
377 {
378 Err(PodCastError::TargetAlignmentGreaterAndInputNotAligned)
379 } else if size_of::<B>() == size_of::<A>() {
380 Ok(unsafe { &*(a as *const A as *const B) })
381 } else {
382 Err(PodCastError::SizeMismatch)
383 }
384 }
385
386 /// Try to convert a `&mut T` into `&mut U`.
387 ///
388 /// As [`try_cast_ref`], but `mut`.
389 #[inline]
try_cast_mut<A: Pod, B: Pod>(a: &mut A) -> Result<&mut B, PodCastError>390 pub fn try_cast_mut<A: Pod, B: Pod>(a: &mut A) -> Result<&mut B, PodCastError> {
391 // Note(Lokathor): everything with `align_of` and `size_of` will optimize away
392 // after monomorphization.
393 if align_of::<B>() > align_of::<A>()
394 && (a as *mut A as usize) % align_of::<B>() != 0
395 {
396 Err(PodCastError::TargetAlignmentGreaterAndInputNotAligned)
397 } else if size_of::<B>() == size_of::<A>() {
398 Ok(unsafe { &mut *(a as *mut A as *mut B) })
399 } else {
400 Err(PodCastError::SizeMismatch)
401 }
402 }
403
404 /// Try to convert `&[A]` into `&[B]` (possibly with a change in length).
405 ///
406 /// * `input.as_ptr() as usize == output.as_ptr() as usize`
407 /// * `input.len() * size_of::<A>() == output.len() * size_of::<B>()`
408 ///
409 /// ## Failure
410 ///
411 /// * If the target type has a greater alignment requirement and the input slice
412 /// isn't aligned.
413 /// * If the target element type is a different size from the current element
414 /// type, and the output slice wouldn't be a whole number of elements when
415 /// accounting for the size change (eg: 3 `u16` values is 1.5 `u32` values, so
416 /// that's a failure).
417 /// * Similarly, you can't convert between a [ZST](https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts)
418 /// and a non-ZST.
419 #[inline]
try_cast_slice<A: Pod, B: Pod>(a: &[A]) -> Result<&[B], PodCastError>420 pub fn try_cast_slice<A: Pod, B: Pod>(a: &[A]) -> Result<&[B], PodCastError> {
421 // Note(Lokathor): everything with `align_of` and `size_of` will optimize away
422 // after monomorphization.
423 if align_of::<B>() > align_of::<A>()
424 && (a.as_ptr() as usize) % align_of::<B>() != 0
425 {
426 Err(PodCastError::TargetAlignmentGreaterAndInputNotAligned)
427 } else if size_of::<B>() == size_of::<A>() {
428 Ok(unsafe { core::slice::from_raw_parts(a.as_ptr() as *const B, a.len()) })
429 } else if size_of::<A>() == 0 || size_of::<B>() == 0 {
430 Err(PodCastError::SizeMismatch)
431 } else if core::mem::size_of_val(a) % size_of::<B>() == 0 {
432 let new_len = core::mem::size_of_val(a) / size_of::<B>();
433 Ok(unsafe { core::slice::from_raw_parts(a.as_ptr() as *const B, new_len) })
434 } else {
435 Err(PodCastError::OutputSliceWouldHaveSlop)
436 }
437 }
438
439 /// Try to convert `&mut [A]` into `&mut [B]` (possibly with a change in
440 /// length).
441 ///
442 /// As [`try_cast_slice`], but `&mut`.
443 #[inline]
try_cast_slice_mut<A: Pod, B: Pod>( a: &mut [A], ) -> Result<&mut [B], PodCastError>444 pub fn try_cast_slice_mut<A: Pod, B: Pod>(
445 a: &mut [A],
446 ) -> Result<&mut [B], PodCastError> {
447 // Note(Lokathor): everything with `align_of` and `size_of` will optimize away
448 // after monomorphization.
449 if align_of::<B>() > align_of::<A>()
450 && (a.as_mut_ptr() as usize) % align_of::<B>() != 0
451 {
452 Err(PodCastError::TargetAlignmentGreaterAndInputNotAligned)
453 } else if size_of::<B>() == size_of::<A>() {
454 Ok(unsafe {
455 core::slice::from_raw_parts_mut(a.as_mut_ptr() as *mut B, a.len())
456 })
457 } else if size_of::<A>() == 0 || size_of::<B>() == 0 {
458 Err(PodCastError::SizeMismatch)
459 } else if core::mem::size_of_val(a) % size_of::<B>() == 0 {
460 let new_len = core::mem::size_of_val(a) / size_of::<B>();
461 Ok(unsafe {
462 core::slice::from_raw_parts_mut(a.as_mut_ptr() as *mut B, new_len)
463 })
464 } else {
465 Err(PodCastError::OutputSliceWouldHaveSlop)
466 }
467 }
468