numbered
Derive stable integer numbers for enum variants. This crate
kills the boilerplate of handwritten from_u8 / as_u8 matches: you pick a
repr, optionally pin a few variants, and the rest continue from the last
assigned number.
Numbers are trait items (Number, FromNumber), not inherent methods on
E. Import the trait to call e.number(), or use UFCS when a user fn
or parent trait owns the same name.
Full API reference: https://docs.rs/numbered
[]
= "0.1"
use ;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert!;
assert_eq!;
assert_eq!;
Native Rust discriminants (Process = 1) are treated as #[numbered(n = 1)].
If both are present they must agree, or the derive is a compile error. A
variant named Error is fine: generated TryFrom names FromNumberError
instead of Self::Error.
Attributes
Container (required): #[numbered(<repr>, ...)]
| key | required | notes |
|---|---|---|
u8 / u16 / u32 / u64 / usize / i8 / i16 / i32 / i64 / isize |
yes | first positional, or repr = u8 |
start = 1 |
no | first auto-assigned number when no discriminant / n is set (default 0) |
crate = ::other::numbered |
no | path used in generated code when this crate is re-exported |
Variant (optional): #[numbered(n = 5)]
Pins that variant to an explicit integer. A native = 5 discriminant does
the same. Gaps are allowed. After an explicit number, the next auto variant
is last + 1.
use ;
assert_eq!;
assert_eq!;
assert_eq!;
Violations (non-enum, empty enum, missing repr, duplicate keys, unknown
keys, collisions, overflow, disagreeing discriminant) are compile errors,
pinned by trybuild tests under tests/ui/.
Fielded variants keep Number. number(&self) ignores the payload, so the
same enum can also derive cognomen
and interpolate {field} in extras. FromNumber is omitted (a number
cannot rebuild fields). VARIANTS is then &[()] of length COUNT;
NUMBERS is unchanged.
Generated API
For #[numbered(u8)] on E. Nothing is inherent on E.
| item | notes |
|---|---|
Number |
number() / as_u8(); &self (as_* follows the repr: as_u16, as_i32, ...). Not const |
FromNumber |
from_number / from_u8; Result<Self, FromNumberError<u8>> (fieldless). Not const |
Variants |
E::VARIANTS / E::NUMBERS / E::COUNT after use numbered::Variants (non-generic). Trait items, so they cannot clash with cognomen. Const use goes through NUMBERS |
From<E> for u8, TryFrom<u8> for E |
TryFrom is fieldless; uses core |
PartialEq<u8> both ways |
compare a variant against its number |
Serialize / Deserialize |
feature serde; the number, not a string. Deserialize is fieldless. Do not enable serde on both Numbered and Cognomen for the same type |
Features
| feature | default | unlocks |
|---|---|---|
std |
yes | alloc + std::error::Error for FromNumberError |
alloc |
via std |
kept for feature parity; the unmatched number is always stored |
serde |
no | Serialize / Deserialize as the number |
no_std, including embedded:
= { = "0.2", = false }
Number, FromNumber, From / TryFrom, and Variants use only core.
Add features = ["serde"] for wire formats. Print a number with
e.number().
MSRV
Rust 1.71.1. Floor is the pinned proc-macro2 (rustc 1.71+).
Publishing
numbered depends on numbered-macros by version. The first crates.io
upload must publish numbered-macros first, then numbered. New crate
names cannot use trusted publishing; that first upload is manual. Later
releases are prepared and published by release-plz on main.
License
Dual-licensed under MIT OR Apache-2.0, see
LICENSE-MIT and LICENSE-APACHE.
Copyright (c) 2026 Matheus Cardoso.