numbered 0.4.0

Derive stable integer numbers for enum variants.
Documentation

numbered

crates.io docs.rs license

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

[dependencies]
numbered = "0.1"
use numbered::{FromNumber, Number, Numbered, Variants};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
#[numbered(u8)]
enum Kind {
    Process,                 // 0
    File,                    // 1
    #[numbered(n = 10)]
    Network,                 // 10
    Socket,                  // 11  (continues after last explicit)
}

assert_eq!(Kind::Process.number(), 0u8);
assert_eq!(Kind::File.as_u8(), 1);
assert_eq!(Kind::from_number(10).unwrap(), Kind::Network);
assert_eq!(Kind::try_from(11u8), Ok(Kind::Socket));
assert!(Kind::Process == 0u8);
assert_eq!(Kind::VARIANTS.len(), 4);
assert_eq!(Kind::NUMBERS, &[0, 1, 10, 11]);

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::{FromNumber, Number, Numbered};

#[derive(Debug, PartialEq, Numbered)]
#[numbered(u8, start = 1)]
enum Wire {
    Open,                    // 1
    #[numbered(n = 10)]
    IoFailed,                // 10
    Closed = 20,             // 20
    Draining,                // 21
}

assert_eq!(Wire::Open.number(), 1);
assert_eq!(Wire::IoFailed.as_u8(), 10);
assert_eq!(Wire::from_number(21).unwrap(), Wire::Draining);

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:

numbered = { version = "0.2", default-features = 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.