百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
N

num_enum

> 编程语言
开源

numenum 这些过程级宏可使原语和枚举之间的操作更加方便。此 crate 与 nostd 不兼容。将枚举转换为…

377 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

numenum 这些过程级宏可使原语和枚举之间的操作更加方便。此 crate 与 nostd 不兼容。将枚举转换为…

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 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rust

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

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