Macro stringy::stringy

macro_rules! stringy {
    (
        $($(#[$top:meta])+)?
        $name:ident
        =
        $(
            $($(#[$com:meta])+)?
            $label:ident $lit:literal $(| $alt:literal)*
        )+
    ) => { ... };
    (#$t:tt) => { ... };
    (#$a:tt $($bs:tt)+) => { ... };
}

! This library holds macros which can be used to generate enums as labels ! for fixed instances of lazily allocated literal data. ! Generates byte-sized enums corresponding to a set of string literals.

The variants are all fieldless variants, but they each can generate one of the aforementioned set of string literals – in particular, each variant dereferences to an instance of the string literal provided when calling this macro, thus each enum generated by this macro implements std::ops::Deref<&str>.

Additionally, every generated enum implements Ord, with the total order defined in terms of the order in which each variant was defined, i.e., strictly based on the order they appear in the macro call.

This effectively allows for unification of &str values with usize values via a single 1 byte long interface, as the inherent method as_usize returns the usize value corresponding to the position of a given variant within this total order.

The provided literal values are additionally automatically recorded in doc comments for each enum variant, as well as within relevant methods.

Example

// Let's define some names for colors
stringy! { Color =
    Red     "red"
    Green   "green"
    Blue    "blue"
}

// Now we can test any strings to see if they match a color name
let not_a_color_name = "boop";
let red = "red";
assert_eq!(Color::test_str(not_a_color_name), false);
assert_eq!(Color::from_str(not_a_color_name), None);
assert_eq!(Color::test_str(red), true);
assert_eq!(Color::from_str(red), Some(Color::Red));

// Each variant is associated with a `usize` value indicating its order
// relative to the other variants
let idx_red = Color::Red.as_usize();
let idx_blue = Color::Blue.as_usize();
assert_eq!(idx_red, 0);
assert_eq!(idx_blue, 2);

// We can also generate a fixed-size array of all of the possibiities,
// ordered as defined.
let rgb = Color::VARIANTS;
assert_eq!(rgb, [Color::Red, Color::Green, Color::Blue]);