oct 0.34.0

Octonary transcodings.
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

// Copyright 2024-2026 Gabriel Bjørnager Jensen.
//
// SPDX: MIT OR Apache-2.0

//! The [`IntoOctets`] trait.

mod test;

use crate::{FromOctets, Immutable, Init};

use core::mem::MaybeUninit;
use core::slice;

/// Denotes a type representable as octets (bytes).
///
/// This trait is implemented for any, possible type
/// -- which is safe, given Rust's octonary memory
/// model. The real crème de la crème, however,
/// comes when the implementing type additionally
/// implements [`Init`], as this allows for
/// conversions into readable octets (see
/// [`as_octets`] and [`as_octets_mut`]).
///
/// [`as_octets`]: Self::as_octets
/// [`as_octets_mut`]: Self::as_octets_mut
///
/// # Safety
///
/// This trait is safe to implemement as-is for any
/// type (as all types are, by definition,
/// represented by octets). Provided defaults,
/// however, may not be overriden.
#[doc(alias = "IntoBytes")]
pub unsafe trait IntoOctets {
	/// Reinterprets the object as a slice of octets.
	#[doc(alias = "as_bytes")]
	#[inline(always)]
	#[must_use]
	fn as_octets(&self) -> &[u8]
	where
		Self: Init + Immutable,
	{
		let len  = size_of_val(self);
		let data = (&raw const *self).cast::<u8>();

		// SAFETY: `Init` guarantees initialised data.
		// `size_of_val` guarantees the exact size of the
		// referenced object. Additionally, `Immutable`
		// guarantees interiour-immutability.
		unsafe { slice::from_raw_parts(data, len) }
	}

	/// Reinterprets the object as a mutable slice of
	/// octets.
	///
	/// This method requires [`FromOctets`] as we cannot
	/// alone guarantee whether any write to the
	/// returned slice is valid.
	#[doc(alias = "as_bytes_mut")]
	#[doc(alias = "as_mut_bytes")]
	#[doc(alias = "as_mut_octets")]
	#[inline(always)]
	#[must_use]
	fn as_octets_mut(&mut self) -> &mut [u8]
	where
		Self: Init + FromOctets,
	{
		let len  = size_of_val(self);
		let data = (&raw mut *self).cast::<u8>();

		// SAFETY: `Init` guarantees initialised data.
		// `size_of_val` guarantees the exact size of the
		// referenced object. Lastly, `FromOctets` guarantees
		// that any write to the returned slice is valid.
		unsafe { slice::from_raw_parts_mut(data, len) }
	}

	/// Reinterprets the object as a slice of
	/// uninitialised octets.
	///
	/// This operation is valid for any virtually any
	/// type. Do note, however, that the returned octets
	/// can rarely be used for anything other than pure
	/// copy operations.
	#[inline(always)]
	#[must_use]
	fn as_uninit_octets(&self) -> &[MaybeUninit<u8>]
	where
		Self: Immutable,
	{
		let len  = size_of_val(self);
		let data = (&raw const *self).cast::<MaybeUninit<u8>>();

		// SAFETY: `size_of_val` guarantees the exact size
		// of the referenced object. Additionally,
		// `Immutable` guarantees that no write can be made
		// to the returned slice.
		unsafe { slice::from_raw_parts(data, len) }
	}
}

unsafe impl<T: ?Sized> IntoOctets for T {}