facet_core/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2// Enable portable_simd when available (detected via autocfg in build.rs)
3#![cfg_attr(has_portable_simd, feature(portable_simd))]
4#![warn(missing_docs)]
5#![warn(clippy::std_instead_of_core)]
6#![warn(clippy::std_instead_of_alloc)]
7// Allow uncommon unicode in the 𝟋 prelude module
8#![allow(uncommon_codepoints)]
9#![doc = include_str!("../README.md")]
10
11#[cfg(feature = "alloc")]
12extern crate alloc;
13
14// Core type definitions (merged from facet-core-types)
15mod types;
16pub use types::*;
17
18// Write trait for serializers
19mod write;
20pub use write::Write;
21
22// Implementations of the Shape trait
23mod impls;
24
25/// Allows querying the [`Shape`] of a type, which in turn lets us inspect any fields, build a value of
26/// this type progressively, etc.
27///
28/// The `'facet` lifetime allows `Facet` to be derived for types that borrow from something else.
29///
30/// # Safety
31///
32/// If you implement this wrong, all the safe abstractions in `facet-reflect`,
33/// all the serializers, deserializers, the entire ecosystem is unsafe.
34///
35/// You're responsible for describing the type layout properly, and annotating all the invariants.
36pub unsafe trait Facet<'facet>: 'facet {
37    /// The shape of this type, including: whether it's a Struct, an Enum, something else?
38    ///
39    /// All its fields, with their names, types, attributes, doc comments, etc.
40    /// VTables for list operations, set operations, map operations, option operations,
41    /// and implementations for Display, Debug, etc.—marker traits like Send, Sync, Copy, Eq,
42    /// and probably other things I'm forgetting.
43    const SHAPE: &'static Shape;
44}
45
46/// Returns the shape of a type as a function pointer.
47///
48/// This is a helper for lazy shape initialization in field definitions.
49/// Using a function pointer instead of a direct reference moves const
50/// evaluation from compile time to runtime, improving compile times.
51///
52/// # Example
53///
54/// ```ignore
55/// use facet_core::{FieldBuilder, shape_of};
56///
57/// // In field definitions:
58/// FieldBuilder::new("my_field", shape_of::<i32>, 0)
59/// ```
60#[inline]
61pub const fn shape_of<'a, T: Facet<'a>>() -> &'static Shape {
62    T::SHAPE
63}
64
65/// Ultra-compact prelude for derive macro codegen (the "digamma" prelude).
66///
67/// All exports are prefixed with `𝟋` to avoid collisions after `use ::facet::𝟋::*;`
68///
69/// The `𝟋` character (U+1D4CB, Mathematical Script Small F, "digamma") was chosen because:
70/// - It's a valid Rust identifier (XID_Start)
71/// - It's visually distinctive ("this is internal macro stuff")
72/// - It won't collide with any user-defined names
73#[doc(hidden)]
74#[allow(nonstandard_style)]
75pub mod 𝟋 {
76    // === Type aliases ===
77    pub use crate::Attr as 𝟋Attr;
78    pub use crate::Def as 𝟋Def;
79    pub use crate::DefaultSource as 𝟋DS;
80    pub use crate::EnumRepr as 𝟋ERpr;
81    pub use crate::EnumType as 𝟋ETy;
82    pub use crate::EnumTypeBuilder as 𝟋ETyB;
83    pub use crate::Facet as 𝟋Fct;
84    pub use crate::Field as 𝟋Fld;
85    pub use crate::FieldBuilder as 𝟋FldB;
86    pub use crate::FieldFlags as 𝟋FF;
87    pub use crate::HashProxy as 𝟋HP;
88    pub use crate::MarkerTraits as 𝟋Mt;
89    pub use crate::Repr as 𝟋Repr;
90    pub use crate::Shape as 𝟋Shp;
91    pub use crate::ShapeBuilder as 𝟋ShpB;
92    pub use crate::ShapeFlags as 𝟋ShpF;
93    pub use crate::ShapeRef as 𝟋ShpR;
94    pub use crate::StructKind as 𝟋Sk;
95    pub use crate::StructType as 𝟋STy;
96    pub use crate::StructTypeBuilder as 𝟋STyB;
97    pub use crate::Type as 𝟋Ty;
98    pub use crate::UserType as 𝟋UTy;
99    pub use crate::VTableDirect as 𝟋VtD;
100    pub use crate::VTableErased as 𝟋VtE;
101    pub use crate::Variance as 𝟋Vnc;
102    pub use crate::VarianceDesc as 𝟋VncD;
103    pub use crate::Variant as 𝟋Var;
104    pub use crate::VariantBuilder as 𝟋VarB;
105    pub use ::core::option::Option::None as 𝟋None;
106    pub use ::core::option::Option::Some as 𝟋Some;
107    pub use ::core::result::Result::Err as 𝟋Err;
108    pub use ::core::result::Result::Ok as 𝟋Ok;
109
110    // === Core utility re-exports ===
111    pub use ::core::mem::forget as 𝟋forget;
112    pub use ::core::mem::transmute as 𝟋transmute;
113    pub use ::core::ptr::drop_in_place as 𝟋drop_in_place;
114
115    /// Helper to get shape of a type as a function - monomorphized per type
116    pub use crate::shape_of as 𝟋shp;
117
118    // === Declaration ID ===
119    pub use crate::DeclId as 𝟋DId;
120    pub use crate::decl_id_hash as 𝟋dih;
121
122    // === Constants ===
123    /// Empty attributes slice
124    pub const 𝟋NOAT: &[crate::FieldAttribute] = &[];
125    /// Empty doc slice
126    pub const 𝟋NODOC: &[&str] = &[];
127    /// Empty flags
128    pub const 𝟋NOFL: crate::FieldFlags = crate::FieldFlags::empty();
129    /// Computed variance (for non-opaque types) - bivariant base with field walking fallback
130    pub const 𝟋CV: crate::VarianceDesc = crate::VarianceDesc::BIVARIANT;
131
132    // === Type Aliases ===
133    /// PhantomData type for shadow structs, invariant with respect to lifetime `'a`.
134    pub type 𝟋Ph<'a> = ::core::marker::PhantomData<*mut &'a ()>;
135
136    /// String type for proxy conversion errors (requires alloc feature).
137    #[cfg(feature = "alloc")]
138    pub type 𝟋Str = ::alloc::string::String;
139
140    /// Fallback when alloc is not available - proxy requires alloc at runtime,
141    /// but we need a type for compilation in no_std contexts.
142    #[cfg(not(feature = "alloc"))]
143    pub type 𝟋Str = &'static str;
144
145    /// Result type alias for macro-generated code.
146    pub type 𝟋Result<T, E> = ::core::result::Result<T, E>;
147
148    // === Helper functions ===
149    /// Returns `drop_in_place::<T>` as a function pointer for vtable construction.
150    pub const fn 𝟋drop_for<T>() -> unsafe fn(*mut T) {
151        ::core::ptr::drop_in_place::<T>
152    }
153
154    /// Returns a default_in_place function pointer for TypeOpsDirect.
155    /// # Safety
156    /// The pointer must point to uninitialized memory of sufficient size and alignment for T.
157    pub const fn 𝟋default_for<T: Default>() -> unsafe fn(*mut T) {
158        unsafe fn default_in_place<T: Default>(ptr: *mut T) {
159            unsafe { ptr.write(T::default()) };
160        }
161        default_in_place::<T>
162    }
163
164    /// Returns a clone_into function pointer for TypeOpsDirect.
165    /// # Safety
166    /// - `src` must point to a valid, initialized value of type T
167    /// - `dst` must point to uninitialized memory of sufficient size and alignment for T
168    pub const fn 𝟋clone_for<T: Clone>() -> unsafe fn(*const T, *mut T) {
169        unsafe fn clone_into<T: Clone>(src: *const T, dst: *mut T) {
170            unsafe { dst.write((*src).clone()) };
171        }
172        clone_into::<T>
173    }
174
175    // === TypeOpsIndirect helpers ===
176    // These take OxPtrMut/OxPtrConst and work with wide pointers
177
178    /// Returns a drop_in_place function pointer for TypeOpsIndirect.
179    pub const fn 𝟋indirect_drop_for<T>() -> unsafe fn(crate::OxPtrMut) {
180        unsafe fn drop_in_place<T>(ox: crate::OxPtrMut) {
181            unsafe { ::core::ptr::drop_in_place(ox.ptr().as_ptr::<T>() as *mut T) };
182        }
183        drop_in_place::<T>
184    }
185
186    /// Returns a default_in_place function pointer for TypeOpsIndirect.
187    pub const fn 𝟋indirect_default_for<T: Default>() -> unsafe fn(crate::OxPtrMut) {
188        unsafe fn default_in_place<T: Default>(ox: crate::OxPtrMut) {
189            unsafe { ox.ptr().as_uninit().put(T::default()) };
190        }
191        default_in_place::<T>
192    }
193
194    /// Returns a clone_into function pointer for TypeOpsIndirect.
195    pub const fn 𝟋indirect_clone_for<T: Clone>() -> unsafe fn(crate::OxPtrConst, crate::OxPtrMut) {
196        unsafe fn clone_into<T: Clone>(src: crate::OxPtrConst, dst: crate::OxPtrMut) {
197            let src_val = unsafe { &*(src.ptr().as_byte_ptr() as *const T) };
198            unsafe { dst.ptr().as_uninit().put(src_val.clone()) };
199        }
200        clone_into::<T>
201    }
202
203    // === Specialization ===
204    pub use crate::types::specialization::impls;
205    pub use crate::types::specialization::{
206        Spez, SpezCloneIntoNo, SpezCloneIntoYes, SpezDebugNo, SpezDebugYes, SpezDefaultInPlaceNo,
207        SpezDefaultInPlaceYes, SpezDisplayNo, SpezDisplayYes, SpezEmpty, SpezHashNo, SpezHashYes,
208        SpezOrdNo, SpezOrdYes, SpezParseNo, SpezParseYes, SpezPartialEqNo, SpezPartialEqYes,
209        SpezPartialOrdNo, SpezPartialOrdYes,
210    };
211}
facet_core/lib.rs

facet_core/
lib.rs
