#num #enum #derive #macros #internal

macro num_enum_derive

Internal implementation details for ::num_enum (Procedural macros to make inter-operation between primitives and enums easier)

6 releases

✓ Uses Rust 2018 edition

0.5.0 May 9, 2020
0.4.3 Mar 17, 2020
0.4.2 Oct 4, 2019
0.4.1 Aug 12, 2019
0.0.0 Aug 9, 2019

#641 in Rust patterns

Download history 8477/week @ 2020-03-16 6868/week @ 2020-03-23 7747/week @ 2020-03-30 7462/week @ 2020-04-06 8162/week @ 2020-04-13 7054/week @ 2020-04-20 9336/week @ 2020-04-27 8506/week @ 2020-05-04 13302/week @ 2020-05-11 13592/week @ 2020-05-18 14720/week @ 2020-05-25 13777/week @ 2020-06-01 15069/week @ 2020-06-08 15663/week @ 2020-06-15 15361/week @ 2020-06-22 14492/week @ 2020-06-29

33,356 downloads per month
Used in 162 crates (2 directly)

BSD-3-Clause

12KB
207 lines

num_enum

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

crates.io Documentation Build Status

Turning an enum into a primitive

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

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`",
    );
}

Unsafely turning a primitive into an enum with from_unchecked

If you're really certain a conversion will succeed, 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.

use num_enum::UnsafeFromPrimitive;

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

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

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

Optional features

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

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.

Dependencies

~390–800KB
~19K SLoC