Enum Conversion

Evo has helpers for efficiently converting between strings and enums.

• Enum string list is built at compile-time – doesn't allocate memory
• Lookups are fast – binary search is used to find the enum string in a pre-sorted list with SubStringMapList
• This is done using EVO_ENUM_MAP_PREFIXED() or EVO_ENUM_CLASS_MAP(), or a related variant
• Caution: This requires string values to be pre-sorted, and no gaps between enum values

Additionally, these helpers are useful for mapping enums to "trait" objects:

• EVO_ENUM_TRAITS(), EVO_ENUM_CLASS_TRAITS()

This example defines an enum, then uses the EVO_ENUM_MAP_PREFIXED() helper to create string mappings.

• This requires the enum to have the expected first/last guard values (UNKNOWN, ENUM_END – with a prefix where applicable) to deduce the mappings
• These enum values have a lowercase prefix to avoid collisions with other enums – referred to as a "prefixed" enum
• The enum map also has a nested Iter type for iterating through enum values

#include <evo/enum.h>
#include <evo/io.h>
using namespace evo;

enum Color {
    cUNKNOWN = 0,   // Must be first
    cBLUE,
    cGREEN,
    cRED,
    cENUM_END       // Must be last
};

EVO_ENUM_MAP_PREFIXED(Color, c,
    // Must be sorted, and must match enum values
    "blue",
    "green",
    "red"
);

int main() {
    // Enum map lookups
    Color     color_val1 = ColorEnum::get_enum("green");    // set to cGREEN
    Color     color_val2 = ColorEnum::get_enum(2);          // set to cGREEN
    SubString color_str  = ColorEnum::get_string(cGREEN);   // set to "green"
    int       color_num  = ColorEnum::get_int(cGREEN);      // set to 2

    // Iterate through enum values
    Console& c = con();
    for (ColorEnum::Iter iter; iter; ++iter)
        c.out << "num:" << iter.value_num() << ", str:" << iter.value_str() << NL;

    return 0;
}

Output (from iterator):

num:1, str:blue
num:2, str:green
num:3, str:red

Unsorted Enum Values

This example is similar but uses an enum with unsorted values, which must be "remapped" to match the sorted string values.

• This is useful when the enum values must be in a specific order that doesn't match the pre-sorted strings

#include <evo/enum.h>
using namespace evo;

enum Color {
    cUNKNOWN = 0,   // Must be first
    cRED,           // Unsorted values
    cBLUE,
    cGREEN,
    cENUM_END       // Must be last
};

static const Color COLOR_REMAP[] = {
    // Must match string order below
    cBLUE,
    cGREEN,
    cRED
};

EVO_ENUM_REMAP_PREFIXED(Color, c, COLOR_REMAP,
    // Must be sorted, and must match "remapped" enum values
    "blue",
    "green",
    "red"
);

int main() {
    Color     color_val1 = ColorEnum::get_enum("green");    // set to cGREEN
    Color     color_val2 = ColorEnum::get_enum(2);          // set to cBLUE
    SubString color_str  = ColorEnum::get_string(cGREEN);   // set to "green"
    int       color_num  = ColorEnum::get_int(cGREEN);      // set to 3
    return 0;
}

Enum Traits

This example creates traits for the above Color enum using EVO_ENUM_TRAITS():

• This requires the enum to have the expected first guard value (UNKNOWN – with prefix where applicable) to deduce the mappings
• The above enum map example and the below enum traits example may be combined on the same enum, creating ColorEnum and ColorEnumTraits helper types

#include <evo/enum.h>
#include <evo/substring.h>
using namespace evo;

enum Color {
    cUNKNOWN = 0,   // Must be first (required for traits)
    cBLUE,
    cGREEN,
    cRED,
    cENUM_END       // Must be last (not required for traits)
};

struct ColorTraits {
    int index;
    SubString code;
};

EVO_ENUM_TRAITS(Color, ColorTraits, cUNKNOWN,
    // Initialize ColorTraits for each enum value starting at cUNKNOWN, must match enum values
    { 0, "?" },
    { 1, "B" },
    { 2, "G" },
    { 3, "R" }
);

