#enums #newtype #macro

no-std newtype-enum

Traits to convert between enums and their variant types

1 unstable release

0.1.0 May 11, 2020

#2099 in Rust patterns

MIT/Apache

24KB
108 lines

Crates.io API Documentation Workflow Status

newtype-enum

Traits and macro to use newtype enums and convert between enums and their variants.

A newtype enum is an enum where every variant wraps another type and the wrapped type can uniquely identify the variant.

You can use the newtype_enum attribute macro to define a newtype enum. When the macro is applied to an enum E it will implement the Enum trait for E and the Variant<E> trait for all variant types.

See the examples in the Enum trait for usage of the available methods.

The macro will also convert all unit and struct variants to generated structs and replace the enum variant with a newtype variant that contains the generated struct. See below for the rules and options that are available.

Variant transformation

The variants of the enum will be converted in the following way:

Unit variants

#[newtype_enum]
enum Test {
    Example,
}
enum Test {
    Example(Test_variants::Example),
}

mod Test_variants {
    pub(super) struct Example;
}

Newtype variants

#[newtype_enum]
enum Test {
    Example(usize),
}
enum Test {
    Example(usize),
}

Struct variants

#[newtype_enum]
enum Test {
    Example { test: usize },
}
enum Test {
    Example(Test_variants::Example),
}

mod Test_variants {
    pub(super) struct Example {
        pub(super) test: usize,
    }
}

Attribute arguments

You can pass the following arguments to the newtype_enum macro:

Variants module name

#[newtype_enum(variants = "test")]
enum Test {
    Example,
}
enum Test {
    Example(test::Example),
}

mod test {
    // <-- the name of the generated module
    pub(super) struct Example;
}

Variants module visibility

#[newtype_enum(variants = "pub(crate) test")]
enum Test {
    Example,
}
enum Test {
    Example(test::Example),
}

pub(crate) mod test {
    // <-- the visibility of the generated module
    pub(super) struct Example;
}

Visibilities and attributes (e.g. #[derive] attributes)

The visibility of the generated variant structs behaves as if they where part of a normal enum: All variants and their fields have the same visibiltiy scope as the enum itself.

Attributes will be passed to the following locations:

Location Destination
enum Enum and generated variant structs
enum variant Generated variant struct
variant field Generated struct field
#[newtype_enum]
#[derive(Debug)]
pub(crate) enum Test {
    #[derive(Clone)]
    Example {
        test: usize,
        pub(super) test_super: usize,
        pub(self) test_self: usize,
    },
}
#[derive(Debug)]
pub(crate) enum Test {
    Example(Test_variants::Example),
}

pub(crate) mod Test_variants {
    #[derive(Debug, Clone)]
    pub(crate) struct Example {
        pub(crate) test: usize,
        pub(in super::super) test_super: usize,
        pub(super) test_self: usize,
    }
}

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~1.3–1.7MB
~41K SLoC