Struct Shape 

#[repr(C)]
pub struct Shape {

    pub id: ConstTypeId,
    pub layout: ShapeLayout,
    pub vtable: VTableErased,
    pub type_ops: Option<TypeOps>,
    pub marker_traits: MarkerTraits,
    pub ty: Type,
    pub def: Def,
    pub type_identifier: &'static str,
    pub type_params: &'static [TypeParam],
    pub doc: &'static [&'static str],
    pub attributes: &'static [Attr],
    pub type_tag: Option<&'static str>,
    pub inner: Option<&'static Shape>,
    pub builder_shape: Option<&'static Shape>,
    pub type_name: Option<TypeNameFn>,
    pub proxy: Option<&'static ProxyDef>,
    pub variance: fn(&'static Shape) -> Variance,
    pub flags: ShapeFlags,
    pub tag: Option<&'static str>,
    pub content: Option<&'static str>,
}

Schema for reflection of a type — the core type in facet. Contains everything needed to inspect, allocate, and manipulate values at runtime.

Fields

id: ConstTypeId

Unique type identifier from the compiler. Use this for type equality checks and hash map keys.

layout: ShapeLayout

Size and alignment — enough to allocate (but not initialize). Check sized_layout() for sized types, or handle Unsized for slices/dyn.

vtable: VTableErased

Erased vtable for display, debug, default, clone, hash, eq, ord, etc. More specific vtables (e.g. for structs, enums) live in Def variants.

type_ops: Option<TypeOps>

Per-type operations that must be monomorphized (drop, default, clone).

For generic containers like Vec<T>, the main vtable can be shared across all instantiations (using type-erased operations), while type_ops contains the operations that must be specialized per-T.

• TypeOps::Direct for concrete types (uses thin pointers)
• TypeOps::Indirect for generic containers (uses wide pointers with shape)

marker_traits: MarkerTraits

Marker traits like Copy, Send, Sync, etc.

ty: Type

Underlying type category: primitive, array, slice, tuple, pointer, user-defined. Follows the Rust Reference.

def: Def

Type definition with variant-specific operations: scalar parsing, struct field access, enum variant iteration, map/list manipulation.

type_identifier: &'static str

Type name without generic parameters (e.g. Vec, not Vec<String>). For the full name with generics, use vtable.type_name.

type_params: &'static [TypeParam]

Generic type parameters (e.g. T in Vec<T>). Includes bounds and variance information.

doc: &'static [&'static str]

Doc comments from the original type definition. Collected by facet-macros; lines usually start with a space.

attributes: &'static [Attr]

Custom attributes applied to this type via #[facet(...)]. Use for validation, serialization hints, etc.

type_tag: Option<&'static str>

Type tag for self-describing formats (e.g. JSON with type discriminators). Can be a qualified name, simple string, or integer depending on format.

inner: Option<&'static Shape>

If set, this shape is a transparent wrapper around another shape. Newtypes (NonZero), path wrappers (Utf8PathBuf), smart pointers (Arc<T>). Serializes as the inner type: NonZero<u8> becomes 128, not {"value": 128}.

builder_shape: Option<&'static Shape>

Optional builder type for immutable collections. If set, deserializers should build this type first, then convert to the target type. Examples: Bytes builds through BytesMut, Arc<[T]> builds through Vec<T>.

type_name: Option<TypeNameFn>

Custom type name formatter for generic types. If None, uses type_identifier. If Some, calls the function to format the full type name including generic parameters (e.g., Vec<String>).

proxy: Option<&'static ProxyDef>

Container-level proxy for custom serialization/deserialization. Set by #[facet(proxy = ProxyType)] on the container.

