subtype_macro

Changelog

[0.2.1] — 2025-10-14

Formal enum-mode support + stronger struct-mode transparency. #[subtype] now works on C-like enums with an explicit integer #[repr(..)]. In struct mode, the macro auto-adds #[repr(transparent)] to improve FFI/ABI guarantees. Crate-level docs and examples were expanded.

Added

• Enum mode (requires an integer #[repr(u8) | u16 | …]):

  • Common impls: Display (numeric), From<Enum> for repr, and to_repr().

  • TryFrom<repr>:

    • Contiguous literal enums (all discriminants are integer literals forming an unbroken range): uses a bounds check followed by an optimized unsafe transmute.
    • Otherwise: uses an explicit match over known discriminants.

  • Custom error type: error = "path::ToErr" or error(path::ToErr). If omitted, a lightweight <EnumName>TryFromError is generated.

• Crate-level documentation (//! …):

  • Clear how-tos for struct/enum modes, runnable examples, and a safety note for the enum fast path.

Changed

• Struct mode #[repr(transparent)] auto-insertion:

  • If the user forgets it, the macro adds it (and won’t duplicate it if already present).

• Improved diagnostics:

  • Clearer error when an enum lacks a primitive #[repr(..)].
  • Better messages for malformed error(...) arguments.

• Helper refactor:

  • Primitive-integer checks extracted to is_primitive_integer_ident for readability.

Docs

• Full examples for both struct and enum modes (including custom error types) with safety notes.
• Short rustdoc comments on public APIs (MIN/MAX, new, into_inner, to_repr, etc.).

Safety

• Enum fast path:

  • transmute only after verifying MIN <= x <= MAX, which makes the cast sound.

• Struct-mode FFI/ABI:

  • Auto #[repr(transparent)] strengthens compatibility with C ABIs.

Migration notes (from 0.2.0)

• When using #[subtype] on enums, you must specify a primitive integer #[repr(..)] (e.g., #[repr(u8)]).
• Custom error types are supported in both modes; implement From<subtype_rs::SubtypeError<ReprOrInner>>.
• Struct mode may now auto-add #[repr(transparent)]. This is typically desirable; review only if you relied on a non-transparent layout for unusual reasons.