coffee/better-enums
1
0
Fork 0
mirror of https://github.com/aantron/better-enums.git synced 2025-12-07 01:06:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

Minimally updated documentation.

Browse Source
This commit is contained in:
Anton Bachin 2015-05-17 22:49:24 -05:00
parent 6c60edcc46
commit 10c9977a9c
4 changed files with 34 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
README.md
View File

@ -25,30 +25,18 @@ for (Channel channel : Channel::_values) {
}
```
...and more. See the [project page](http://aantron.github.io/better-enums) and
...and more. See the
[project page](http://aantron.github.io/better-enums#tutorial) and
[examples](https://github.com/aantron/better-enums/tree/master/example) for a
tutorial.
## Installation
Simply add `enum.h` and `enum_preprocessor_map.h` to your project. The current
version can be found at
[https://github.com/aantron/better-enums/releases](https://github.com/aantron/better-enums/releases).
`enum_preprocessor_map.h` can handle enums with up to 256 constants. If you have
more, re-generate it by running something like:
./pp_map_gen.py enum_preprocessor_map.h 512
This only needs to be done once when the constant limit is exceeded. You don't
need to do this on every build. I hope to remove the need for this completely in
a future version.
Simply add `enum.h` from `master` to your project.
## Features
- Generated at compile time by `constexpr` functions and the preprocessor.
`pp_map_gen.py` is only needed if you have an enum with more than 256
constants.
- Safe conversions between enums and integers and strings.
[1-basic.cc](https://github.com/aantron/better-enums/blob/master/example/1-basic.cc)
- Iterable collections of constants and names.
@ -58,22 +46,21 @@ a future version.
[2-iterate.cc](https://github.com/aantron/better-enums/blob/master/example/2-iterate.cc)
- Switch case checking.
[3-switch.cc](https://github.com/aantron/better-enums/blob/master/example/3-switch.cc)
- Almost all operations are `constexpr` and can be used at compile time in your
own `constexpr` code.
- All operations are `constexpr` and can be used at compile time in your own
`constexpr` code.
[4-constexpr.cc](https://github.com/aantron/better-enums/blob/master/example/4-constexpr.cc)
- Constant values can be set (`Red = 1`) and aliased (`Favorite = Green`), just
like with built-in enums.
- Generating a large number of enums is faster than including a typical standard
header like `iostream` – performance test included.
- Generating a large number of enums is about as fast as including a typical
standard header like `iostream` – performance test included.
- Explicit choice of underlying representation type.
- Header-only.
- No dependencies besides the standard library.
- Tested on gcc 4.9 and clang 3.6.
The library compiles only with gcc and clang due to use of weak symbols and due
to lagging C++11 support in msvc. It should ultimately be portable to msvc,
since msvc has its own version of weak symbols. Everything else in the library
is standard C++.
The library is standard C++, but it compiles only with gcc and clang due to
lagging C++11 support in msvc. A future runtime fallback version will allow
msvc and non-C++11 usage.
## Contact
@ -98,12 +85,6 @@ See the full [documentation](http://aantron.github.io/better-enums).
There are several areas that still need improvement.
- I will try to eliminate the need for `pp_map_gen.py`. The library will then
consist of one file, `enum.h`.
- `to_string` can be made `constexpr`, like most of the rest of the code.
- Iterators over defined constants should be made random-access. This would
allow `constexpr` functions to use them by adding 1 – the only way to advance
them now is by mutating increment.
- Some enum types might have a sensible choice for a default constructor. The
library should allow it to be customized.
- All safety checks are currently done by linear scans. This may be a

15
doc/api.html
View File

@ -637,17 +637,16 @@ do_something(Enum::A); // converted silently</pre>
<a id="to_string"></a>
<h3>
<span>member</span> const char* enum_value.to_string()
<span>member constexpr</span> const char* enum_value.to_string()
<span>const</span>
</h3>
<p>
Returns the string representation of enum value on which the method is
called. If multiple constants have the same numeric value, the string
returned can be the representation any of the constants. Note that this
method is <em>not</em> <tt>constexpr</tt>. Complexity is <em>linear</em> in
the number of constants. If the string does not name a constant,
<em>throws</em> <tt>std::runtime_error</tt>.
returned can be the representation any of the constants. Complexity is
<em>linear</em> in the number of constants. If the string does not name a
constant, <em>throws</em> <tt>std::runtime_error</tt>.
</p>
<a id="name"></a>
@ -728,9 +727,9 @@ Enum::_values::end()</pre>
<h3><span>class</span> _NameIterable::iterator</h3>
<p>
An iterator over defined constant names with a dereference operator that is
<em>not</em> <tt>constexpr</tt>. Can be created explicitly by the
<tt>constexpr</tt> expressions
An iterator over defined constant names with a <tt>constexpr</tt>
dereference operator. Can be created explicitly by the <tt>constexpr</tt>
expressions
</p>
<pre>Enum::_names::begin()

35
doc/index.html
View File

@ -59,8 +59,8 @@
<p>
Better Enums gives you rich, reflective enums with the nicest syntax yet
seen.<sup><a href="#note">1</a></sup> All you have to do is add two short,
simple header files to your project, and you are ready to go.
seen.<sup><a href="#note">1</a></sup> All you have to do is add one short
and simple header file to your project, and you are ready to go.
</p>
<pre>#include &lt;enum.h&gt;
@ -71,15 +71,16 @@ ENUM(Channel, int, Red, Green, Blue);</pre>
reflective capacity, including string conversions, value listing,
compile-time operations, static information about the range of declared
constants, and (last and probably least) the name <code>"Channel"</code>
itself.
itself. You can even assign explicit values to constants and alias them
like with a normal built-in <code>enum</code>.
</p>
<p>
The enum is easy to maintain. There is no duplication of value names,
no repetition of cumbersome macros, and no generator to run on every
build. The library is header-only and has no dependencies, so there aren't
any object files to link with. You can assign explicit values to constants
and alias them like with a normal <code>enum</code>.
any object files to link with. It is also standard
<span class="cpp">C++</span>.
</p>
<p>
@ -95,13 +96,11 @@ ENUM(Channel, int, Red, Green, Blue);</pre>
<h2>Installation</h2>
<p>
Download the
<a href="https://github.com/aantron/better-enums/releases/latest">
latest release</a>, then copy the files
<code>enum.h</code> and <code>enum_preprocessor_map.h</code> to your
project. That's it! Just make sure both files are in your include path and
you are compiling with <span class="cc">gcc</span> or
<span class="cc">clang</span> in
Download
<a href="https://github.com/aantron/better-enums/blob/master/enum.h">
enum.h</a> and copy it to your project. That's it! Just make sure it's in
your include path and you are compiling with <span class="cc">gcc</span>
or <span class="cc">clang</span> in
<span class="cpp">C++</span><span class="eleven">11</span> mode.
</p>
@ -212,13 +211,13 @@ Channel my_channel = Channel::_from_integral(2);</pre>
<hr />
<p>
Finally, most of the above is declared <code>constexpr</code> and can be
run at compile time. This means you can do all sorts of parsing and
processing at the same time the rest of your code is being compiled,
improving runtime and startup performance! See some
Finally, all of the above can be done at compile time. This means you can
do all sorts of parsing and processing at the same time the rest of your
code is being compiled, improving runtime and startup performance! See
some
<a href="https://github.com/aantron/better-enums/blob/master/example/4-constexpr.cc">examples</a>
and another
<a href="https://github.com/aantron/better-enums/blob/master/example/6-traits.cc">example</a>.
<a href="https://github.com/aantron/better-enums/blob/master/example/6-traits.cc">2</a>
<a href="https://github.com/aantron/better-enums/blob/master/example/8-constexpr-iterate.cc">3</a>.
</p>
</section>

2
doc/sitemap.xml
View File

@ -2,11 +2,9 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://aantron.github.io/better-enums</loc>
<changefreq>daily</changefreq>
<priority>1.0</priority>
</url>
<url>
<loc>http://aantron.github.io/better-enums/api.html</loc>
<changefreq>daily</changefreq>
</url>
</urlset>