int main() {
    const ColorTraits& unknown_traits = ColorEnumTraits::get(cUNKNOWN); // index:0, code:?
    const ColorTraits& green_traits   = ColorEnumTraits::get(cGREEN);   // index:2, code:G
    return 0;
}

Enum Class (C++11)

This is simplied further with C++11 enum class and EVO_ENUM_CLASS_MAP(), as long as the enum has the expected first/last guard values (UNKNOWN, ENUM_END).

#include <evo/enum.h>
#include <evo/io.h>
using namespace evo;

enum class Color {
    UNKNOWN = 0,    // Must be first
    BLUE,
    GREEN,
    RED,
    ENUM_END        // Must be last
};

EVO_ENUM_CLASS_MAP(Color,
    // Must be sorted, and must match enum values
    "blue",
    "green",
    "red"
);

int main() {
    // Enum map lookups
    Color     color_val1 = ColorEnum::get_enum("green");        // set to Color::GREEN
    Color     color_val2 = ColorEnum::get_enum(2);              // set to Color::GREEN
    SubString color_str  = ColorEnum::get_string(Color::GREEN); // set to "green"
    int       color_num  = ColorEnum::get_int(Color::GREEN);    // set to 2

    // Iterate through enum values
    Console& c = con();
    for (ColorEnum::Iter iter; iter; ++iter)
        c.out << "num:" << iter.value_num() << ", str:" << iter.value_str() << NL;

    return 0;
}

Output (from iterator):

num:1, str:blue
num:2, str:green
num:3, str:red

Unsorted Enum Class Values (C++11)

This example is similar but uses an enum class with unsorted values, which must be "remapped" to match the sorted string values.

• This is useful when the enum values must be in a specific order that doesn't match the pre-sorted strings

#include <evo/substring.h>
using namespace evo;

enum class Color {
    UNKNOWN = 0,    // Must be first
    RED,            // Unsorted values
    BLUE,
    GREEN,
    ENUM_END        // Must be last
};

static const Color COLOR_REMAP[] = {
    // Must match string order below
    Color::BLUE,
    Color::GREEN,
    Color::RED
};

EVO_ENUM_CLASS_REMAP(Color, COLOR_REMAP,
    // Must be sorted, and must match "remapped" enum values
    "blue",
    "green",
    "red"
);

int main() {
    Color     color_val1 = ColorEnum::get_enum("green");        // set to Color::GREEN
    Color     color_val2 = ColorEnum::get_enum(2);              // set to Color::BLUE
    SubString color_str  = ColorEnum::get_string(Color::GREEN); // set to "green"
    int       color_num  = ColorEnum::get_int(Color::GREEN);    // set to 3
    return 0;
}

Enum Class Traits (C++11)

This example creates traits for the above Color enum class using EVO_ENUM_CLASS_TRAITS():

• This requires the enum class to have the expected first guard value (UNKNOWN) to deduce the mappings
• The above enum class map example and the below enum traits example may be combined on the same enum, creating ColorEnum and ColorEnumTraits helper types

#include <evo/enum.h>
#include <evo/substring.h>
using namespace evo;

enum class Color {
    UNKNOWN = 0,    // Must be first
    BLUE,
    GREEN,
    RED,
    ENUM_END        // Must be last
};

struct ColorTraits {
    int index;
    SubString code;
};

EVO_ENUM_CLASS_TRAITS(Color, ColorTraits,
    // Initialize ColorTraits for each enum value starting at UNKNOWN, must match enum values
    { 0, "?" },
    { 1, "B" },
    { 2, "G" },
    { 3, "R" }
);

int main() {
    const ColorTraits& unknown_traits = ColorEnumTraits::get(Color::UNKNOWN);   // index:0, code:?
    const ColorTraits& green_traits   = ColorEnumTraits::get(Color::GREEN);     // index:2, code:G
    return 0;
}