Enum Extension Library
This Rust crate provides procedural
and attribute
macros that enhance Rust enums with additional methods and
conversions. It simplifies working with enums by automatically generating utility methods for common tasks such as
retrieving a list of variants, counting variants, and converting between discriminants and integer types.
See the enum_ext!
and #[enum_extend]
macro examples below for more information.
Both macros generate the same utility methods, so you can choose the one that best fits your coding style.
Utility Functions
Core Functions
list()
: Returns an array containing all variants of the enum.count()
: Returns the number of variants in the enum.ordinal()
: Returns the ordinal (index) of a variant.from_ordinal(ordinal: usize)
: Returns the variant corresponding to the given ordinal.ref_from_ordinal(ordinal: usize)
: Returns a reference to the variant corresponding to the given ordinal.valid_ordinal(ordinal: usize)
: Checks if the given ordinal is valid for the enum.iter()
: Returns an iterator over all the variants of the enum.pretty_print()
: Returns a formatted string displaying the enum and all its variants in a pretty-print format.
String Conversion Functions
pascal_spaced(&self)
: Converts the variant name to spaced PascalCase. For instance,InQA
becomes"In QA"
.from_pascal_spaced(name: &str)
: Returns the variant corresponding to the spaced PascalCase name. For example,"In QA"
becomesInQA
.snake_case(&self)
: Converts the variant name to snake_case. For instance,InQA
becomes"in_qa"
.from_snake_case(name: &str)
: Returns the variant corresponding to the snake_case name. For example,"in_qa"
becomesInQA
.kebab_case(&self)
: Converts the variant name to kebab-case. For instance,InQA
becomes"in-qa"
.from_kebab_case(name: &str)
: Returns the variant corresponding to the kebab-case name. For example,"in-qa"
becomesInQA
.
Navigation Functions
next(&self)
: Returns the next variant in ordinal order (wraps around to first when at last).previous(&self)
: Returns the previous variant in ordinal order (wraps around to last when at first).next_linear(&self)
: Returns the next variant without wrapping (returnsNone
at end).previous_linear(&self)
: Returns the previous variant without wrapping (returnsNone
at start).
Validation Functions
is_first(&self)
: Returnstrue
if this is the first variant (ordinal 0).is_last(&self)
: Returnstrue
if this is the last variant.comes_before(&self, other: &Self)
: Returnstrue
if this variant comes before the other in ordinal order.comes_after(&self, other: &Self)
: Returnstrue
if this variant comes after the other in ordinal order.
Filtering Functions
variants_containing(substring: &str)
: Returns variants whose names contain the substring.variants_starting_with(prefix: &str)
: Returns variants whose names start with the prefix.variants_ending_with(suffix: &str)
: Returns variants whose names end with the suffix.
Batch Operations
slice(start: usize, end: usize)
: Returns a slice of variants from start to end ordinal.range(range: std::ops::Range<usize>)
: Returns variants in the specified ordinal range.first_n(n: usize)
: Returns the first N variants.last_n(n: usize)
: Returns the last N variants.
Metadata Functions
variant_name(&self)
: Returns the variant name as a string.variant_names()
: Returns all variant names as a vector of strings.
Random Selection (Optional Feature)
random()
: Returns a random variant (requires"random"
feature).random_with_rng<R: Rng>(rng: &mut R)
: Returns a random variant using provided RNG (requires"random"
feature).
Integer Conversion Functions (When IntType is specified)
from_<IntType>(value: <IntType>)
andas_<IntType>(&self)
: Convert to and from the specified integer type, if defined in the attributes.- For example,
from_i32(10)
andas_i32()
ifIntType = "i32"
, orfrom_u32(10)
andas_u32()
ifIntType = "u32"
, etc.
- For example,
See examples in the repository for more information.
Attributes
Attributes are optional and used to customize the generated methods.
IntType
is currently the only attribute supported and specifies the discriminant type for conversion methods. The generated methods allow conversion from this type to an enum variant and vice versa. Supported types include standard Rust integer types likei32
,u32
,i64
, etc. If this attribute is not specified,usize
is used as the default.- Note: If the enum has discriminant values,
#[derive(Clone)]
is added to the enum (if not already present).
- Note: If the enum has discriminant values,
Features
This crate supports optional features that can be enabled in your Cargo.toml
:
random
- Enables random variant selection functionality (random()
andrandom_with_rng()
methods). Add this to yourCargo.toml
:[] = "0.9.1" = { = "0.4.1", = ["random"] }
Assigning attributes vary slightly depending on the macro used.
When using enum_extend
, the attribute is applied directly in the tag:
use enum_extend;
// example with no attribute
// example with an attribute
// <- `IntType` is the discriminant type for conversion methods
When using enum_ext!
, the attribute is applied in an enum_def
parameter to the macro:
use enum_ext;
enum_ext!;
Usage
Using the #[enum_extend]
Attribute Macro
To use the enum_extend attribute macro, simply include it in your Rust project and apply it to your enum definitions. Here's an example:
Using the enum_ext!
Procedural Macro
To use the enum_ext!
macro, simply include it in your Rust project and apply it to your enum definitions. Here's an
example:
Additional utility methods are generated for the enum variants:
use enum_extend;
Getting Started
Add the following to your Cargo.toml file:
[]
= "0.4.1"