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 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.
• mutability: whether type can be mutated through shared access.
• drop: whether dropping runs custom or compiler-generated code.

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:

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

Alignment

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

Trap

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

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

Niche

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

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

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

Drop

Describes the type’s behavior when dropped:

• NoDrop: dropping the type runs no drop glue.
• AutoDrop: owned contents need automatic drop glue.
• CustomDrop<NoDrop>: the type implements Drop and its contents need no automatic drop glue.
• CustomDrop<AutoDrop>: the type implements Drop and its contents need automatic drop glue.

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

Mutability

Describes whether a type has parts that can be mutated through shared access:

• Exclusive: mutation requires exclusive non-interleaving access.
• WithInterior: a part can be mutated through shared access.

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.

mutability

Mutability classification of Rust types.

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 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.

Opaque

Marker for a type whose value representation is opaque (unreadable).

RustSpec

Joined Rust-spec classification of a type.

Derive Macros

RustSpec

Derives RustSpec for a struct, enum, or union.