oct 0.26.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

// Copyright 2024-2025 Gabriel Bjørnager Jensen.
//
// This Source Code Form is subject to the terms of
// the Mozilla Public License, v. 2.0. If a copy of
// the MPL was not distributed with this file, you
// can obtain one at:
// <https://mozilla.org/MPL/2.0/>.

//! The [`transmute`] and [`transmute_unchecked`]
//! functions.

mod test;

use crate::{FromOcts, Init, IntoOcts};

use core::mem::ManuallyDrop;

/// Transmutes an object to another type.
///
/// The raw octet representation of the object is
/// reused. Note, however, that this isn't necessar-
/// ily equivalent to the new value being equal to
/// the old one (as per [`PartialEq::eq`]).
///
/// # Panics
///
/// This function will panic at translation time if
/// `T` and `U` aren't of the same size.
#[inline]
#[must_use]
#[track_caller]
pub const fn transmute<T, U>(value: T) -> U
where
	T: IntoOcts + Init,
	U: FromOcts,
{
	const {
		assert!(
			size_of::<T>() == size_of::<U>(),
			"cannot transmute types of different sizes",
		);
	}

	// SAFETY: We have asserted that both types are of
	// equal size. Bounds guarantee lack of type in-
	// variants.
	unsafe { transmute_unchecked(value) }
}

/// Unsafely transmutes an object to another type.
///
/// The raw octet representation of the object is
/// reused. Note, however, that this isn't necessar-
/// ily equivalent to the new value being equal to
/// the old one (as per [`PartialEq::eq`]).
///
/// This function should be used rarely, with
/// [`transmute`] guaranteeing safe transmutations
/// instead. This function may be used instead of
/// [`core::mem::transmute`] when transmuting
/// dependently-sized types (e.g. [arrays](array)).
///
/// # Safety
///
/// The sizes of `T` and `U` must be exactly equal.
/// Furthermore, callers guarantee that the exact
/// representation used by the provided value is
/// valid for objects of the destination type.
#[inline(always)]
#[must_use]
#[track_caller]
pub const unsafe fn transmute_unchecked<T, U>(value: T) -> U {
	debug_assert!(
		size_of::<T>() == size_of::<U>(),
		"cannot transmute types of different sizes",
	);

	union Transmute<Src, Dst> {
		src: ManuallyDrop<Src>,
		dst: ManuallyDrop<Dst>,
	}

	let transmute = Transmute { src: ManuallyDrop::new(value) };

	// SAFETY: Caller guarantees correct representa-
	// tion.
	unsafe { ManuallyDrop::into_inner(transmute.dst) }
}