Allow specifing an expected type for field_offset!

Add detailed documentation and doc-tests

Author: Techcable

src/lib.rs

@@ -10,6 +10,7 @@
 //! I'd be happy to add more features as long as they align with the general philosophy
 //! of compile-time reflection.
 #![deny(missing_docs)]
+#![deny(unused_features, stable_features)]
 #![feature(
     const_panic, const_option, // We use Option::unwrap
     const_fn_fn_ptr_basics, // We use PhantomData<fn() -> T>

src/macros.rs

@@ -5,7 +5,7 @@
 macro_rules! define_extern_type {
     ($target:ident) => ($crate::define_extern_type!($target => $target););
     ($target:ty => $defined_path:path) => {
-        unsafe impl ::static_reflect::StaticReflect for $target {
+        unsafe impl $crate::StaticReflect for $target {
             const TYPE_INFO: $crate::TypeInfo<'static> = $crate::TypeInfo::Extern {
                 name: stringify!($defined_path)
             };
@@ -14,13 +14,55 @@ macro_rules! define_extern_type {
 }
 
 /// Get the integer offset of the specified field
+///
+/// This is only well defined for `#[repr(C)]` types,
+/// since `#[repr(Rust)]` types don't have a well-defined layout.
+///
+/// ## Examples
+/// ````
+/// # use static_reflect::field_offset;
+/// # #[repr(C)]
+/// # struct Nested {
+/// #     nested: u32
+/// # }
+/// #[repr(C)]
+/// struct Example {
+///     first: u32,
+///     second: u8,
+///     third: Nested,
+/// }
+/// assert_eq!(field_offset!(Example, first), 0);
+/// // You may specify the expected type by suffixing with `as $expected_type`
+/// assert_eq!(field_offset!(Example, second as u8), 4);
+/// // Fields can be arbitrarily nested
+/// assert_eq!(field_offset!(Example, third.nested as u32), 8);
+/// ````
+///
+/// ## Const eval
+/// Assuming you specify the appropriate feature flags,
+/// this macro can also be used in a const-eval context.
+/// ````
+/// #![feature(const_raw_ptr_deref, const_maybe_uninit_as_ptr, const_ptr_offset_from)]
+/// # #![deny(unused_features, stable_features)]
+/// # use static_reflect::field_offset;
+/// struct Example {
+///     first: u32,
+///     second: u8,
+/// }
+/// const FIRST_OFFSET: usize = field_offset!(Example, first as u32);
+/// assert_eq!(FIRST_OFFSET, 0);
+/// const SECOND_OFFSET: usize = field_offset!(Example, second as u8);
+/// assert_eq!(SECOND_OFFSET, 4);
+/// ````
 #[macro_export]
 macro_rules! field_offset {
-    ($target:path, $($field:ident),+) => {
+    ($target:path, $($field:ident).*) => (field_offset!($target, $($field).* as _));
+    ($target:path, $($field:ident).+ as $expected_type:ty) => {
         unsafe {
             let uninit = core::mem::MaybeUninit::<$target>::uninit();
             let base = uninit.as_ptr();
-            (core::ptr::addr_of!((*base)$(.$field)*).cast::<u8>().offset_from(base as *const u8) as usize)
+            let ptr: *const $expected_type = core::ptr::addr_of!((*base)$(.$field)*);
+            ptr.cast::<u8>().offset_from(base as *const u8) as usize
         }
     }
 }