strum

To use Strum, add it to your Cargo.toml. You can either import strum and strum_macros separately, or use the derive feature on the strum crate to import the macros directly from strum.

[dependencies]
strum = "0.28"
strum_macros = "0.28"

# Alternatively, use the derive feature to import macros directly from strum:
# strum = { version = "0.28", features = ["derive"] }

If you need to inspect the code generated by Strum macros, you can use the STRUM_DEBUG environment variable during compilation.

• Set STRUM_DEBUG=1 to dump all generated code for every type.
• Set STRUM_DEBUG=YourType to dump only the code generated for a specific type named YourType.

You can control the generation of the discriminant enum using the #[strum_discriminants(...)] attribute on your main enum. This allows you to override default naming, visibility, and pass through specific attributes to the generated variants.

Supported Configuration Options:

• name = "...": Sets the name of the generated discriminant enum.
• vis = "...": Sets the visibility of the generated enum (e.g., pub, pub(crate)).
• #[strum_discriminants(attribute)]: You can use this to proxy specific attributes to the generated variants. The attribute inside the parentheses must be a group (e.g., #[strum_discriminants(#[cfg(feature = "foo")])]).

The EnumIs macro automatically generates boolean check methods for each variant of an enum. For a variant named MyVariant, the macro generates a method named is_my_variant(). These methods are const, inline, and marked with #[must_use]. They return true if the enum instance matches that specific variant, and false otherwise.

Note: If a variant has its disabled property set (via Strum attributes), the corresponding is_* method will not be generated for that variant.

The AsRefStr derive macro implements AsRef<str> for your enum. This allows you to get a string slice of the variant name (or a custom serialized name) without allocating a new String.

Customization:

• Prefix/Suffix: Use #[strum(prefix = "...")] or #[strum(suffix = "...")] on the enum to apply a string to all variants.
• Custom Name: Use #[strum(serialize = "...")] on a specific variant to change its string representation.

use std::convert::AsRef;
use strum_macros::AsRefStr;

#[derive(AsRefStr, Debug)]
#[strum(prefix = "/")]
enum ColorWithPrefix {
    #[strum(serialize = "redred")]
    Red,
    Green,
}

assert_eq!("/redred", ColorWithPrefix::Red.as_ref());
assert_eq!("/Green", ColorWithPrefix::Green.as_ref());

The Display derive macro implements std::fmt::Display for your enum. It determines the string representation based on these rules:

1. Use the to_string property if present (only one allowed per variant).
2. Use the longest serialize property if no to_string is present.
3. Use the variant name if no attributes are present.
4. Prepend strum(prefix = "...") or append strum(suffix = "...") if defined on the enum.
5. Supports string interpolation for variants with fields.

use std::string::ToString;
use strum_macros::Display;

#[derive(Display, Debug)]
enum Color {
    #[strum(serialize = "redred")]
    Red,
    Green,
    Yellow,
    #[strum(to_string = "purple with {sat} saturation")]
    Purple { sat: usize },
}

let purple = Color::Purple { sat: 10 };
assert_eq!(String::from("purple with 10 saturation"), purple.to_string());

The EnumIter derive macro implements strum::IntoEnumIterator for your enum. This allows you to iterate over all variants using YourEnum::iter().

Note: For variants containing data, the iterator will use Default::default() to populate the fields. You cannot derive EnumIter on enums with lifetime bounds (e.g., MyEnum<'a>).

use strum::IntoEnumIterator;
use strum_macros::EnumIter;

#[derive(EnumIter, Debug, PartialEq)]
enum Color {
    Red,
    Green { range: usize },
    Blue(usize),
    Yellow,
}

for color in Color::iter() {
    println!("My favorite color is {:?}", color);
}

The EnumIs derive macro generates helper methods for each variant to check if an enum instance matches that variant (e.g., my_enum.is_red()).

use strum_macros::EnumIs;

#[derive(EnumIs, Debug)]
enum Color {
    Red,
    Green { range: usize },
}

let color = Color::Red;
assert!(color.is_red());

The IntoStaticStr derive macro implements From<YourEnum> and From<&'a YourEnum> for &'static str. This is useful for converting an enum variant into a static string slice, especially when the enum has lifetime bounds.

use strum_macros::IntoStaticStr;

#[derive(IntoStaticStr)]
enum State<'a> {
    Initial(&'a str),
    Finished,
}

fn verify_state<'a>(s: &'a str) {
    let state = State::Initial(s);
    let right: &'static str = state.into();
    assert_eq!("Initial", right);
}