mirror of
https://github.com/aantron/better-enums.git
synced 2025-12-07 17:26:45 +08:00
2acb5743fa
The documentation is now generated from markdown. Samples are generated from the tutorial pages. Testing is done by a Python script which runs the tests for a large number of compilers. This version is not very developer-friendly - the Python scripts need ways of limiting what compilers they try to run. If you don't have 15 compilers installed, you won't be able to run the tests in this commit. Fix coming soon.
158 lines
4.5 KiB
Markdown
158 lines
4.5 KiB
Markdown
## Conversions
|
|
|
|
Let's begin by including `enum.h` and declaring our enum:
|
|
|
|
#include <cassert>
|
|
#include <iostream>
|
|
|
|
<em>#include <enum.h></em>
|
|
|
|
<em>ENUM(Channel, int, Cyan = 1, Magenta, Yellow, Black)</em>
|
|
|
|
We now have an `int`-sized enum with four constants.
|
|
|
|
There are three groups of conversion functions: for strings, case-insensitive
|
|
strings, and integers. They all follow the same pattern, so I'll explain the
|
|
string functions in detail, and the rest can be understood by analogy.
|
|
|
|
### Strings
|
|
|
|
There are three functions:
|
|
|
|
1. `._to_string`
|
|
2. `::_from_string`
|
|
3. `::_from_string_nothrow`
|
|
|
|
|
|
int main()
|
|
{
|
|
<em>Channel channel = Channel::Cyan</em>;
|
|
std::cout << <em>channel._to_string()</em> << " ";
|
|
|
|
As you'd expect, the code above prints "Cyan".
|
|
|
|
If `channel` is invalid — for example, if you simply cast the number "42"
|
|
to `Channel` — then the result of `to_string` is undefined.
|
|
|
|
---
|
|
|
|
channel = <em>Channel::_from_string("Magenta")</em>;
|
|
std::cout << channel._to_string() << " ";
|
|
|
|
This is also straightforward. If you pass a string which is not the name of a
|
|
declared value, `_from_string` throws `std::runtime_error`.
|
|
|
|
---
|
|
|
|
If you don't want an exception, there is `_from_string_nothrow`:
|
|
|
|
<em>better_enums::optional<Channel></em> maybe_channel =
|
|
<em>Channel::_from_string_nothrow("Yellow")</em>;
|
|
|
|
if (<em>!maybe_channel</em>)
|
|
std::cout << "error";
|
|
else
|
|
std::cout << <em>maybe_channel-></em>_to_string() << " ";
|
|
|
|
This returns an *optional value*, in the style of
|
|
[`boost::optional`](http://www.boost.org/doc/libs/1_58_0/libs/optional/doc/html/index.html)
|
|
or the proposed
|
|
[`std::optional`](http://en.cppreference.com/w/cpp/experimental/optional).
|
|
|
|
What that means for the above code is:
|
|
|
|
- if the conversion succeeds, `maybe_channel` converts to `true` and
|
|
`*maybe_channel` is the converted value of type `Channel`,
|
|
- if the conversion fails, `maybe_channel` converts to `false`.
|
|
|
|
In $cxx11, you can use `auto` to avoid writing out the optional type:
|
|
|
|
~~~comment
|
|
<em>auto</em> maybe_channel = <em>Channel::_from_string_nothrow("Yellow")</em>;
|
|
if (<em>!maybe_channel</em>)
|
|
std::cout << "error";
|
|
else
|
|
std::cout << <em>maybe_channel-></em>_to_string() << " ";
|
|
~~~
|
|
|
|
### Case-insensitive strings
|
|
|
|
The "`_nocase`" string conversions follow the same pattern, except for the lack
|
|
of a "`to_string_nocase`".
|
|
|
|
1. `::_from_string_nocase`
|
|
2. `::_from_string_nocase_nothrow`
|
|
|
|
|
|
channel = <em>Channel::_from_string_nocase("cYaN")</em>;
|
|
std::cout << channel._to_string() << " ";
|
|
|
|
maybe_channel = <em>Channel::_from_string_nocase_nothrow("rEeD")</em>;
|
|
assert(!maybe_channel);
|
|
|
|
### Integers
|
|
|
|
And, it is similar with the *representation type* `int`:
|
|
|
|
1. `._to_integral`
|
|
2. `::_from_integral`
|
|
3. `::_from_integral_nothrow`
|
|
4. `::_from_integral_unchecked`
|
|
|
|
|
|
channel = Channel::Cyan;
|
|
std::cout << <em>channel._to_integral()</em> << " ";
|
|
|
|
channel = <em>Channel::_from_integral(2)</em>;
|
|
std::cout << channel._to_string() << " ";
|
|
|
|
maybe_channel = <em>Channel::_from_integral_nothrow(0)</em>;
|
|
assert(<em>!maybe_channel</em>);
|
|
|
|
That prints "1 Magenta".
|
|
|
|
`_from_integral_unchecked` is a no-op unchecked cast of integers to enums, so
|
|
use it carefully.
|
|
|
|
channel = <em>Channel::_from_integral_unchecked(0)</em>;
|
|
// <em>Invalid</em> - better not to try converting it to string!
|
|
|
|
### Aside
|
|
|
|
You have certainly noticed that all the method names begin with underscores.
|
|
This is because they share scope with the enum constants that you declare.
|
|
Better Enums is trying to stay out of your way by using a prefix.
|
|
|
|
### Validity checking
|
|
|
|
For completeness, Better Enums also provides three validity checking functions,
|
|
one for each of the groups of conversions — string, case-insensitive
|
|
string, and integer:
|
|
|
|
assert(<em>Channel::_is_valid(3)</em>);
|
|
assert(<em>Channel::_is_valid("Magenta")</em>);
|
|
assert(<em>Channel::_is_valid_nocase("cYaN")</em>);
|
|
|
|
---
|
|
|
|
Almost done.
|
|
|
|
There is one unfortunate wrinkle. You cannot convert a literal constant such as
|
|
`Channel::Cyan` directly to, for example, a string. You have to prefix it with
|
|
`+`:
|
|
|
|
std::cout << (<em>+Channel::Cyan</em>)._to_string();
|
|
|
|
This is due to some type gymnastics in the implementation of Better Enums. The
|
|
<a>Reference</a> section has a full explanation.
|
|
|
|
---
|
|
|
|
This concludes the first tutorial!
|
|
|
|
---
|
|
|
|
std::cout << std::endl;
|
|
return 0;
|
|
}
|