# Better Enums

Reflective compile-time enum library with clean syntax, in a single header
file.

![Better Enums code overview][sample]

[sample]: https://raw.githubusercontent.com/aantron/better-enums/0.10.1/doc/image/sample.gif

[![Try online][wandbox-img]][wandbox] [![version 0.10.1][version]][releases]
[![BSD license][license-img]][license]

In C++11, *everything* can be used at compile time. You can convert your enums,
loop over them, [find their max][max],
[statically enforce conventions][enforce], and pass along the results as
template arguments or to `constexpr` functions. All the reflection is available
for your metaprogramming needs.

The interface is the same for C++98 — you just have to use most of it at
run time only. This library does provide scoped and sized enums, something not
built into C++98.

See the [project page][project] for full documentation.

[max]:      http://aantron.github.io/better-enums/demo/BitSets.html
[enforce]:  http://aantron.github.io/better-enums/demo/SpecialValues.html
[project]:  http://aantron.github.io/better-enums
[wandbox]:  http://melpon.org/wandbox/permlink/5N9QZYdA5LqWy26R
[tutorial]: http://aantron.github.io/better-enums#Tutorial
[api]:      http://aantron.github.io/better-enums/ApiReference.html
[releases]: https://github.com/aantron/better-enums/releases

[wandbox-img]: https://img.shields.io/badge/try%20it-online-blue.svg
[version]:     https://img.shields.io/badge/version-0.10.1-lightgrey.svg
[license-img]: https://img.shields.io/badge/license-BSD-lightgrey.svg

## Installation

Simply add `enum.h` to your project — that's it.

Then, include it, and use the `ENUM` macro. Your compiler will generate the rich
enums that are missing from standard C++.

## Additional features

- No dependencies and no external build tools. Uses only standard C++, though,
  for C++98, variadic macro support is required.
- Supported and tested on [clang, gcc, and msvc][testing].
- Fast compilation. You have to declare a few dozen enums to slow down your
  compiler as much as [just including `iostream` does][performance].
- Use any initializers and sparse ranges, just like with a built-in enum.
- Guaranteed size and alignment — you choose the representation type.
- Stream operators.
- Does not use the heap and can be compiled with exceptions disabled, for use in
  minimal freestanding environments.
- The underlying type [does not have to be an integral type][underlying].

[testing]:     http://aantron.github.io/better-enums/CompilerSupport.html
[performance]: http://aantron.github.io/better-enums/Performance.html
[underlying]:  http://aantron.github.io/better-enums/demo/NonIntegralUnderlyingTypes.html

## Limitations

The biggest limitation is that the `ENUM` macro can't be used inside a class.
This seems [difficult to remove][nested]. There is a workaround with `typedef`
(or C++11 `using`):

```cpp
ENUM(UniquePrefix_Color, uint8_t, Red, Green, Blue)

struct triplet {
    typedef UniquePrefix_Color      Color;
    Color                           r, g, b;
};

triplet::Color  color;
```

You can, however, use `ENUM` inside a namespace.

[nested]: http://aantron.github.io/better-enums/DesignDecisionsFAQ.html#NoEnumInsideClass

## Contact and development

Don't hesitate to contact me about features or bugs:
[antonbachin@yahoo.com][email], Twitter [@better_enums][twitter], or open an
issue on GitHub.

If you'd like to help develop Better Enums, see [CONTRIBUTING][contributing].

[![master kept stable][stable]][commits] [![Travis status][travis-img]][travis]
[![AppVeyor status][appveyor-img]][appveyor]

[email]:        mailto:antonbachin@yahoo.com
[twitter]:      https://twitter.com/better_enums
[contributing]: https://github.com/aantron/better-enums/blob/master/doc/CONTRIBUTING.md
[stable]:       https://img.shields.io/badge/master-kept_stable-brightgreen.svg
[commits]:      https://github.com/aantron/better-enums/blob/master/doc/CONTRIBUTING.md#commits

[appveyor]:     https://ci.appveyor.com/project/aantron/better-enums/branch/master
[travis]:       https://travis-ci.org/aantron/better-enums/branches
[travis-img]:   https://img.shields.io/travis/aantron/better-enums/master.svg?label=travis
[appveyor-img]: https://img.shields.io/appveyor/ci/aantron/better-enums/master.svg?label=appveyor

## License and history

Better Enums is released under the BSD 2-clause license. See [LICENSE][license].

The library was originally developed by the author in the winter of 2012-2013 at
Hudson River Trading, as a replacement for an older generator called
`BETTER_ENUM`.

[license]: https://github.com/aantron/better-enums/blob/master/doc/LICENSE