better-enums/doc/demo/102-any-underlying.md

## Non-integral underlying types

The underlying type of a Better Enum doesn't have to be an integral type. It can
be any literal type `T`, as long as you provide a `constexpr` two-way mapping
between `T` and an integral type of your choosing. This also works in $cxx98
— though then, of course, `T` doesn't have to be literal and the mapping
doesn't have to be `constexpr`. In $cxx98, everything involving `T` will simply
be done by Better Enums at run time.

This feature is semi-experimental. I am considering relaxing the requirements on
`T` so that it doesn't have to be literal. I can use a `reinterpret_cast` to
make a mapping automatically. This will make non-integral underlying types
easier to use, but will also prevent usage at compile time, which unfortunately
has structural consequences for the implementation of Better Enums, and
additional semantic consequences for usage, even at run time.

In the meantime, here's how to have a non-integral underlying type in the
current version.

    #include <iostream>
    #include <enum.h>
    typedef unsigned char uint8_t;      // <cstdint> not in C++98.



    // The underlying type. A color triplet.
    <em>struct html_color {
        uint8_t     r, g, b;

        constexpr html_color(uint8_t _r, uint8_t _g, uint8_t _b) :
            r(_r), g(_g), b(_b) { }
    };</em>

    // The mapping. It just stuffs bits to get the same effect as
    // reinterpret_cast, except reinterpret_cast is not available in constexpr
    // functions, so we have to write the bit manipulations out. On modern
    // C++11 compilers, you don't have to enter the better_enums namespace like
    // this - you can just do
    // struct ::better_enums::integral_mapping<html_color> { ...
    namespace better_enums {

    <em>template <>
    struct integral_mapping<html_color> {
        using integral_representation = unsigned int;

        constexpr static html_color from_integral(unsigned int i)
            { return html_color(i >> 16 & 0xff, i >> 8 & 0xff, i & 0xff); }

        constexpr static unsigned int to_integral(html_color c)
            { return (unsigned int)c.r << 16 | (unsigned int)c.g << 8 | c.b; }
    };</em>

    }



    // The enum itself.
    <em>ENUM(Color, html_color,
         darksalmon = 0xc47451, purplemimosa = 0x9e7bff, slimegreen = 0xbce954)</em>

Now, we can do:

    int main()
    {
        <em>Color   color = Color::darksalmon</em>;

        std::cout << std::hex;
        std::cout << "Red component: "   << <em>(int)color->r</em> << std::endl;
        std::cout << "Green component: " << <em>(int)color->g</em> << std::endl;
        std::cout << "Blue component: "  << <em>(int)color->b</em> << std::endl;

        std::cout << <em>color._to_string()</em> << std::endl;

        <em>switch (color)</em> {
            <em>case Color::darksalmon</em>:   return 0;
            <em>case Color::purplemimosa</em>: return 1;
            <em>case Color::slimegreen</em>:   return 2;
        }

        return 0;
    }

This prints each component, the name of the color (`"darksalmon"`), and then
exits from the `switch` with status 0.

### Constructors in initializers

The above declaration used only numbers in initializers, but it is actually
possible to use constructors of `html_color`. We have to add a `constexpr`
converting operator directly to `html_color`, however:

~~~comment
struct better_html_color {
    uint8_t     r, g, b;

    constexpr better_html_color(uint8_t _r, uint8_t _g, uint8_t _b) :
        r(_r), g(_g), b(_b) { }

    <em>// This is new:
    constexpr operator unsigned int() const
        { return (unsigned int)r << 16 | (unsigned int)g << 8 | b; }</em>
};

namespace better_enums {

template <>
struct integral_mapping<better_html_color> {
    using integral_representation = unsigned int;

    constexpr static better_html_color from_integral(unsigned int i)
    {
        return better_html_color(i >> 16 & 0xff, i >> 8 & 0xff, i & 0xff);
    }

    constexpr static unsigned int to_integral(better_html_color c)
        { return (unsigned int)c.r << 16 | (unsigned int)c.g << 8 | c.b; }
};

}
~~~

This allows:

~~~comment
ENUM(BetterColor, better_html_color,
     darksalmon = 0xc47451, purplemimosa = 0x9e7bff, slimegreen = 0xbce954,
     <em>celeste = better_html_color(0x50, 0xeb, 0xec)</em>)
~~~

If you can't edit your literal type to add this converting operator, or don't
want to for type safety reasons, you can achieve a similar effect by declaring
an intermediate type `U` that `html_color` can convert to, that can convert to
the integral type. Then, cast your constructor call to `U`. The type `U` is for
declarations only.

Constructors in initializers require $cxx11. Also, g++ doesn't support this
before 5.1.

### Letting the compiler enumerate your type

Of course, as long as the values are valid, you can let the compiler enumerate
your type as in a regular enum, by omitting initializers:

~~~comment
<em>ENUM(FD, file_descriptor, STDIN, STDOUT, STDERR, SomePipeYourDaemonHas, ...)</em>
~~~

Here, `FD::STDIN` maps to the integral representation 0, `STDOUT` to 1, and so
on.

### Discussion

This feature is still semi-experimental, though I expect it to remain stable,
except perhaps that I will make it possible to infer the type
`integral_representation`.

Any opinions are welcome.

- The main reason Better Enums needs you to supply and explicit mapping is
  because it can't just get the "bits" of objects of underlying type in
  `constexpr` code. Both `reinterpret_cast` and union abuse seem to be forbidden
  in `constexpr` functions.
- There is currently no way to have two different integral representaitons for
  the same underlying type in different enums. I don't think that's a major use
  case at this point, however.



%% description = "Using Better Enums with non-integral underlying types."