Crate rust_spec 

Compile-time classification of types according to the Rust specification.

Classification Axes

RustSpec describes a type across the following axes:

• layout: representation stability.
• size: statically sized, metadata-sized, or extern-type-like shape.
• Alignment: whether ABI alignment is one or greater than one.
• trap: whether the value representation has trap values.
• niche: whether a type has a stable, unstable, or no niche value.
• drop: whether no code runs on drop, custom code or inner field’s.

Layout

Describes total reachable (through pointer indirection) representation stability:

• Stable: compiler-guaranteed representation.
• Unstable: representation is not guaranteed.

Size

Describes compile-time size and pointer metadata shape:

• size::Sized<Zero>: compile-time known zero-sized type.
• size::Sized<Gt<Zero>>: compile-time known non-zero-sized type.
• size::MetaSized<size::SliceLike>: dynamically sized slice-like type.
• size::MetaSized<size::DynTraitLike>: dynamically sized trait-object-like type.
• size::ExternTypeLike: dynamically sized extern-type-like type.
• size::NulTerminated: unsized nul-terminated data.

Alignment

• One means ABI alignment is exactly one;
• Gt<One> means it is greater than one.

Trap

Describes total reachable (through pointer indirection) value-representation validity:

• layout::Robust: every bit pattern is valid.
• layout::NonRobust: some bit patterns are trap/invalid values.

Niche

Describes whether and what kind of niche is available for the type:

• niche::WithoutNiche: no niche is available.
• niche::WithNiche<Stable>: compiler-guaranteed niche.
• niche::WithNiche<Unstable>: niche exists but is not guaranteed.

Use #[rust_spec(custom_niche)] when deriving RustSpec to select WithNiche<Unstable>.

Drop

Describes the type’s behavior when dropped:

• drop::NoDrop: dropping the type runs no drop glue.
• drop::WithDrop<drop::Inner>: a field or other owned content has drop behavior.
• drop::WithDrop<drop::Custom>: the type implements Drop without inner drop requirements.

Use #[rust_spec(custom_drop)] when deriving RustSpec for a type that implements Drop.

How to Use

Derive RustSpec for your types, then use its associated marker families as bounds when implementing other traits:

use disjoint_impls::disjoint_impls;
use rust_spec::{RustSpec, Stable, Unstable, niche::{WithNiche, WithoutNiche}};

#[derive(RustSpec)]
struct Header {
    id: u32,
    flags: u16,
}

disjoint_impls! {
    trait NullableEncoding {
        const NEEDS_TAG: bool;
    }

    impl<T: RustSpec<Niche = WithoutNiche>> NullableEncoding for T {
        const NEEDS_TAG: bool = true;
    }

    impl<T: RustSpec<Niche = WithNiche<Stable>>> NullableEncoding for T {
        const NEEDS_TAG: bool = false;
    }

    impl<T: RustSpec<Niche = WithNiche<Unstable>>> NullableEncoding for T {
        const NEEDS_TAG: bool = false;
    }
}

const HEADER_OPTION_NEEDS_TAG: bool = Header::NEEDS_TAG;

Check out CO3 to see how this crate allows for building higher zero-cost abstractions.

Modules

drop

Drop behavior classification.

layout

Representation stability and trap/robustness classification.

niche

Logic related to the conversion of Option<T> to and from FFI-compatible representation

size

Structs

Gt

Marker for a statically sized type greater than the given threshold.

Enums

One

Marker for ABI alignment one.

Stable

Marker for a compiler-guaranteed representation or niche.

Unstable

Marker for a representation or niche that is not compiler-guaranteed.

Zero

Marker for a zero-sized type.

Traits

Max

Type-level maximum used to combine alignment categories.

RustSpec

Joined Rust-spec classification of a type.

Derive Macros

RustSpec

Derives RustSpec for a struct, enum, or union.