all-is-bytes 0.1.0

Because everything is just a bunch of bytes... right?
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

//! # `all_is_bytes`
//!
//! [![crates.io](https://img.shields.io/crates/v/all-is-bytes.svg)](https://crates.io/crates/all-is-bytes)
//! [![Dependency Status](https://deps.rs/crate/all-is-bytes/0.1.0/status.svg)](https://deps.rs/crate/all-is-bytes/0.1.0)
//! [![License](https://img.shields.io/badge/license-Unlicense-blue.svg)](https://unlicense.org/)
//! [![MSRV](https://img.shields.io/badge/MSRV-1.38-white.svg)](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
//!
//! Because everything is just a bunch of bytes... right?
//!
//! # See also
//!
//! This crate is not very practical to use, as it is for casting **any** type to a byte slice,
//! regardless of whether or not it contains padding or has interior mutability.
//! [bytemuck] has mechanisms to *safely* perform such casts, so consider using it instead.
//!
//! [bytemuck]: https://crates.io/crates/bytemuck

// Attributes
#![cfg_attr(not(any(doc, test)), no_std)]
// Lints
#![allow(clippy::inline_always)]
#![deny(
    clippy::missing_safety_doc,
    clippy::undocumented_unsafe_blocks,
    unsafe_op_in_unsafe_fn
)]

use core::{
    mem::{self, MaybeUninit},
    slice,
};

/// Reinterprets as a byte slice.
///
/// Returns <code>&\[[`MaybeUninit`]\<u8\>\]</code> rather than `&[u8]` as it is [undefined behavior] to read padding bytes.
/// If the type does not contain any padding, it is safe to cast it to `&[u8]` yourself.
///
/// # Safety
///
/// The type must not have interior mutability.
///
/// In other words, the type cannot contain [`Cell`], [`UnsafeCell`], and the like.
///
/// ## Why?
///
/// Aliasing. See here:
///
/// ```no_run
/// # use core::cell::Cell;
/// let cell = Cell::new(1u8);
/// let raw = unsafe { all_is_bytes::cast(&cell) };
/// cell.set(0u8); // Erm... well that just happened...
/// assert_eq!(cell.get(), unsafe { raw[0].assume_init() }); // Uh oh!
/// ```
///
/// This causes [undefined behavior].
///
/// [`Cell`]: core::cell::Cell
/// [`UnsafeCell`]: core::cell::UnsafeCell
/// [undefined behavior]: https://doc.rust-lang.org/stable/reference/behavior-considered-undefined.html
#[inline(always)]
#[must_use]
pub unsafe fn cast<T>(x: &T) -> &[MaybeUninit<u8>]
where
    T: ?Sized,
{
    let len = mem::size_of_val(x);
    let ptr = (x as *const T).cast::<MaybeUninit<u8>>();

    // SAFETY: `ptr` is valid and points to a value `len` bytes long.
    unsafe { slice::from_raw_parts(ptr, len) }
}

/// Reinterprets as a mutable byte slice.
///
/// Returns <code>&\[[`MaybeUninit`]\<u8\>\]</code> rather than `&[u8]` as it is [undefined behavior] to read padding bytes.
/// If the type does not contain any padding, it is safe to cast it to `&[u8]` yourself.
///
/// # Safety
///
/// All invariants of the type must be upheld.
///
/// ## Why?
///
/// See this example with [`NonZeroU8`]:
///
/// ```no_run
/// # use core::num::NonZeroU8;
/// let mut num = NonZeroU8::new(1).unwrap();
/// let raw = unsafe { all_is_bytes::cast_mut(&mut num) };
/// raw[0].write(0); // Don't do this!
/// ```
///
/// As `NonZero*` values must not be 0, this causes [undefined behavior].
///
/// References and [`NonNull`] values are similar in that they must not be null.
///
/// Additionally, [`str`] has the invariant that its contents must be valid UTF-8.
/// See [`str::as_bytes_mut`] for more information.
///
/// [`NonZeroU8`]: core::num::NonZeroU8
/// [`NonNull`]: core::ptr::NonNull
/// [undefined behavior]: https://doc.rust-lang.org/stable/reference/behavior-considered-undefined.html
#[inline(always)]
#[must_use]
pub unsafe fn cast_mut<T>(x: &mut T) -> &mut [MaybeUninit<u8>]
where
    T: ?Sized,
{
    let len = mem::size_of_val(x);
    let ptr = (x as *mut T).cast::<MaybeUninit<u8>>();

    // SAFETY: `ptr` is valid and points to a value `len` bytes long.
    unsafe { slice::from_raw_parts_mut(ptr, len) }
}