oct 0.36.2

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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

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

//! The [`IntoOctets`] trait.

mod test;

use core::mem::MaybeUninit;
use core::slice;
use oct::{
	FromOctets,
	Immutable,
	Init,
	transmute_mut,
	transmute_ref,
};

/// Denotes a type representable as octets (bytes).
///
/// A type that implements this trait is a type that
/// has an underlying octonary/bytewise
/// representation.
///
/// As this represention is required by Rust's
/// memory model, this trait is actually implemented
/// for any given type. However, due to some types
/// having unitialised fields (e.g. padding bytes),
/// types must additionally implement [`Init`] for
/// conversions directly into [`u8`] objects to be
/// sound.
///
/// # Safety
///
/// Implementations may not override provided items.
#[doc(alias = "IntoBytes")]
pub unsafe trait IntoOctets {
	/// Reinterprets the object as a slice of octets.
	///
	/// The returned slice covers the entire
	/// representation of the referenced object.
	///
	/// See also [`as_octets_mut`].
	///
	/// [`as_octets_mut`]: Self::as_octets_mut
	#[doc(alias = "as_bytes")]
	#[inline]
	#[must_use]
	fn as_octets(&self) -> &[u8]
	where
		Self: Init + Immutable,
	{
		transmute_ref::<Self, [u8]>(self)
	}

	/// Reinterprets the object as a mutable slice of
	/// octets.
	///
	/// The returned slice covers the entire
	/// representation of the referenced object.
	///
	/// See also [`as_octets`].
	///
	/// [`as_octets`]: Self::as_octets
	#[doc(alias = "as_bytes_mut")]
	#[doc(alias = "as_mut_bytes")]
	#[doc(alias = "as_mut_octets")]
	#[inline]
	#[must_use]
	fn as_octets_mut(&mut self) -> &mut [u8]
	where
		Self: Init + FromOctets,
	{
		transmute_mut::<Self, [u8]>(self)
	}

	/// 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]
	#[must_use]
	fn as_uninit_octets(&self) -> &[MaybeUninit<u8>]
	where
		Self: Immutable,
	{
		// The length of the object, in count of octets.
		let len = size_of_val(self);

		// The raw data representing the object.
		let data = (&raw const *self).cast::<MaybeUninit<u8>>();

		// NOTE: Should be a no-op.
		debug_assert!(data.is_aligned());

		// SAFETY:
		// * `data` derives from a reference and can there-
		//   fore neither be null nor reference multiple
		//   allocations. As the destination type is `u8`,
		//   we can guarantee that the address is aligned
		//   as all pointers must be byte-aligned (i.e.
		//   `u8`-aligned). The slice also inherits the
		//   original reference's (guaranteed) read
		//   provenance.
		//
		// * `size_of_val` returns the exact size of the
		//   destination object. `MaybeUninit<u8>` itself
		//   has no invariants, so representation is unimpor-
		//   tant.
		//
		// * The destination object(s) cannot be modified,
		//   thanks to the `Immutable` bound.
		//
		// * The total size cannot overflow `isize` (see
		//   note #1.)
		//
		// For the record, the returned slice cannot deini-
		// tialise the destination object
		//
		// Note #1: This assumption is deduced from,
		// `core::slice::from_ref`, as that would otherwise
		// be unsound.
		unsafe { slice::from_raw_parts(data, len) }
	}
}

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