diff --git a/README.md b/README.md index f01cd8f..e98ba74 100644 --- a/README.md +++ b/README.md @@ -76,13 +76,25 @@ triplet::Color color; You can, however, use `BETTER_ENUM` inside a namespace. +The macro has a soft limit of 64 declared constants. You can extend it by +following [these instructions][extend]. Ultimately, the number of constants is +limited by your compiler's maximum macro argument count. + +In some cases, it is necessary to prefix constants such as `Channel::Red` with a +`+` to explicitly promote them to type `Channel`. For example, if you are doing +a comparison: + +``` +channel == +Channel::Red +``` + [nested]: http://aantron.github.io/better-enums/DesignDecisionsFAQ.html#NoEnumInsideClass +[extend]: http://aantron.github.io/better-enums/ExtendingLimits.html ## 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. +[antonbachin@yahoo.com][email], or open an issue on GitHub. If you'd like to help develop Better Enums, see [CONTRIBUTING][contributing]. @@ -90,7 +102,6 @@ If you'd like to help develop Better Enums, see [CONTRIBUTING][contributing]. [![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 diff --git a/doc/ExtendingLimits.md b/doc/ExtendingLimits.md index c7fa3e1..c18a37c 100644 --- a/doc/ExtendingLimits.md +++ b/doc/ExtendingLimits.md @@ -34,6 +34,17 @@ constants of full-`constexpr` enums. To extend: - With CMake, you may need something like `add_definitions(-DBETTER_ENUMS_MACRO_FILE="$${CMAKE_SOURCE_DIR}/src/enum-macros.h")` + You can also create a new header file that defines this macro, and then + includes `enum.h`. Then, include your new file everywhere where you would + otherwise include `enum.h`: + + ~~~comment + #pragma once + + #define BETTER_ENUMS_MACRO_FILE + #include + ~~~ + 6. Enjoy the looser limits. Just watch out — increasing the second number can really slow down compilation of full-`constexpr` enums. 7. You don't need `make_macros.py` anymore. It's not part of your build diff --git a/doc/demo/105-c++17-reflection.md b/doc/demo/105-c++17-reflection.md index 464cb0d..17f6266 100644 --- a/doc/demo/105-c++17-reflection.md +++ b/doc/demo/105-c++17-reflection.md @@ -45,11 +45,10 @@ Resulting in the values `3`, `Foo::A`, and `"B"`, respectively. --- The interface is implemented in the optional header file -[`extra/better-enums/n4428.h`][header]. There are two necessary differences. - -1. The interface is only available for enums declared through the `BETTER_ENUM` - macro. This is because the macro is what generates the information necessary - for reflection. +[`extra/better-enums/n4428.h`][header]. There is a necessary difference: the +interface is only available for enums declared through the `BETTER_ENUM` macro. +This is because the macro is what generates the information necessary for +reflection. ### Demo diff --git a/doc/tutorial/7-safety.md b/doc/tutorial/7-safety.md index 2c02aa2..bc8c8bf 100644 --- a/doc/tutorial/7-safety.md +++ b/doc/tutorial/7-safety.md @@ -3,6 +3,12 @@ This tutorial shows some of the safety features of Better Enums: scope, how to control conversions, and the lack of a default constructor. +On balance, Better Enums are in one way less type-safe than enum class, and in +another way more type-safe. The first difference in safety is the presence of +implicit conversion to integral types. The second difference is the lack of a +default constructor. Both of these can be toggled, so you can make Better Enums +strictly safer than enum class, or just as safe. + $internal_toc ### Scope @@ -47,6 +53,11 @@ will not compile: The reason this is not enabled by default is explained in the reference page on [strict conversions](${prefix}OptInFeatures.html#StrictConversions). +You can conveniently define the macro on your compiler's command line, or by +creating a little header file that defines it, and then includes +enum.h. You can then include this new header file in your project +everywhere where you would have included enum.h. + ### Default constructor Better Enums generate without a default constructor. The purpose is to support diff --git a/example/105-c++17-reflection.cc b/example/105-c++17-reflection.cc index 5f6029c..2846baf 100644 --- a/example/105-c++17-reflection.cc +++ b/example/105-c++17-reflection.cc @@ -41,11 +41,9 @@ // Resulting in the values 3, Foo::A, and "B", respectively. // The interface is implemented in the optional header file -// extra/better-enums/n4428.h. There are two necessary differences. -// -// 1. The interface is only available for enums declared through the -// BETTER_ENUM macro. This is because the macro is what generates the -// information necessary for reflection. +// extra/better-enums/n4428.h. There is a necessary difference: the interface is +// only available for enums declared through the BETTER_ENUM macro. This is +// because the macro is what generates the information necessary for reflection. // // Demo // diff --git a/example/7-safety.cc b/example/7-safety.cc index 53c16b5..b60fcf7 100644 --- a/example/7-safety.cc +++ b/example/7-safety.cc @@ -5,6 +5,12 @@ // This tutorial shows some of the safety features of Better Enums: scope, how // to control conversions, and the lack of a default constructor. // +// On balance, Better Enums are in one way less type-safe than enum class, and +// in another way more type-safe. The first difference in safety is the presence +// of implicit conversion to integral types. The second difference is the lack +// of a default constructor. Both of these can be toggled, so you can make +// Better Enums strictly safer than enum class, or just as safe. +// // Scope // // You have probably noticed by now that Better Enums are scoped: when you @@ -45,28 +51,20 @@ int main() // The reason this is not enabled by default is explained in the reference page // on strict conversions. // +// You can conveniently define the macro on your compiler's command line, or by +// creating a little header file that defines it, and then includes enum.h. You +// can then include this new header file in your project everywhere where you +// would have included enum.h. +// // Default constructor // -// Better Enums don't have a default constructor, for three reasons. -// -// 1. Better Enums is a library that can't know what your application would -// like the default value to be for each enum, or whether you even want -// one. -// 2. I chose not to leave the default value undefined, because the idea is to -// encourage the convention that whenever a Better Enum exists, it has a -// valid value. This is borrowed from typed functional programming. -// 3. Better Enums is still under development, and this option is the most -// future-proof. -// -// So, if you uncomment this code, the file won't compile: +// Better Enums generate without a default constructor. The purpose is to +// support the convention where if a Better Enum exists, then it has a valid +// value. So, if you uncomment this code, the program won't compile: // // Channel channel; // -// This may be too strict, and I may relax it in the future. In the meantime, -// the solution sketched in the special values demo can replace default -// constructors for some purposes, and in a more flexible way. I may eventually -// have the default constructor calling a template function like the one in that -// demo. +// If this is too strict for your project, you can relax it as described here. return 0;