rkyv/
macros.rs

1#[cfg(feature = "copy")]
2macro_rules! default {
3    (#[inline] $($fn:tt)*) => { #[inline] default $($fn)* };
4    ($($fn:tt)*) => { default $($fn)* };
5}
6
7#[cfg(not(feature = "copy"))]
8macro_rules! default {
9    (#[inline] $($fn:tt)*) => { #[inline] $($fn)* };
10    ($($fn:tt)*) => { $($fn)* };
11}
12
13/// Returns a tuple of `(field_pos, field_out)`, where `field_pos` is the "position",
14/// i.e. offset in bytes, of the field relative to the base address of the struct and `field_out`
15/// is a `*mut` that points to the field directly.
16///
17/// This is essentially a convenience wrapper around [`core::ptr::addr_of_mut!`] that also
18/// gives back the relative offset of the field, as these are often needed together. You will often
19/// see the return values named `(fp, fo)` in internal use of this macro, which stand for `field_pos`
20/// and `field_out` respectively as discussed above.
21///
22/// # Example
23///
24/// ```
25/// use core::mem::MaybeUninit;
26/// use rkyv::out_field;
27///
28/// // The macro works on repr(Rust) structs as well, but for the purposes of asserting
29/// // an exact guaranteed position of each field in this example, we'll use repr(C)
30/// #[repr(C)]
31/// struct Example {
32///     a: i32,
33///     b: bool,
34/// }
35///
36/// let mut result = MaybeUninit::<Example>::zeroed();
37/// let out = result.as_mut_ptr();
38///
39/// let (a_pos, a_out) = out_field!(out.a);
40/// assert_eq!(a_pos, 0); // guaranteed by repr(C) layout, repr(Rust) has free reign
41/// unsafe { a_out.write(42); }
42///
43/// let (b_pos, b_out) = out_field!(out.b);
44/// assert_eq!(b_pos, 4); // guaranteed by repr(C) layout, repr(Rust) has free reign
45/// unsafe { b_out.write(true); }
46///
47/// let result = unsafe { result.assume_init() };
48/// assert_eq!(result.a, 42);
49/// assert_eq!(result.b, true);
50/// ```
51#[macro_export]
52macro_rules! out_field {
53    ($out:ident.$field:tt) => {{
54        #[allow(unused_unsafe)]
55        unsafe {
56            let fo = ::core::ptr::addr_of_mut!((*$out).$field);
57            (fo.cast::<u8>().offset_from($out.cast::<u8>()) as usize, fo)
58        }
59    }};
60}
61
62/// Returns the unarchived value of the given archived primitive.
63///
64/// This macro is not needed for most use cases. Its primary purpose is to simultaneously:
65/// - Convert values from (potentially) different archived primitives to their native counterparts
66/// - Allow transformation in `const` contexts
67/// - Prevent linter warnings from unused `into()` calls
68///
69/// Users should feel free to use the more ergonomic `into()` where appropriate.
70#[macro_export]
71macro_rules! from_archived {
72    ($expr:expr) => {{
73        #[cfg(not(any(feature = "archive_le", feature = "archive_be")))]
74        {
75            $expr
76        }
77        #[cfg(any(feature = "archive_le", feature = "archive_be"))]
78        {
79            ($expr).value()
80        }
81    }};
82}
83
84#[cfg(any(feature = "archive_le", feature = "archive_be"))]
85pub use crate::rend::NativeEndian;
86
87/// Returns the archived value of the given archived primitive.
88///
89/// This macro is not needed for most use cases. Its primary purpose is to simultaneously:
90/// - Convert values from (potentially) different primitives to their archived counterparts
91/// - Allow transformation in `const` contexts
92/// - Prevent linter warnings from unused `into()` calls
93///
94/// Users should feel free to use the more ergonomic `into()` where appropriate.
95#[macro_export]
96macro_rules! to_archived {
97    ($expr:expr) => {{
98        #[cfg(not(any(feature = "archive_le", feature = "archive_be")))]
99        {
100            $expr
101        }
102        #[cfg(feature = "archive_le")]
103        {
104            $crate::macros::NativeEndian { value: $expr }.to_le()
105        }
106        #[cfg(feature = "archive_be")]
107        {
108            $crate::macros::NativeEndian { value: $expr }.to_be()
109        }
110    }};
111}
112
113#[cfg(not(any(feature = "size_16", feature = "size_32", feature = "size_64")))]
114core::compile_error!(r#"one of ["size_16", "size_32", or "size_64"] features must be enabled"#);
115
116#[cfg(all(feature = "size_16", feature = "size_32"))]
117core::compile_error!(
118    "\"size_16\" and \"size_32\" are mutually-exclusive features. You may need to set \
119    `default-features = false` or compile with `--no-default-features`."
120);
121#[cfg(all(feature = "size_16", feature = "size_64"))]
122core::compile_error!(
123    "\"size_16\" and \"size_64\" are mutually-exclusive features. You may need to set \
124    `default-features = false` or compile with `--no-default-features`."
125);
126#[cfg(all(feature = "size_32", feature = "size_64"))]
127core::compile_error!(
128    "\"size_32\" and \"size_64\" are mutually-exclusive features. You may need to set \
129    `default-features = false` or compile with `--no-default-features`."
130);
131
132#[cfg(feature = "size_16")]
133macro_rules! pick_size_type {
134    ($s16:ty, $s32:ty, $s64:ty) => {
135        $s16
136    };
137    ($s16:ty, $s32:ty, $s64:ty,) => {
138        pick_size_type!($s16, $s32, $s64)
139    };
140}
141
142#[cfg(feature = "size_32")]
143macro_rules! pick_size_type {
144    ($s16:ty, $s32:ty, $s64:ty) => {
145        $s32
146    };
147    ($s16:ty, $s32:ty, $s64:ty,) => {
148        pick_size_type!($s16, $s32, $s64)
149    };
150}
151
152#[cfg(feature = "size_64")]
153macro_rules! pick_size_type {
154    ($s16:ty, $s32:ty, $s64:ty) => {
155        $s64
156    };
157    ($s16:ty, $s32:ty, $s64:ty,) => {
158        pick_size_type!($s16, $s32, $s64)
159    };
160}
rkyv/macros.rs

rkyv/
macros.rs
