Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
N

num_enum

> 编程语言
Open source

numenum Procedural macros to make inter-operation between primitives and enums easier. This crate is nostd compatible. Turning an enum into…

377 stars0 likes0 views
WebsiteGitHub

About

numenum Procedural macros to make inter-operation between primitives and enums easier. This crate is nostd compatible. Turning an enum into…

num_enum

Procedural macros to make inter-operation between primitives and enums easier. This crate is no_std compatible.

Turning an enum into a primitive

rust
use num_enum::IntoPrimitive;

#[derive(IntoPrimitive)]
#[repr(u8)]
enum Number {
    Zero,
    One,
}

fn main() {
    let zero: u8 = Number::Zero.into();
    assert_eq!(zero, 0u8);
}

num_enum's IntoPrimitive is more type-safe than using as, because as will silently truncate - num_enum only derives From for exactly the discriminant type of the enum.

Attempting to turn a primitive into an enum with try_from

rust
use num_enum::TryFromPrimitive;
use std::convert::TryFrom;

#[derive(Debug, Eq, PartialEq, TryFromPrimitive)]
#[repr(u8)]
enum Number {
    Zero,
    One,
}

fn main() {
    let zero = Number::try_from(0u8);
    assert_eq!(zero, Ok(Number::Zero));

    let three = Number::try_from(3u8);
    assert_eq!(
        three.unwrap_err().to_string(),
        "No discriminant in enum `Number` matches the value `3`",
    );
}

Variant alternatives

Sometimes a single enum variant might be representable by multiple numeric values.

The #[num_enum(alternatives = [..])] attribute allows you to define additional value alternatives for individual variants.

(The behavior of IntoPrimitive is unaffected by this attribute, it will always return the canonical value.)

…

Range expressions are also supported for alternatives, but this requires enabling the complex-expressions feature:

rust
use num_enum::TryFromPrimitive;
use std::convert::TryFrom;

#[derive(Debug, Eq, PartialEq, TryFromPrimitive)]
#[repr(u8)]
enum Number {
    Zero = 0,
    #[num_enum(alternatives = [2..16])]
    Some = 1,
    #[num_enum(alternatives = [17, 18..=255])]
    Many = 16,
}

fn main() {
    let zero = Number::try_from(0u8);
    assert_eq!(zero, Ok(Number::Zero));

    let some = Number::try_from(15u8);
    assert_eq!(some, Ok(Number::Some));

    let many = Number::try_from(255u8);
    assert_eq!(many, Ok(Number::Many));
}

Custom error types

TryFromPrimitive by default will use num_enum::TryFromPrimitiveError as its Error type.

If you want to use a different type, you can use an annotation for this:

rust
use num_enum::TryFromPrimitive;

#[derive(Debug, Eq, PartialEq, TryFromPrimitive)]
#[num_enum(error_type(name = CustomError, constructor = CustomError::new))]
#[repr(u8)]
enum FirstNumber {
    Zero,
    One,
    Two,
}

struct CustomError {}

impl CustomError {
    fn new(value: u8) -> CustomError {
        CustomError {}
    }
}

Safely turning a primitive into an exhaustive enum with from_primitive