variance: fn(&'static Shape) -> Variance

Variance of this type with respect to its type/lifetime parameters. For derived types, use Shape::computed_variance which walks fields. For leaf types, use Variance::COVARIANT, Variance::INVARIANT, etc.

flags: ShapeFlags

Bit flags for common boolean attributes.

Provides O(1) access to frequently-checked attributes like untagged. These are set by the derive macro based on #[facet(...)] attributes with #[storage(flag)] in the grammar.

tag: Option<&'static str>

Tag field name for internally/adjacently tagged enums. Set by #[facet(tag = "...")].

content: Option<&'static str>

Content field name for adjacently tagged enums. Set by #[facet(content = "...")].

Implementations

impl Shape

pub const fn builder_for_sized<T>(type_identifier: &'static str) -> ShapeBuilder

Create a new builder for a sized type.

The id and layout are derived from the type parameter.

pub const fn builder_for_unsized<T: ?Sized>( type_identifier: &'static str, ) -> ShapeBuilder

Create a new builder for an unsized type.

impl Shape

pub fn is_shape(&self, other: &Shape) -> bool

Check if this shape is of the given type

pub fn assert_shape(&self, other: &Shape)

Assert that this shape is equal to the given shape, panicking if it’s not

pub fn requires_eager_materialization(&self) -> bool

Returns true if this shape requires eager materialization.

Shapes that require eager materialization cannot have their construction deferred because they need all their data available at once. Examples include:

• Arc<[T]>, Box<[T]>, Rc<[T]> - slice-based smart pointers that need all elements to compute the final allocation

This is used by deferred validation mode in Partial to determine which shapes must be fully materialized before proceeding.

impl Shape

pub fn allocate(&self) -> Result<PtrUninit, UnsizedError>

Heap-allocate a value of this shape

pub unsafe fn deallocate_mut(&self, ptr: PtrMut) -> Result<(), UnsizedError>

Deallocate a heap-allocated value of this shape

Safety

• ptr must have been allocated using Self::allocate and be aligned for this shape.
• ptr must point to a region that is not already deallocated.

pub unsafe fn deallocate_uninit( &self, ptr: PtrUninit, ) -> Result<(), UnsizedError>

Deallocate a heap-allocated, uninitialized value of this shape.

Safety

• ptr must have been allocated using Self::allocate (or equivalent) for this shape.
• ptr must not have been already deallocated.
• ptr must be properly aligned for this shape.

impl Shape

pub const UNSIZED_LAYOUT: ShapeLayout = ShapeLayout::Unsized

Returns the unsized layout marker.

pub const fn id_of<T: ?Sized>() -> ConstTypeId

Returns a const type ID for type T.

pub const fn layout_of<T>() -> ShapeLayout

Returns the sized layout for type T.

pub fn has_deny_unknown_fields_attr(&self) -> bool

Returns true if this shape has the deny_unknown_fields builtin attribute.

pub fn has_default_attr(&self) -> bool

Returns true if this shape has the default builtin attribute.

pub fn has_builtin_attr(&self, key: &str) -> bool

Returns true if this shape has a builtin attribute with the given key.

pub fn is_transparent(&self) -> bool

Returns true if this shape is transparent.

A type is transparent if it has #[repr(transparent)] or is marked with #[facet(transparent)].

pub fn is_untagged(&self) -> bool

Returns true if this enum is untagged.

Untagged enums serialize their content directly without any discriminant. This checks the UNTAGGED flag (O(1)).

pub fn get_tag_attr(&self) -> Option<&'static str>

Returns the tag field name for internally/adjacently tagged enums.

This is the direct field access (O(1)), not an attribute lookup.

pub fn get_content_attr(&self) -> Option<&'static str>

Returns the content field name for adjacently tagged enums.

This is the direct field access (O(1)), not an attribute lookup.

pub fn get_builtin_attr_value<'a, T: Facet<'a> + Copy + 'static>( &self, key: &str, ) -> Option<T>

Gets a builtin attribute value by key.

This is a helper for attributes with simple payload types like &'static str.

pub fn computed_variance(&'static self) -> Variance

Compute the variance of this type by walking its fields recursively.

This method walks struct fields and enum variants to determine the combined variance. For leaf types (scalars, etc.), it delegates to the variance field.

impl Shape

pub unsafe fn call_debug( &'static self, ptr: PtrConst, f: &mut Formatter<'_>, ) -> Option<Result>

Call the debug function, regardless of vtable style.

Safety

ptr must point to a valid value of this shape’s type.

pub unsafe fn call_display( &'static self, ptr: PtrConst, f: &mut Formatter<'_>, ) -> Option<Result>

Call the display function, regardless of vtable style.

Safety

ptr must point to a valid value of this shape’s type.

pub unsafe fn call_hash( &'static self, ptr: PtrConst, hasher: &mut HashProxy<'_>, ) -> Option<()>

Call the hash function, regardless of vtable style.

Safety

ptr must point to a valid value of this shape’s type.

pub unsafe fn call_partial_eq( &'static self, a: PtrConst, b: PtrConst, ) -> Option<bool>

Call the partial_eq function, regardless of vtable style.

Safety

a and b must point to valid values of this shape’s type.

pub unsafe fn call_partial_cmp( &'static self, a: PtrConst, b: PtrConst, ) -> Option<Option<Ordering>>

Call the partial_cmp function, regardless of vtable style.

Safety

a and b must point to valid values of this shape’s type.

pub unsafe fn call_cmp( &'static self, a: PtrConst, b: PtrConst, ) -> Option<Ordering>

Call the cmp function, regardless of vtable style.

Safety

a and b must point to valid values of this shape’s type.

pub unsafe fn call_drop_in_place(&'static self, ptr: PtrMut) -> Option<()>

Call the drop_in_place function from type_ops.

Safety

ptr must point to a valid value of this shape’s type that can be dropped.

pub unsafe fn call_default_in_place(&'static self, ptr: PtrMut) -> Option<()>

Call the default_in_place function from type_ops.

Safety

ptr must point to uninitialized memory suitable for this shape’s type.

pub unsafe fn call_invariants( &'static self, ptr: PtrConst, ) -> Option<Result<(), String>>

Call the invariants function, regardless of vtable style.

Safety

ptr must point to a valid value of this shape’s type.

pub unsafe fn call_parse( &'static self, s: &str, dst: PtrMut, ) -> Option<Result<(), ParseError>>

Call the parse function, regardless of vtable style.

Safety

dst must point to uninitialized memory suitable for this shape’s type.

pub unsafe fn call_try_from( &'static self, src_shape: &'static Shape, src: PtrConst, dst: PtrMut, ) -> Option<Result<(), String>>

Call the try_from function, regardless of vtable style.

Safety

src must point to a valid value of the source type (described by src_shape). dst must point to uninitialized memory suitable for this shape’s type.

pub unsafe fn call_try_borrow_inner( &'static self, ptr: PtrConst, ) -> Option<Result<PtrMut, String>>

Call the try_borrow_inner function, regardless of vtable style.

Safety

ptr must point to a valid value of this shape’s type.

pub unsafe fn call_clone_into( &'static self, src: PtrConst, dst: PtrMut, ) -> Option<()>

Call the clone_into function from type_ops.

Safety

src must point to a valid value of this shape’s type. dst must point to uninitialized memory suitable for this shape’s type.

pub fn is_type<T: Facet<'static>>(&self) -> bool

Check if this shape represents the given type.

pub fn truthiness_fn(&self) -> Option<TruthyFn>

Returns the truthiness predicate stored on this shape, if any.

impl Shape

pub fn scalar_type(&self) -> Option<ScalarType>

Get the scalar type if this shape represents a scalar.

Returns Some(ScalarType) if this shape corresponds to a known scalar type (primitives, String, Cow<str>, network address types, etc.), or None if it’s a non-scalar type like a struct, enum, list, or map.

Example

use facet_core::{Facet, ScalarType};

assert_eq!(bool::SHAPE.scalar_type(), Some(ScalarType::Bool));
assert_eq!(u32::SHAPE.scalar_type(), Some(ScalarType::U32));
assert_eq!(f64::SHAPE.scalar_type(), Some(ScalarType::F64));

impl Shape

pub const fn is(&self, characteristic: Characteristic) -> bool

Checks if a shape has the given characteristic.

pub const fn is_clone(&self) -> bool

Check if this shape implements the Clone trait

pub const fn is_display(&self) -> bool

Check if this shape implements the Display trait

pub const fn is_debug(&self) -> bool

Check if this shape implements the Debug trait

pub const fn is_partial_eq(&self) -> bool

Check if this shape implements the PartialEq trait

pub const fn is_partial_ord(&self) -> bool

Check if this shape implements the PartialOrd trait

pub const fn is_ord(&self) -> bool

Check if this shape implements the Ord trait

pub const fn is_hash(&self) -> bool

Check if this shape implements the Hash trait

pub const fn is_default(&self) -> bool

Check if this shape implements the Default trait

pub const fn is_from_str(&self) -> bool

Check if this shape implements the FromStr trait

pub fn write_type_name( &'static self, f: &mut Formatter<'_>, opts: TypeNameOpts, ) -> Result

Writes the name of this type to the given formatter.

If the type has a custom type_name function, it will be used. Otherwise, falls back to the type_identifier.

pub fn type_name(&'static self) -> TypeNameDisplay

Returns a wrapper that implements Display for the full type name including generic parameters.

Example

extern crate alloc;
use facet_core::Facet;
use alloc::vec::Vec;

let shape = <Vec<u32>>::SHAPE;
assert_eq!(format!("{}", shape.type_name()), "Vec<u32>");

Trait Implementations

impl Clone for Shape

fn clone(&self) -> Shape

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Shape

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Shape

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Facet<'_> for Shape

const SHAPE: &'static Shape

The shape of this type, including: whether it’s a Struct, an Enum, something else?

impl Hash for Shape

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Shape

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Shape

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Shape

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Shape

impl Eq for Shape