better-enums/doc/OptInFeatures.md

## Opt-in features

Better Enums has a few opt-in features that affect how enums are generated. The
default configuration is suitable for general use, but you might have more
stringent requirements. This page describes the optional features and how to
enable them.

### Strict conversions

Each Better Enum is implicitly convertible to its member `enum _enumerated`
type. This is meant to support usage of Better Enums directly in `switch`
statements. When you write

    switch (channel) {
        ...
    }

the compiler applies the implicit conversion, and is also able to do case
exhaustiveness checking. Unfortunately, `_enumerated` is always a regular $cxx98
enum type, meaning that it has standard conversions to integral types. The end
result is `channel` is implicitly convertible all the way to `int` —
behavior that is often considered a violation of type safety.

In $cxx11, you can force Better Enums to declare an internal `enum class` type
to use for `switch` statements. Each enum will then be only convertible to its
`enum class`, and won't be implicitly convertible to integers. This is done by
defining `BETTER_ENUMS_STRICT_CONVERSION` before including `enum.h`. You would
typically do this on the compiler's command line.

The reason strict conversions aren't enabled by default in $cxx11 is that doing
so would break compatibility with the $cxx98 interface.

  - The "weaker" incompatibility is that you could write a bunch of $cxx98 code
    that relies on implicit integer conversions, and then try to switch to
    $cxx11. The code would then fail to compile. An example where implicit
    conversions are an "advantage" is when using Better Enums as arguments to
    the methods of `std::bitset`. I could have ignored this problem by declaring
    usage of implicit integer conversions unsupported, but in light of the next
    issue, I decided not to do that.
  - The "stronger" incompatibility is a difference in how `switch` cases must be
    written. The syntaxes for the two variants, implicitly-converting and
    strict, are mutually exclusive.

Here they are:

    // Default variant
    switch (channel) {
        case Channel::Red:   break;
        case Channel::Green: break;
        case Channel::Blue:  break;
    }

    // Strict variant
    switch (channel) {
        case +Channel::Red:   break;
        case +Channel::Green: break;
        case +Channel::Blue:  break;
    }

I would be very happy to make conversion to `enum class` the default whenever
`enum class` is available, but how to do so without breaking compatibility is so
far an open problem.

### Compile-time name trimming

Better Enums is able to do all of its work at compile time. There is one task,
however, at which my current method is pretty slow on modern compilers. The
performance is still reasonable, but it makes enums take about four times longer
to compile, compared to deferring the task to program startup. The task is
trimming stringized constant names.

The problem arises when the preprocessor stringizes an initializer. For example,

    ENUM(Channel, int, Red = 1, Green, Blue);

results in an internal array, somewhere inside the generated Better Enum, that
looks like

    names = {"Red = 1", "Green", "Blue"}

Before the name of `Channel::Red` can be returned to the user, the initializer
` = 1` must be trimmed off. This is the part that is slow to compile, and is
deferred to startup by default.

If you want to enable it at compile time, you have two options. The first is to
use an alternative `SLOW_ENUM` macro to declare your enum. It will enable
compile-time trimming for that enum only. If you only do this for a few enums,
you probably won't notice the difference in compilation time.

You can also enable compile-time trimming globally for all enums by defining
`BETTER_ENUMS_CONSTEXPR_TO_STRING` before including `enum.h`. Typically, you
would do this by supplying a command-line argument to your compiler.

The result of doing either one is that `_to_string` and `_names` will become
`constexpr` for your compile-time enjoyment.

The reason this option is not enabled by default when avaialble, besides the
fact that the current implementation is slow, is that I don't believe most users
need it most of the time.

As a note, the performance is not *that* bad. You still have to define on the
order of 10+ slow enums in order to slow compilation down as much as merely
including `iostream` does. However, it is shockingly slower than the faster
implementation, where you have the leeway to define 40+ enums before you reach
the same level of slowdown as `iostream` gives you.

There are enough other problems with slow enums, however, like potential symbol
pollution in the final binaries, that I decided to leave them as an opt-in
feature until they improve to the point where they can be the default.