Skip to main content

numbered/
lib.rs

1//! Compile-time integer numbers for enum variants.
2//!
3//! This crate gives each variant a stable integer: a `u8` (or another chosen
4//! repr) assigned at compile time. Runtime conversion is a `match` on a
5//! literal. [`Number::number`] and [`FromNumber::from_number`] are not
6//! `const` (trait methods cannot be). In const context, use
7//! [`Variants::NUMBERS`].
8//!
9//! Downstream crates use this to drop handwritten `from_u8` / `as_u8` matches
10//! on status codes, wire tags, and similar closed integer sets.
11//!
12//! Numbers are **trait items** in this crate, not inherent methods on `E`.
13//! Import [`Number`] / [`FromNumber`] to call them, or use UFCS
14//! (`<E as Number>::number(&e)`). A user `fn number()` still compiles.
15//!
16//! # Quick start
17//!
18//! ```
19//! use numbered::{FromNumber, Number, Numbered, Variants};
20//!
21//! #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
22//! #[numbered(u8)]
23//! enum Kind {
24//!     Process,                 // 0
25//!     File,                    // 1
26//!     #[numbered(n = 10)]
27//!     Network,                 // 10
28//!     Socket,                  // 11  (continues after last explicit)
29//! }
30//!
31//! assert_eq!(Kind::Process.number(), 0u8);
32//! assert_eq!(Kind::File.as_u8(), 1);
33//! assert_eq!(Kind::from_number(10).unwrap(), Kind::Network);
34//! assert_eq!(Kind::try_from(11u8), Ok(Kind::Socket));
35//! assert!(Kind::Process == 0u8);
36//! assert_eq!(Kind::VARIANTS.len(), 4);
37//! assert_eq!(Kind::NUMBERS, &[0, 1, 10, 11]);
38//! ```
39//!
40//! Native Rust discriminants (`Process = 1`) are treated as
41//! `#[numbered(n = 1)]`. If both are present they must agree.
42//! A variant named `Error` is fine: generated `TryFrom` names
43//! [`FromNumberError`] instead of `Self::Error`.
44//!
45//! # Attributes
46//!
47//! **Container** (required): `#[numbered(<repr>, ...)]`
48//!
49//! - A repr type: `u8`, `u16`, `u32`, `u64`, `usize`, `i8`, `i16`, `i32`,
50//!   `i64`, or `isize`. First positional, or `repr = u8`.
51//! - `start = 1`: first auto-assigned number when no discriminant / `n` is
52//!   set (default `0`).
53//! - `crate = ::other::numbered`: path used in generated code when this crate
54//!   is re-exported under another name.
55//!
56//! **Variant** (optional): `#[numbered(n = 5)]`
57//!
58//! Pins that variant to an explicit integer. A native `= 5` discriminant
59//! does the same. Gaps are allowed. After an explicit number, the next auto
60//! variant is `last + 1`.
61//!
62//! ```
63//! use numbered::{FromNumber, Number, Numbered};
64//!
65//! #[derive(Debug, PartialEq, Numbered)]
66//! #[numbered(u8, start = 1)]
67//! enum Wire {
68//!     Open,                    // 1
69//!     #[numbered(n = 10)]
70//!     IoFailed,                // 10
71//!     Closed = 20,             // 20
72//!     Draining,                // 21
73//! }
74//!
75//! assert_eq!(Wire::Open.number(), 1);
76//! assert_eq!(Wire::IoFailed.as_u8(), 10);
77//! assert_eq!(Wire::from_number(21).unwrap(), Wire::Draining);
78//! ```
79//!
80//! Fielded variants keep [`Number`] and the [`Variants`] tables. Pair with
81//! cognomen `reason = "... {field}"` on the same enum; a number cannot
82//! rebuild the payload, so [`FromNumber`] is omitted.
83//!
84//! ```
85//! use numbered::{Number, Numbered, Variants};
86//!
87//! #[derive(Debug, Clone, PartialEq, Numbered)]
88//! #[numbered(u8, start = 1)]
89//! enum HostError {
90//!     Unsupported { capability: &'static str },
91//!     OpenFailed { cause: &'static str },
92//! }
93//!
94//! let e = HostError::OpenFailed { cause: "busy" };
95//! assert_eq!(e.number(), 2);
96//! assert_eq!(HostError::NUMBERS, &[1, 2]);
97//! assert_eq!(HostError::VARIANTS.len(), 2);
98//! assert_eq!(HostError::COUNT, 2);
99//! ```
100//!
101//! Violations (non-enum, empty enum, missing repr, duplicate keys, unknown
102//! keys, collisions, overflow, disagreeing discriminant) are compile errors.
103//!
104//! # Generated API
105//!
106//! For `#[numbered(u8)]` on `E`. Nothing is inherent on `E`.
107//!
108//! - [`Number`]: `number()` / `as_u8()` (`as_*` follows the repr). Takes
109//!   `&self` so fielded variants do not need `Copy`. Not `const`
110//! - [`FromNumber`]: `from_number` / `from_u8` ->
111//!   `Result<Self, FromNumberError<u8>>` (fieldless enums; a number cannot
112//!   rebuild a payload). Not `const`
113//! - [`Variants`] (non-generic enums): `E::VARIANTS`, `E::NUMBERS`, and
114//!   `E::COUNT` after `use numbered::Variants`. Trait items, so they cannot
115//!   clash with cognomen or a user `const VARIANTS`. Fielded enums keep
116//!   `NUMBERS` / `COUNT`; `VARIANTS` is `&[()]` of that length. Const use
117//!   goes through `NUMBERS`
118//! - No `Display` impl. Print the number with `e.number()`.
119//! - `From<E> for u8`, `TryFrom<u8> for E` (`TryFrom` is fieldless only)
120//! - `PartialEq<u8>` / `PartialEq<E>` both ways
121//! - `Serialize` / `Deserialize` (feature `serde`): the number, not a string.
122//!   `Deserialize` is fieldless only. Do not enable serde on both Numbered
123//!   and Cognomen for the same type (two `Serialize` impls)
124//!
125//! # Features
126//!
127//! | Feature | Default | Unlocks |
128//! |---------|---------|---------|
129//! | `std` | yes | `alloc` + [`std::error::Error`] for [`FromNumberError`] |
130//! | `alloc` | via `std` | kept for feature parity; the unmatched number is always stored |
131//! | `serde` | no | `Serialize` / `Deserialize` |
132//!
133//! # `no_std`
134//!
135//! ```toml
136//! numbered = { version = "0.2", default-features = false }
137//! ```
138//!
139//! [`Number`], [`FromNumber`], `From` / `TryFrom`, and [`Variants`] use only
140//! `core`. Add `features = ["serde"]` for wire formats.
141//!
142//! # MSRV
143//!
144//! Rust 1.71.1.
145
146#![no_std]
147#![cfg_attr(docsrs, feature(doc_cfg))]
148
149extern crate self as numbered;
150
151#[cfg(feature = "alloc")]
152extern crate alloc;
153
154#[cfg(feature = "std")]
155extern crate std;
156
157mod number;
158
159pub use number::{FromNumber, Number};
160#[doc(inline)]
161pub use numbered_macros::Numbered;
162
163/// Declaration-order tables for a non-generic numbered enum.
164///
165/// `VARIANTS`, `NUMBERS`, and `COUNT` live on this trait, not as inherent
166/// items on `E`. Cognomen's `Variants` is a different trait; import one
167/// or spell the path: `<E as numbered::Variants>::NUMBERS`.
168///
169/// Fieldless enums store `Self` in [`VARIANTS`]. Fielded enums cannot
170/// build a `'static [Self]`, so [`Variant`](Self::Variant) is `()` and
171/// `VARIANTS.len()` / [`COUNT`](Self::COUNT) still match the declaration.
172///
173/// [`NUMBERS`](Self::NUMBERS) is the const-context path:
174/// [`Number::number`] cannot be `const`.
175///
176/// ```
177/// use numbered::{Numbered, Variants};
178///
179/// #[derive(Debug, Clone, Copy, PartialEq, Numbered)]
180/// #[numbered(u8)]
181/// enum Kind {
182///     A,
183///     B,
184/// }
185///
186/// assert_eq!(Kind::VARIANTS, &[Kind::A, Kind::B]);
187/// assert_eq!(Kind::NUMBERS, &[0, 1]);
188/// assert_eq!(Kind::COUNT, 2);
189/// ```
190pub trait Variants: Sized + 'static {
191    /// Integer type chosen in `#[numbered(<repr>)]`.
192    type Repr: Copy;
193
194    /// Element type of [`VARIANTS`].
195    ///
196    /// `Self` when every variant is fieldless; `()` when any variant has
197    /// a payload (`VARIANTS` is then a length-only table).
198    type Variant: 'static;
199
200    /// All variants in declaration order, or `()` placeholders if fielded.
201    const VARIANTS: &'static [Self::Variant];
202
203    /// Assigned number for each variant in declaration order.
204    const NUMBERS: &'static [Self::Repr];
205
206    /// How many variants were declared (`NUMBERS.len()`).
207    const COUNT: usize = Self::NUMBERS.len();
208}
209
210/// Error returned when a number matches no declared variant.
211///
212/// Produced by [`TryFrom`](core::convert::TryFrom) and
213/// [`FromNumber::from_number`]. The unmatched number is stored in
214/// [`Self::number`]. With `std`, this implements [`std::error::Error`].
215///
216/// ```
217/// use numbered::{FromNumber, FromNumberError, Numbered};
218///
219/// #[derive(Debug, Numbered)]
220/// #[numbered(u8)]
221/// enum Mode {
222///     SingleProcess,
223/// }
224///
225/// let err = Mode::from_number(9).unwrap_err();
226/// assert_eq!(err.number, 9);
227/// assert!(err.to_string().contains("9"));
228/// let _: FromNumberError<u8> = err;
229/// ```
230#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
231pub struct FromNumberError<T> {
232    /// The number that did not match.
233    pub number: T,
234}
235
236impl<T> FromNumberError<T> {
237    /// Build an error for the unmatched `number`.
238    #[must_use]
239    pub const fn new(number: T) -> Self {
240        Self { number }
241    }
242}
243
244impl<T: core::fmt::Display> core::fmt::Display for FromNumberError<T> {
245    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
246        write!(f, "no numbered variant has number {}", self.number)
247    }
248}
249
250#[cfg(feature = "std")]
251#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
252impl<T: core::fmt::Debug + core::fmt::Display> std::error::Error for FromNumberError<T> {}
253
254#[cfg(feature = "serde")]
255#[doc(hidden)]
256pub use serde as __serde;
257
258#[cfg(test)]
259mod tests {
260    extern crate std;
261
262    use std::string::ToString;
263
264    use super::*;
265
266    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
267    #[numbered(u8)]
268    enum Kind {
269        Process,
270        File,
271        #[numbered(n = 10)]
272        Network,
273        Socket,
274    }
275
276    #[test]
277    fn numbers_and_tables() {
278        assert_eq!(Kind::Process.number(), 0u8);
279        assert_eq!(Kind::File.as_u8(), 1);
280        assert_eq!(Kind::from_number(10).unwrap(), Kind::Network);
281        assert_eq!(Kind::try_from(11u8), Ok(Kind::Socket));
282        assert!(Kind::Process == 0u8);
283        assert!(0u8 == Kind::Process);
284        assert_eq!(
285            Kind::VARIANTS,
286            &[Kind::Process, Kind::File, Kind::Network, Kind::Socket]
287        );
288        assert_eq!(Kind::NUMBERS, &[0, 1, 10, 11]);
289        assert_eq!(Kind::COUNT, 4);
290        assert_eq!(Kind::Process.number().to_string(), "0");
291        assert_eq!(u8::from(Kind::File), 1);
292        assert_eq!(Kind::from_u8(11).unwrap(), Kind::Socket);
293    }
294
295    #[derive(Debug, Clone, PartialEq, Eq, Numbered)]
296    #[numbered(u8, start = 1)]
297    enum HostError {
298        Unsupported { capability: &'static str },
299        OpenFailed { cause: &'static str },
300        BadRequest { why: &'static str },
301        Io { status: &'static str },
302    }
303
304    #[test]
305    fn fielded_numbers_and_tables() {
306        let e = HostError::OpenFailed { cause: "busy" };
307        assert_eq!(e.number(), 2);
308        assert_eq!(e.as_u8(), 2);
309        assert_eq!(u8::from(e.clone()), 2);
310        assert!(e == 2u8);
311        assert!(2u8 == e);
312        assert_eq!(<HostError as Variants>::NUMBERS, &[1, 2, 3, 4]);
313        assert_eq!(<HostError as Variants>::VARIANTS.len(), 4);
314        assert_eq!(HostError::COUNT, 4);
315        assert_eq!(HostError::COUNT, HostError::VARIANTS.len());
316        assert_eq!(HostError::Unsupported { capability: "x" }.number(), 1);
317        assert_eq!(
318            HostError::BadRequest {
319                why: "device name has interior NUL"
320            }
321            .number(),
322            3
323        );
324        assert_eq!(HostError::Io { status: "e" }.number(), 4);
325    }
326
327    #[test]
328    fn parse() {
329        assert_eq!(Kind::from_u8(10).unwrap(), Kind::Network);
330        assert!(Kind::from_number(99).is_err());
331        let err = Kind::from_number(99).unwrap_err();
332        assert_eq!(err.number, 99);
333        assert!(err.to_string().contains("99"));
334        #[cfg(feature = "std")]
335        {
336            let _: &dyn std::error::Error = &err;
337        }
338    }
339
340    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
341    #[numbered(i8, start = -1)]
342    enum Signed {
343        Neg,
344        Zero,
345        Pos = 5,
346        Next,
347    }
348
349    #[test]
350    fn signed_start_and_discriminant() {
351        assert_eq!(Signed::Neg.number(), -1);
352        assert_eq!(Signed::Zero.as_i8(), 0);
353        assert_eq!(Signed::Pos.number(), 5);
354        assert_eq!(Signed::Next.number(), 6);
355        assert_eq!(Signed::from_number(-1).unwrap(), Signed::Neg);
356        assert_eq!(Signed::NUMBERS, &[-1, 0, 5, 6]);
357    }
358
359    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
360    #[numbered(u8)]
361    enum Shared {
362        A,
363        B,
364    }
365
366    impl core::fmt::Display for Shared {
367        fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
368            f.write_str("user")
369        }
370    }
371
372    impl Shared {
373        pub const VARIANTS: &'static [&'static str] = &["a", "b"];
374
375        fn number(&self) -> u8 {
376            9
377        }
378
379        fn as_u8(&self) -> u8 {
380            8
381        }
382    }
383
384    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
385    #[numbered(u8, start = 1)]
386    enum Level {
387        Error,
388        Warn,
389        Info,
390        Debug,
391    }
392
393    #[test]
394    fn error_variant_try_from() {
395        assert_eq!(Level::Error.number(), 1);
396        assert_eq!(Level::try_from(1u8), Ok(Level::Error));
397        assert_eq!(Level::from_number(4).unwrap(), Level::Debug);
398        assert!(Level::from_number(0).is_err());
399        assert_eq!(Level::Error.number(), 1);
400    }
401
402    #[test]
403    fn tables_do_not_clash_with_user_items() {
404        assert_eq!(Shared::VARIANTS, &["a", "b"]);
405        assert_eq!(<Shared as Variants>::VARIANTS, &[Shared::A, Shared::B]);
406        assert_eq!(<Shared as Variants>::NUMBERS, &[0, 1]);
407        assert_eq!(Shared::A.to_string(), "user");
408        assert_eq!(Shared::A.number(), 9);
409        assert_eq!(Shared::A.as_u8(), 8);
410        assert_eq!(<Shared as Number>::number(&Shared::A), 0);
411        assert_eq!(<Shared as Number>::as_u8(&Shared::A), 0);
412    }
413
414    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
415    #[numbered(repr = u16, start = 1)]
416    enum Port {
417        Http,
418        Https = 443,
419        Alt,
420    }
421
422    #[test]
423    fn repr_key_and_start() {
424        assert_eq!(Port::Http.as_u16(), 1);
425        assert_eq!(Port::Https.number(), 443);
426        assert_eq!(Port::Alt.number(), 444);
427        assert_eq!(u16::from(Port::Http), 1);
428        assert_eq!(Port::try_from(443u16), Ok(Port::Https));
429    }
430
431    // Trait methods cannot be const. Const use goes through Variants::NUMBERS.
432    const fn kind_number_in_const() -> u8 {
433        Kind::NUMBERS[0]
434    }
435
436    #[test]
437    fn works_in_const() {
438        assert_eq!(kind_number_in_const(), 0);
439        const TABLES: &[u8] = Kind::NUMBERS;
440        assert_eq!(TABLES, &[0, 1, 10, 11]);
441    }
442
443    #[test]
444    fn from_number_error_new() {
445        let err = FromNumberError::new(7u8);
446        assert_eq!(err.number, 7);
447        assert_eq!(err, Kind::from_number(7).unwrap_err());
448        assert_eq!(err.to_string(), "no numbered variant has number 7");
449    }
450
451    #[test]
452    fn partial_eq_mismatch() {
453        assert!(Kind::Process != 1u8);
454        assert!(1u8 != Kind::Process);
455        assert!(Kind::File != 99u8);
456        assert!(Kind::Network == 10u8);
457    }
458
459    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
460    #[numbered(u8)]
461    enum Literals {
462        Hex = 0x10,
463        #[numbered(n = 0x20)]
464        AlsoHex,
465        Next,
466        #[numbered(n = 5)]
467        Agree = 5,
468        Paren = (7),
469    }
470
471    #[test]
472    fn hex_paren_and_agreeing_discriminant() {
473        assert_eq!(Literals::Hex.number(), 16);
474        assert_eq!(Literals::AlsoHex.number(), 32);
475        assert_eq!(Literals::Next.number(), 33);
476        assert_eq!(Literals::Agree.number(), 5);
477        assert_eq!(Literals::Paren.number(), 7);
478        assert_eq!(Literals::from_number(16).unwrap(), Literals::Hex);
479        assert_eq!(Literals::NUMBERS, &[16, 32, 33, 5, 7]);
480    }
481
482    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
483    #[numbered(i8, start = -128)]
484    enum I8Min {
485        Lo,
486        Next,
487    }
488
489    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
490    #[numbered(u32)]
491    enum Wide {
492        A,
493        B = 1_000,
494        C,
495    }
496
497    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
498    #[numbered(usize)]
499    enum UsizeKind {
500        A,
501        B,
502    }
503
504    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
505    #[numbered(isize)]
506    enum IsizeKind {
507        A = -1,
508        B,
509    }
510
511    #[test]
512    fn other_reprs() {
513        assert_eq!(I8Min::Lo.as_i8(), -128);
514        assert_eq!(I8Min::Next.number(), -127);
515        assert_eq!(Wide::B.as_u32(), 1_000);
516        assert_eq!(Wide::C.number(), 1_001);
517        assert_eq!(UsizeKind::B.as_usize(), 1);
518        assert_eq!(IsizeKind::A.as_isize(), -1);
519        assert_eq!(IsizeKind::B.number(), 0);
520        assert_eq!(u32::from(Wide::A), 0);
521        assert_eq!(Wide::try_from(1_000u32), Ok(Wide::B));
522    }
523
524    #[derive(Debug, Clone, Copy, PartialEq, Eq, Numbered)]
525    #[numbered(u8)]
526    enum Generic<const N: usize> {
527        A,
528        B,
529    }
530
531    #[test]
532    fn generic_has_numbers_not_tables() {
533        assert_eq!(Generic::<3>::A.number(), 0);
534        assert_eq!(Generic::<3>::from_number(1).unwrap(), Generic::<3>::B);
535        assert_eq!(u8::from(Generic::<1>::A), 0);
536    }
537
538    impl Shared {
539        pub const NUMBERS: &'static [&'static str] = &["zero", "one"];
540    }
541
542    #[test]
543    fn user_numbers_do_not_hide_trait_numbers() {
544        assert_eq!(Shared::NUMBERS, &["zero", "one"]);
545        assert_eq!(<Shared as Variants>::NUMBERS, &[0, 1]);
546    }
547
548    #[test]
549    fn signed_from_and_eq() {
550        assert_eq!(i8::from(Signed::Neg), -1);
551        assert_eq!(Signed::from_i8(5).unwrap(), Signed::Pos);
552        assert!(Signed::Neg == -1i8);
553        assert!(-1i8 == Signed::Neg);
554        assert!(Signed::Pos != 0i8);
555    }
556
557    #[cfg(feature = "serde")]
558    #[test]
559    fn serde_roundtrip() {
560        let v = Kind::Network;
561        let s = serde_json::to_string(&v).unwrap();
562        assert_eq!(s, "10");
563        let back: Kind = serde_json::from_str(&s).unwrap();
564        assert_eq!(back, v);
565        assert!(serde_json::from_str::<Kind>("99").is_err());
566        let process: Kind = serde_json::from_str("0").unwrap();
567        assert_eq!(process, Kind::Process);
568        let generic = Generic::<3>::B;
569        let gs = serde_json::to_string(&generic).unwrap();
570        assert_eq!(gs, "1");
571        let gback: Generic<3> = serde_json::from_str(&gs).unwrap();
572        assert_eq!(gback, generic);
573    }
574}