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.
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 Numbered;
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 are allowed. number(&self) ignores the payload, so the
same enum can also derive cognomen
and interpolate {field} in extras. from_number is omitted (a number
cannot rebuild fields). VARIANTS is then &[()] of length COUNT;
NUMBERS is unchanged.
Generated API
For #[numbered(u8)] on E:
| item | notes |
|---|---|
number() / as_u8() |
assigned number; &self (as_* follows the repr: as_u16, as_i32, ...) |
from_number / from_u8 |
Result<Self, FromNumberError<u8>> (fieldless) |
Variants |
E::VARIANTS / E::NUMBERS / E::COUNT after use numbered::Variants (non-generic). Trait items, so they cannot clash with cognomen |
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 }
Numbers, parse, 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.