If your enum has all possible primitive values covered, you can derive FromPrimitive for it (which auto-implement stdlib's From):

You can cover all possible values by:

  • Having variants for every possible value
  • Having a variant marked #[num_enum(default)]
  • Having a variant marked #[num_enum(catch_all)]
  • Having #[num_enum(alternatives = [...])s covering values not covered by a variant.
rust
use num_enum::FromPrimitive;

#[derive(Debug, Eq, PartialEq, FromPrimitive)]
#[repr(u8)]
enum Number {
    Zero,
    #[num_enum(default)]
    NonZero,
}

fn main() {
    assert_eq!(
        Number::Zero,
        Number::from(0_u8),
    );
    assert_eq!(
        Number::NonZero,
        Number::from(1_u8),
    );
}

Default variant

Sometimes it is desirable to have an Other variant in an enum that acts as a kind of a wildcard matching all the value not yet covered by other variants.

The #[num_enum(default)] attribute (or the stdlib #[default] attribute) allows you to mark variant as the default.

(The behavior of IntoPrimitive is unaffected by this attribute, it will always return the canonical value.)

rust
use num_enum::FromPrimitive;
use std::convert::TryFrom;

#[derive(Debug, Eq, PartialEq, FromPrimitive)]
#[repr(u8)]
enum Number {
    Zero = 0,
    #[num_enum(default)]
    NonZero = 1,
}

fn main() {
    let zero = Number::from(0u8);
    assert_eq!(zero, Number::Zero);

    let one = Number::from(1u8);
    assert_eq!(one, Number::NonZero);

    let two = Number::from(2u8);
    assert_eq!(two, Number::NonZero);
}

Only FromPrimitive pays attention to default attributes, TryFromPrimitive ignores them.

Catch-all variant

Sometimes it is desirable to have an Other variant which holds the otherwise un-matched value as a field.

The #[num_enum(catch_all)] attribute allows you to mark at most one variant for this purpose. The variant it's applied to must be a tuple variant with exactly one field matching the repr type.

rust
use num_enum::FromPrimitive;
use std::convert::TryFrom;

#[derive(Debug, Eq, PartialEq, FromPrimitive)]
#[repr(u8)]
enum Number {
    Zero = 0,
    #[num_enum(catch_all)]
    NonZero(u8),
}

fn main() {
    let zero = Number::from(0u8);
    assert_eq!(zero, Number::Zero);

    let one = Number::from(1u8);
    assert_eq!(one, Number::NonZero(1_u8));

    let two = Number::from(2u8);
    assert_eq!(two, Number::NonZero(2_u8));
}

As this is naturally exhaustive, this is only supported for FromPrimitive, not also TryFromPrimitive.

Unsafely turning a primitive into an enum with unchecked_transmute_from

If you're really certain a conversion will succeed (and have not made use of #[num_enum(default)] or #[num_enum(alternatives = [..])] for any of its variants), and want to avoid a small amount of overhead, you can use unsafe code to do this conversion. Unless you have data showing that the match statement generated in the try_from above is a bottleneck for you, you should avoid doing this, as the unsafe code has potential to cause serious memory issues in your program.

rust
use num_enum::UnsafeFromPrimitive;

#[derive(Debug, Eq, PartialEq, UnsafeFromPrimitive)]
#[repr(u8)]
enum Number {
    Zero,
    One,
}

fn main() {
    assert_eq!(
        unsafe { Number::unchecked_transmute_from(0_u8) },
        Number::Zero,
    );
    assert_eq!(
        unsafe { Number::unchecked_transmute_from(1_u8) },
        Number::One,
    );
}

unsafe fn undefined_behavior() {
    let _ = Number::unchecked_transmute_from(2); // 2 is not a valid discriminant!
}

Note that this derive ignores any default, catch_all, and alternatives attributes on the enum. If you need support for conversions from these values, you should use TryFromPrimitive or FromPrimitive.

This means, for instance, that the following is undefined behaviour:

use num_enum::UnsafeFromPrimitive;

#[derive(UnsafeFromPrimitive)]
#[repr(u8)]
enum Number {
    Zero = 0,

    // Same for `#[num_enum(catch_all)]`, and `#[num_enum(alternatives = [2, ...])]`
    #[num_enum(default)]
    One = 1,
}
let _undefined_behavior = unsafe { Number::unchecked_transmute_from(2) };

Optional features

Some enum values may be composed of complex expressions, for example:

rust
enum Number {
    Zero = (0, 1).0,
    One = (0, 1).1,
}

To cut down on compile time, these are not supported by default, but if you enable the complex-expressions feature of your dependency on num_enum, these should start working.

License

num_enum may be used under your choice of the BSD 3-clause, Apache 2, or MIT license.

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rust

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言