/**
\defgroup fcpptenum fcppt.enum
\ingroup fcpptmain
\brief Helper functions for contiguous enums

<table id="toc">
<tr>
<td>

<ul>
	<li>\ref fcpptenum_contiguous</li>
	<li>\ref fcpptenum_range</li>
	<li>\ref fcpptenum_array</li>
	<li>\ref fcpptenum_cast_to</li>
	<li>\ref fcpptenum_string</li>
</ul>

</td>
</tr>
</table>

\section fcpptenum_contiguous Contiguous Enums

Contiguous enums are enums whose enumerator values form a range of
<code>0</code> to <code>max</code>, which means there is no gap in between the
values. For example, if no enumerator values are specified, an enum is contiguous
as in the following example:

\snippet enum.cpp enum_def

Most function of this library need to know the enum's maximum value, or its number of
enumerators, for that matter. Unfortunately, C++ offers no introspection of any
kind which makes it possible to query the maximum value. fcppt provides a trait
class called #fcppt::enum_::max_value, which can be quickly specialized by
using #FCPPT_ENUM_DEFINE_MAX_VALUE in the global namespace, for example:

\snippet enum.cpp enum_maximum

Building on top of this, #fcppt::enum_::size calculates the number of enumerators in an enum, setting
it to <code>fcppt::enum_::max_value<Enum> + 1</code> by default.

\section fcpptenum_range Enum Ranges

Given the above definition of contiguous enums, it is possible to create a
range that iterates over an enum.

\snippet enum.cpp enum_range

#fcppt::enum_::make_range creates an #fcppt::enum_::range which uses
#fcppt::enum_::iterator. To create subranges of enums, there are
#fcppt::enum_::make_range_start and #fcppt::enum_::make_range_start_end.

\section fcpptenum_array Array indexed with an enum

A contiguous enum is also a range of constant size, making it suitable as an
index for an #fcppt::array::object. #fcppt::enum_::array is a class that wraps
#fcppt::array::object, replacing all indices by Enums, for example:

\snippet enum.cpp enum_array

\section fcpptenum_cast_to Cast to enums

Casting an integral value to an enum might be needed when deserializing data.
It is important, however, that the value must not fall outside of the enum's
range. #fcppt::enum_::from_int returns an empty optional in this case.

\section fcpptenum_string String conversion

Converting enums from and to strings is also often needed. Unfortunately, because
C++ offers no introspection of any kind for enums, we have to provide our own mapping
from enums to strings.
To implement this for a custom enum type <code>Enum</code>, we have to specialize the struct #fcppt::enum_::to_string_impl
and implement a member function <code>std::string get(Enum)</code>. For example:

\snippet enum.cpp enum_names

We can now use #fcppt::enum_::to_string to convert <code>myenum</code> to a string:

\snippet enum.cpp enum_to_string

Similarly, we can also try to convert a string to an enum: #fcppt::enum_::from_string uses
#fcppt::enum_::from_string_impl, which by default simply goes through all possible enum names.
If no enum name matches, an empty optional is returned:

\snippet enum.cpp enum_from_string

The functions #fcppt::enum_::input and #fcppt::enum_::output make use of #fcppt::enum_::from_string
and #fcppt::enum_::to_string respectively. They can be used to implement <code>operator>></code> and
<code>operator<<</code>.
*/
