Debian Codegraph @

.cargo/vendor/bytemuck/src/lib.rs

raw
1 #![no_std]
2 #![warn(missing_docs)]
3 #![allow(unused_mut)]
4 #![allow(clippy::match_like_matches_macro)]
5 #![allow(clippy::uninlined_format_args)]
6 #![allow(clippy::result_unit_err)]
7 #![allow(clippy::type_complexity)]
8 #![cfg_attr(feature = "nightly_docs", feature(doc_cfg))]
9 #![cfg_attr(feature = "nightly_portable_simd", feature(portable_simd))]
10 #![cfg_attr(feature = "nightly_float", feature(f16, f128))]
11 #![cfg_attr(
12 all(
13 feature = "nightly_stdsimd",
14 any(target_arch = "x86_64", target_arch = "x86")
15 ),
16 feature(stdarch_x86_avx512)
17 )]
18
19 //! This crate gives small utilities for casting between plain data types.
20 //!
21 //! ## Basics
22 //!
23 //! Data comes in five basic forms in Rust, so we have five basic casting
24 //! functions:
25 //!
26 //! * `T` uses [`cast`]
27 //! * `&T` uses [`cast_ref`]
28 //! * `&mut T` uses [`cast_mut`]
29 //! * `&[T]` uses [`cast_slice`]
30 //! * `&mut [T]` uses [`cast_slice_mut`]
31 //!
32 //! Depending on the function, the [`NoUninit`] and/or [`AnyBitPattern`] traits
33 //! are used to maintain memory safety.
34 //!
35 //! **Historical Note:** When the crate first started the [`Pod`] trait was used
36 //! instead, and so you may hear people refer to that, but it has the strongest
37 //! requirements and people eventually wanted the more fine-grained system, so
38 //! here we are. All types that impl `Pod` have a blanket impl to also support
39 //! `NoUninit` and `AnyBitPattern`. The traits unfortunately do not have a
40 //! perfectly clean hierarchy for semver reasons.
41 //!
42 //! ## Failures
43 //!
44 //! Some casts will never fail, and other casts might fail.
45 //!
46 //! * `cast::<u32, f32>` always works (and [`f32::from_bits`]).
47 //! * `cast_ref::<[u8; 4], u32>` might fail if the specific array reference
48 //! given at runtime doesn't have alignment 4.
49 //!
50 //! In addition to the "normal" forms of each function, which will panic on
51 //! invalid input, there's also `try_` versions which will return a `Result`.
52 //!
53 //! If you would like to statically ensure that a cast will work at runtime you
54 //! can use the `must_cast` crate feature and the `must_` casting functions. A
55 //! "must cast" that can't be statically known to be valid will cause a
56 //! compilation error (and sometimes a very hard to read compilation error).
57 //!
58 //! ## Using Your Own Types
59 //!
60 //! All the functions listed above are guarded by the [`Pod`] trait, which is a
61 //! sub-trait of the [`Zeroable`] trait.
62 //!
63 //! If you enable the crate's `derive` feature then these traits can be derived
64 //! on your own types. The derive macros will perform the necessary checks on
65 //! your type declaration, and trigger an error if your type does not qualify.
66 //!
67 //! The derive macros might not cover all edge cases, and sometimes they will
68 //! error when actually everything is fine. As a last resort you can impl these
69 //! traits manually. However, these traits are `unsafe`, and you should
70 //! carefully read the requirements before using a manual implementation.
71 //!
72 //! ## Cargo Features
73 //!
74 //! The crate supports Rust 1.34 when no features are enabled, and so there's
75 //! cargo features for thing that you might consider "obvious".
76 //!
77 //! The cargo features **do not** promise any particular MSRV, and they may
78 //! increase their MSRV in new versions.
79 //!
80 //! * `derive`: Provide derive macros for the various traits.
81 //! * `extern_crate_alloc`: Provide utilities for `alloc` related types such as
82 //! Box and Vec.
83 //! * `zeroable_maybe_uninit` and `zeroable_atomics`: Provide more [`Zeroable`]
84 //! impls.
85 //! * `wasm_simd` and `aarch64_simd`: Support more SIMD types.
86 //! * `min_const_generics`: Provides appropriate impls for arrays of all lengths
87 //! instead of just for a select list of array lengths.
88 //! * `must_cast`: Provides the `must_` functions, which will compile error if
89 //! the requested cast can't be statically verified.
90 //! * `const_zeroed`: Provides a const version of the `zeroed` function.
91
92 #[cfg(all(target_arch = "aarch64", feature = "aarch64_simd"))]
93 use core::arch::aarch64;
94 #[cfg(all(target_arch = "wasm32", feature = "wasm_simd"))]
95 use core::arch::wasm32;
96 #[cfg(target_arch = "x86")]
97 use core::arch::x86;
98 #[cfg(target_arch = "x86_64")]
99 use core::arch::x86_64;
100 //
101 use core::{
102 marker::*,
103 mem::{align_of, size_of},
104 num::*,
105 ptr::*,
106 };
107
108 // Used from macros to ensure we aren't using some locally defined name and
109 // actually are referencing libcore. This also would allow pre-2018 edition
110 // crates to use our macros, but I'm not sure how important that is.
111 #[doc(hidden)]
112 pub use ::core as __core;
113
114 #[cfg(not(feature = "min_const_generics"))]
115 macro_rules! impl_unsafe_marker_for_array {
116 ( $marker:ident , $( $n:expr ),* ) => {
117 $(unsafe impl<T> $marker for [T; $n] where T: $marker {})*
118 }
119 }
120
121 /// A macro to transmute between two types without requiring knowing size
122 /// statically.
123 macro_rules! transmute {
124 ($val:expr) => {
125 ::core::mem::transmute_copy(&::core::mem::ManuallyDrop::new($val))
126 };
127 // This arm is for use in const contexts, where the borrow required to use
128 // transmute_copy poses an issue since the compiler hedges that the type
129 // being borrowed could have interior mutability.
130 ($srcty:ty; $dstty:ty; $val:expr) => {{
131 #[repr(C)]
132 union Transmute<A, B> {
133 src: ::core::mem::ManuallyDrop<A>,
134 dst: ::core::mem::ManuallyDrop<B>,
135 }
136 ::core::mem::ManuallyDrop::into_inner(
137 Transmute::<$srcty, $dstty> { src: ::core::mem::ManuallyDrop::new($val) }
138 .dst,
139 )
140 }};
141 }
142
143 /// A macro to implement marker traits for various simd types.
144 /// #[allow(unused)] because the impls are only compiled on relevant platforms
145 /// with relevant cargo features enabled.
146 #[allow(unused)]
147 macro_rules! impl_unsafe_marker_for_simd {
148 ($(#[cfg($cfg_predicate:meta)])? unsafe impl $trait:ident for $platform:ident :: {}) => {};
149 ($(#[cfg($cfg_predicate:meta)])? unsafe impl $trait:ident for $platform:ident :: { $first_type:ident $(, $types:ident)* $(,)? }) => {
150 $( #[cfg($cfg_predicate)] )?
151 $( #[cfg_attr(feature = "nightly_docs", doc(cfg($cfg_predicate)))] )?
152 unsafe impl $trait for $platform::$first_type {}
153 $( #[cfg($cfg_predicate)] )? // To prevent recursion errors if nothing is going to be expanded anyway.
154 impl_unsafe_marker_for_simd!($( #[cfg($cfg_predicate)] )? unsafe impl $trait for $platform::{ $( $types ),* });
155 };
156 }
157
158 /// A macro for conditionally const-ifying a function.
159 /// #[allow(unused)] because currently it is only used with the `must_cast` feature.
160 #[allow(unused)]
161 macro_rules! maybe_const_fn {
162 (
163 #[cfg($cfg_predicate:meta)]
164 $(#[$attr:meta])*
165 $vis:vis $(unsafe $($unsafe:lifetime)?)? fn $name:ident $($rest:tt)*
166 ) => {
167 #[cfg($cfg_predicate)]
168 $(#[$attr])*
169 $vis const $(unsafe $($unsafe)?)? fn $name $($rest)*
170
171 #[cfg(not($cfg_predicate))]
172 $(#[$attr])*
173 $vis $(unsafe $($unsafe)?)? fn $name $($rest)*
174 };
175 }
176
177 #[cfg(feature = "extern_crate_std")]
178 extern crate std;
179
180 #[cfg(feature = "extern_crate_alloc")]
181 extern crate alloc;
182 #[cfg(feature = "extern_crate_alloc")]
183 #[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "extern_crate_alloc")))]
184 pub mod allocation;
185 #[cfg(feature = "extern_crate_alloc")]
186 pub use allocation::*;
187
188 mod anybitpattern;
189 pub use anybitpattern::*;
190
191 pub mod checked;
192 pub use checked::CheckedBitPattern;
193
194 mod internal;
195
196 mod zeroable;
197 pub use zeroable::*;
198 mod zeroable_in_option;
199 pub use zeroable_in_option::*;
200
201 mod pod;
202 pub use pod::*;
203 mod pod_in_option;
204 pub use pod_in_option::*;
205
206 #[cfg(feature = "must_cast")]
207 mod must;
208 #[cfg(feature = "must_cast")]
209 #[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "must_cast")))]
210 pub use must::*;
211
212 mod no_uninit;
213 pub use no_uninit::*;
214
215 mod contiguous;
216 pub use contiguous::*;
217
218 mod offset_of;
219 // ^ no import, the module only has a macro_rules, which are cursed and don't
220 // follow normal import/export rules.
221
222 mod transparent;
223 pub use transparent::*;
224
225 #[cfg(feature = "derive")]
226 #[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "derive")))]
227 pub use bytemuck_derive::{
228 AnyBitPattern, ByteEq, ByteHash, CheckedBitPattern, Contiguous, NoUninit,
229 Pod, TransparentWrapper, Zeroable,
230 };
231
232 /// The things that can go wrong when casting between [`Pod`] data forms.
233 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
234 pub enum PodCastError {
235 /// You tried to cast a reference into a reference to a type with a higher
236 /// alignment requirement but the input reference wasn't aligned.
237 TargetAlignmentGreaterAndInputNotAligned,
238 /// If the element size of a slice changes, then the output slice changes
239 /// length accordingly. If the output slice wouldn't be a whole number of
240 /// elements, then the conversion fails.
241 OutputSliceWouldHaveSlop,
242 /// When casting an individual `T`, `&T`, or `&mut T` value the
243 /// source size and destination size must be an exact match.
244 SizeMismatch,
245 /// For this type of cast the alignments must be exactly the same and they
246 /// were not so now you're sad.
247 ///
248 /// This error is generated **only** by operations that cast allocated types
249 /// (such as `Box` and `Vec`), because in that case the alignment must stay
250 /// exact.
251 AlignmentMismatch,
252 }
253 #[cfg(not(target_arch = "spirv"))]
254 impl core::fmt::Display for PodCastError {
255 fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
256 write!(f, "{:?}", self)
257 }
258 }
259 #[cfg(feature = "extern_crate_std")]
260 #[cfg_attr(feature = "nightly_docs", doc(cfg(feature = "extern_crate_std")))]
261 impl std::error::Error for PodCastError {}
262
263 /// Re-interprets `&T` as `&[u8]`.
264 ///
265 /// Any ZST becomes an empty slice, and in that case the pointer value of that
266 /// empty slice might not match the pointer value of the input reference.
267 #[inline]
268 pub fn bytes_of<T: NoUninit>(t: &T) -> &[u8] {
269 unsafe { internal::bytes_of(t) }
270 }
271
272 /// Re-interprets `&mut T` as `&mut [u8]`.
273 ///
274 /// Any ZST becomes an empty slice, and in that case the pointer value of that
275 /// empty slice might not match the pointer value of the input reference.
276 #[inline]
277 pub fn bytes_of_mut<T: NoUninit + AnyBitPattern>(t: &mut T) -> &mut [u8] {
278 unsafe { internal::bytes_of_mut(t) }
279 }
280
281 /// Re-interprets `&[u8]` as `&T`.
282 ///
283 /// ## Panics
284 ///
285 /// This is like [`try_from_bytes`] but will panic on error.
286 #[inline]
287 #[cfg_attr(feature = "track_caller", track_caller)]
288 pub fn from_bytes<T: AnyBitPattern>(s: &[u8]) -> &T {
289 unsafe { internal::from_bytes(s) }
290 }
291
292 /// Re-interprets `&mut [u8]` as `&mut T`.
293 ///
294 /// ## Panics
295 ///
296 /// This is like [`try_from_bytes_mut`] but will panic on error.
297 #[inline]
298 #[cfg_attr(feature = "track_caller", track_caller)]
299 pub fn from_bytes_mut<T: NoUninit + AnyBitPattern>(s: &mut [u8]) -> &mut T {
300 unsafe { internal::from_bytes_mut(s) }
301 }
302
303 /// Reads from the bytes as if they were a `T`.
304 ///
305 /// Unlike [`from_bytes`], the slice doesn't need to respect alignment of `T`,
306 /// only sizes must match.
307 ///
308 /// ## Failure
309 /// * If the `bytes` length is not equal to `size_of::<T>()`.
310 #[inline]
311 pub fn try_pod_read_unaligned<T: AnyBitPattern>(
312 bytes: &[u8],
313 ) -> Result<T, PodCastError> {
314 unsafe { internal::try_pod_read_unaligned(bytes) }
315 }
316
317 /// Reads the slice into a `T` value.
318 ///
319 /// Unlike [`from_bytes`], the slice doesn't need to respect alignment of `T`,
320 /// only sizes must match.
321 ///
322 /// ## Panics
323 /// * This is like `try_pod_read_unaligned` but will panic on failure.
324 #[inline]
325 #[cfg_attr(feature = "track_caller", track_caller)]
326 pub fn pod_read_unaligned<T: AnyBitPattern>(bytes: &[u8]) -> T {
327 unsafe { internal::pod_read_unaligned(bytes) }
328 }
329
330 /// Re-interprets `&[u8]` as `&T`.
331 ///
332 /// ## Failure
333 ///
334 /// * If the slice isn't aligned for the new type
335 /// * If the slice's length isn’t exactly the size of the new type
336 #[inline]
337 pub fn try_from_bytes<T: AnyBitPattern>(s: &[u8]) -> Result<&T, PodCastError> {
338 unsafe { internal::try_from_bytes(s) }
339 }
340
341 /// Re-interprets `&mut [u8]` as `&mut T`.
342 ///
343 /// ## Failure
344 ///
345 /// * If the slice isn't aligned for the new type
346 /// * If the slice's length isn’t exactly the size of the new type
347 #[inline]
348 pub fn try_from_bytes_mut<T: NoUninit + AnyBitPattern>(
349 s: &mut [u8],
350 ) -> Result<&mut T, PodCastError> {
351 unsafe { internal::try_from_bytes_mut(s) }
352 }
353
354 /// Cast `A` into `B`
355 ///
356 /// ## Panics
357 ///
358 /// * This is like [`try_cast`], but will panic on a size mismatch.
359 #[inline]
360 #[cfg_attr(feature = "track_caller", track_caller)]
361 pub fn cast<A: NoUninit, B: AnyBitPattern>(a: A) -> B {
362 unsafe { internal::cast(a) }
363 }
364
365 /// Cast `&mut A` into `&mut B`.
366 ///
367 /// ## Panics
368 ///
369 /// This is [`try_cast_mut`] but will panic on error.
370 #[inline]
371 #[cfg_attr(feature = "track_caller", track_caller)]
372 pub fn cast_mut<A: NoUninit + AnyBitPattern, B: NoUninit + AnyBitPattern>(
373 a: &mut A,
374 ) -> &mut B {
375 unsafe { internal::cast_mut(a) }
376 }
377
378 /// Cast `&A` into `&B`.
379 ///
380 /// ## Panics
381 ///
382 /// This is [`try_cast_ref`] but will panic on error.
383 #[inline]
384 #[cfg_attr(feature = "track_caller", track_caller)]
385 pub fn cast_ref<A: NoUninit, B: AnyBitPattern>(a: &A) -> &B {
386 unsafe { internal::cast_ref(a) }
387 }
388
389 /// Cast `&[A]` into `&[B]`.
390 ///
391 /// ## Panics
392 ///
393 /// This is [`try_cast_slice`] but will panic on error.
394 #[inline]
395 #[cfg_attr(feature = "track_caller", track_caller)]
396 pub fn cast_slice<A: NoUninit, B: AnyBitPattern>(a: &[A]) -> &[B] {
397 unsafe { internal::cast_slice(a) }
398 }
399
400 /// Cast `&mut [A]` into `&mut [B]`.
401 ///
402 /// ## Panics
403 ///
404 /// This is [`try_cast_slice_mut`] but will panic on error.
405 #[inline]
406 #[cfg_attr(feature = "track_caller", track_caller)]
407 pub fn cast_slice_mut<
408 A: NoUninit + AnyBitPattern,
409 B: NoUninit + AnyBitPattern,
410 >(
411 a: &mut [A],
412 ) -> &mut [B] {
413 unsafe { internal::cast_slice_mut(a) }
414 }
415
416 /// As [`align_to`](https://doc.rust-lang.org/std/primitive.slice.html#method.align_to),
417 /// but safe because of the [`Pod`] bound.
418 #[inline]
419 pub fn pod_align_to<T: NoUninit, U: AnyBitPattern>(
420 vals: &[T],
421 ) -> (&[T], &[U], &[T]) {
422 unsafe { vals.align_to::<U>() }
423 }
424
425 /// As [`align_to_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.align_to_mut),
426 /// but safe because of the [`Pod`] bound.
427 #[inline]
428 pub fn pod_align_to_mut<
429 T: NoUninit + AnyBitPattern,
430 U: NoUninit + AnyBitPattern,
431 >(
432 vals: &mut [T],
433 ) -> (&mut [T], &mut [U], &mut [T]) {
434 unsafe { vals.align_to_mut::<U>() }
435 }
436
437 /// Try to cast `A` into `B`.
438 ///
439 /// Note that for this particular type of cast, alignment isn't a factor. The
440 /// input value is semantically copied into the function and then returned to a
441 /// new memory location which will have whatever the required alignment of the
442 /// output type is.
443 ///
444 /// ## Failure
445 ///
446 /// * If the types don't have the same size this fails.
447 #[inline]
448 pub fn try_cast<A: NoUninit, B: AnyBitPattern>(
449 a: A,
450 ) -> Result<B, PodCastError> {
451 unsafe { internal::try_cast(a) }
452 }
453
454 /// Try to convert a `&A` into `&B`.
455 ///
456 /// ## Failure
457 ///
458 /// * If the reference isn't aligned in the new type
459 /// * If the source type and target type aren't the same size.
460 #[inline]
461 pub fn try_cast_ref<A: NoUninit, B: AnyBitPattern>(
462 a: &A,
463 ) -> Result<&B, PodCastError> {
464 unsafe { internal::try_cast_ref(a) }
465 }
466
467 /// Try to convert a `&mut A` into `&mut B`.
468 ///
469 /// As [`try_cast_ref`], but `mut`.
470 #[inline]
471 pub fn try_cast_mut<
472 A: NoUninit + AnyBitPattern,
473 B: NoUninit + AnyBitPattern,
474 >(
475 a: &mut A,
476 ) -> Result<&mut B, PodCastError> {
477 unsafe { internal::try_cast_mut(a) }
478 }
479
480 /// Try to convert `&[A]` into `&[B]` (possibly with a change in length).
481 ///
482 /// * `input.as_ptr() as usize == output.as_ptr() as usize`
483 /// * `input.len() * size_of::<A>() == output.len() * size_of::<B>()`
484 ///
485 /// ## Failure
486 ///
487 /// * If the target type has a greater alignment requirement and the input slice
488 /// isn't aligned.
489 /// * If the target element type is a different size from the current element
490 /// type, and the output slice wouldn't be a whole number of elements when
491 /// accounting for the size change (eg: 3 `u16` values is 1.5 `u32` values, so
492 /// that's a failure).
493 /// * Similarly, you can't convert between a [ZST](https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts)
494 /// and a non-ZST.
495 #[inline]
496 pub fn try_cast_slice<A: NoUninit, B: AnyBitPattern>(
497 a: &[A],
498 ) -> Result<&[B], PodCastError> {
499 unsafe { internal::try_cast_slice(a) }
500 }
501
502 /// Try to convert `&mut [A]` into `&mut [B]` (possibly with a change in
503 /// length).
504 ///
505 /// As [`try_cast_slice`], but `&mut`.
506 #[inline]
507 pub fn try_cast_slice_mut<
508 A: NoUninit + AnyBitPattern,
509 B: NoUninit + AnyBitPattern,
510 >(
511 a: &mut [A],
512 ) -> Result<&mut [B], PodCastError> {
513 unsafe { internal::try_cast_slice_mut(a) }
514 }
515
516 /// Fill all bytes of `target` with zeroes (see [`Zeroable`]).
517 ///
518 /// This is similar to `*target = Zeroable::zeroed()`, but guarantees that any
519 /// padding bytes in `target` are zeroed as well.
520 ///
521 /// See also [`fill_zeroes`], if you have a slice rather than a single value.
522 #[inline]
523 pub fn write_zeroes<T: Zeroable>(target: &mut T) {
524 struct EnsureZeroWrite<T>(*mut T);
525 impl<T> Drop for EnsureZeroWrite<T> {
526 #[inline(always)]
527 fn drop(&mut self) {
528 unsafe {
529 core::ptr::write_bytes(self.0, 0u8, 1);
530 }
531 }
532 }
533 unsafe {
534 let guard = EnsureZeroWrite(target);
535 core::ptr::drop_in_place(guard.0);
536 drop(guard);
537 }
538 }
539
540 /// Fill all bytes of `slice` with zeroes (see [`Zeroable`]).
541 ///
542 /// This is similar to `slice.fill(Zeroable::zeroed())`, but guarantees that any
543 /// padding bytes in `slice` are zeroed as well.
544 ///
545 /// See also [`write_zeroes`], which zeroes all bytes of a single value rather
546 /// than a slice.
547 #[inline]
548 pub fn fill_zeroes<T: Zeroable>(slice: &mut [T]) {
549 if core::mem::needs_drop::<T>() {
550 // If `T` needs to be dropped then we have to do this one item at a time, in
551 // case one of the intermediate drops does a panic.
552 slice.iter_mut().for_each(write_zeroes);
553 } else {
554 // Otherwise we can be really fast and just fill everthing with zeros.
555 let len = slice.len();
556 unsafe { core::ptr::write_bytes(slice.as_mut_ptr(), 0u8, len) }
557 }
558 }
559
560 /// Same as [`Zeroable::zeroed`], but as a `const fn` const.
561 #[cfg(feature = "const_zeroed")]
562 #[inline]
563 #[must_use]
564 pub const fn zeroed<T: Zeroable>() -> T {
565 unsafe { core::mem::zeroed() }
566 }