oct 0.29.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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

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

//! Octonary transcoder.
//!
//! This library provides facilities for transcoding
//! objects to and from octonary (bytewise)
//! representations. This includes in-place
//! transmutations (similarly to e.g. Zerocopy and
//! `bytemuck`) as well (de)serialisations
//! (similarly to e.g. Serde and Bincode).

#![doc(html_logo_url = "https://gitlab.com/bjoernager/oct/-/raw/master/DOC-ICON.svg")]

#![no_std]

#![cfg_attr(feature = "f128", feature(f128))]

#![cfg_attr(feature = "f16", feature(f16))]

#![cfg_attr(
	all(
		feature = "f16",
		any(
			target_arch = "aarch64",
			target_arch = "arm64ec",
			target_feature = "v7",
		),
	),
	feature(stdarch_neon_f16),
)]

#![cfg_attr(
	all(
		feature = "f16",
		any(
			target_arch = "x86",
			target_arch = "x86_64",
		),
	),
	feature(stdarch_x86_avx512_f16),
)]

#![cfg_attr(feature = "unstable_docs", feature(doc_cfg, rustdoc_internals))]

#![cfg_attr(feature = "unstable_docs", allow(internal_features))]

extern crate self as oct;

#[cfg(feature = "alloc")]
extern crate alloc;

#[cfg(feature = "std")]
extern crate std;

pub mod serdes;

mod from_octs;
mod immutable;
mod init;
mod into_octs;
mod transmute;
mod zeroable;

pub use from_octs::FromOcts;
pub use immutable::Immutable;
pub use init::Init;
pub use into_octs::IntoOcts;
pub use transmute::{transmute, transmute_ref, transmute_mut, transmute_unchecked};
pub use zeroable::Zeroable;

/// Implements [`FromOcts`] for the given type.
///
/// [`FromOcts`]: trait@FromOcts
///
/// # Examples
///
/// Any type can derive [`FromOcts`] -- as long as
/// all member fields also implement it.
///
/// [`FromOcts`]: trait@FromOcts
///
/// ```rust
/// use oct::{FromOcts, Zeroable};
///
/// #[derive(FromOcts, Zeroable)]
/// struct Reminder {
///     timestamp: i64,
/// }
/// ```
#[cfg(feature = "proc_macro")]
#[doc(inline)]
pub use oct_macros::FromOcts;

/// Implements [`Immutable`] for the given type.
///
/// [`Immutable`]: trait@Immutable
///
/// # Examples
///
/// Most types can simply derive [`Immutable`],
/// provided that all fields also implement
/// `Immutable`:
///
/// [`Immutable`]: trait@Immutable
///
/// ```rust
/// use oct::Immutable;
///
/// #[derive(Immutable)]
/// struct InteriourImmutableI32 {
///     value: i32,
/// }
/// ```
///
/// Types that contain [`UnsafeCell`] (or other cell
/// types) can thus not derive `Immutable`:
///
/// [`UnsafeCell`]: core::cell::UnsafeCell
///
/// ```rust,compile_fail
/// use core::cell::Cell;
/// use oct::Immutable;
///
/// #[derive(Immutable)]
/// struct InteriourMutableI32 {
///     value: Cell<i32>,
/// }
/// ```
#[cfg(feature = "proc_macro")]
#[doc(inline)]
pub use oct_macros::Immutable;

/// Implements [`Zeroable`] for the given type.
///
/// [`Zeroable`]: trait@Zeroable
///
/// # Examples
///
/// Enumerations must have a variant that uses `0`
/// as its discriminant:
///
/// ```rust
/// use oct::Zeroable;
///
/// #[repr(u8)]
/// #[derive(Zeroable)]
/// enum ExplicitZero {
///     Zero = 0,
/// }
///
/// #[repr(i8)]
/// #[derive(Zeroable)]
/// enum ImplicitZero {
///     NegativeOne = -1,
///     Zero,
/// }
/// ```
///
/// Thus, the following is rejected:
///
/// ```rust,compile_fail
/// use oct::Zeroable;
///
/// #[repr(i32)]
/// #[derive(Zeroable)]
/// enum NoZeroDiscriminant {
///     NegativeTwo = -2,
///     NegativeOne,
///     One         = 1,
/// }
/// ```
#[cfg(feature = "proc_macro")]
#[doc(inline)]
pub use oct_macros::Zeroable;