2.6.0
Freundlich's C++ toolkit
Classes | Typedefs | Functions
fcppt.enum

Description

Helper functions for contiguous enums.

Contiguous Enums

Contiguous enums are enums whose enumerator values form a range of 0 to max, 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:

enum class myenum
{
val1,
val2,
val3
};

It is often desirable 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 has the default behavior of inferring the maximum value from the special enumerator value fcppt_maximum, for example:

enum class myenum
{
val1,
val2,
};
void
print_enum(
myenum const _value
)
{
<<
// Convert to an integer
_value
)
<< '\n';
}
void
{
print_enum(
myenum
>::value
);
}

Additionally, the trait class can also be specialized. Building on top of this, fcppt::enum_::size calculates the number of enumerators in an enum, setting it to fcppt::enum_::max_value<Enum> + 1 by default.

Enum Ranges

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

// Prints 0, 1
for(
myenum const value
:
myenum
>()
)
print_enum(
value
);

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.

Array indexed with an enum

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

typedef
myenum,
bool
>
// Requires three {} pairs because the array wraps std::array
// internally
array const val{{{
true,
false
}}};
<<
val[myenum::val1]
<<
'\n';

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.

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. The function that does this is called fcppt::enum_::names which returns an fcppt::enum_::names_array. The implementation uses the customization point fcppt::enum_::names_impl which needs to be provided for every enum you wish to use this function with, for example:

namespace
{
myenum
> const names{{{
FCPPT_TEXT("val1"),
FCPPT_TEXT("val2")
}}};
}
namespace fcppt
{
namespace enum_
{
template<>
struct names_impl<
myenum
>
{
static
myenum
> const &
get()
{
}
};
}
}

The enum names can then be used to convert enums from and to strings. fcppt::enum_::to_string uses fcppt::enum_::to_string_impl, which by default makes use of fcppt::enum_::names. Since we just provided the enum names for myenum, we can convert it to a string:

myenum const test{
myenum::val2
};
fcppt::string const converted{
)
};

Similarly, we can also try to convert a string to an enum: fcppt::enum_::from_string uses fcppt::enum_::from_string_impl, which, again, makes use of fcppt::enum_::names by default. In case the conversion fails, an empty optional is returned:

// Returns an empty optional
myenum
> const enum1{
myenum
>(
FCPPT_TEXT("test")
)
};
// Returns myenum::val1
myenum
> const enum2{
myenum
>(
FCPPT_TEXT("val1")
)
};

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 operator>> and operator<<.

Classes

class  fcppt::enum_::array< Enum, Value >
 An array indexed with an enum. More...
 
class  fcppt::enum_::iterator< Enum >
 
struct  fcppt::enum_::max_value< Type >
 The maximum enumerator in an enum. More...
 
struct  fcppt::enum_::min_value< Type >
 The minimum enumerator in an enum. More...
 
class  fcppt::enum_::range< Enum >
 A range over a contiguous enum. More...
 
struct  fcppt::enum_::size< Type >
 The number of enumerators in an enum. More...
 
struct  fcppt::mpl::enum_range_start_end< Enum, Start, Max >
 An MPL range over enums from a minimum to a maximum. More...
 

Typedefs

template<typename Enum >
using fcppt::enum_::names_array = fcppt::enum_::array< Enum, fcppt::string >
 Array type for The names of an enum. More...
 
template<typename Type >
using fcppt::enum_::size_type = typename fcppt::enum_::size_type_impl< Type >::type
 The size type used to count the number of enumerators in an enum. More...
 
template<typename Enum >
using fcppt::mpl::enum_range = fcppt::mpl::enum_range_start_end< Enum, fcppt::enum_::min_value< Enum >::value, fcppt::enum_::max_value< Enum >::value >
 An MPL range over enums. More...
 

Functions

template<typename Enum , typename Value >
bool fcppt::enum_::operator== (fcppt::enum_::array< Enum, Value > const &_a, fcppt::enum_::array< Enum, Value > const &_b)
 Compares two enum arrays for equality. More...
 
template<typename Enum , typename Value >
bool fcppt::enum_::operator!= (fcppt::enum_::array< Enum, Value > const &_a, fcppt::enum_::array< Enum, Value > const &_b)
 Compares two enum arrays for inequality. More...
 
template<typename Array , typename Function >
Array fcppt::enum_::array_init (Function const &_function)
 Constructs an array by calling a function with static enumerators. More...
 
template<typename Enum , typename Value >
fcppt::optional::object< Enum > fcppt::enum_::from_int (Value const &_value) noexcept
 Cast an unsigned value to an enum. More...
 
template<typename Enum , typename Value >
Enum fcppt::enum_::from_int_exn (Value const &_value)
 Cast an unsigned value to an enum. More...
 
template<typename Enum >
fcppt::optional::object< Enum > fcppt::enum_::from_string (fcppt::string const &_string)
 Converts a string to an enum. More...
 
template<typename Enum , typename Value >
fcppt::optional::object< Enum > fcppt::enum_::index_of_array (fcppt::enum_::array< Enum, Value > const &_array, Value const &_value)
 Returns the enum of the first element found in an enum array. More...
 
template<typename Enum >
fcppt::io::istreamfcppt::enum_::input (fcppt::io::istream &_stream, Enum &_result)
 Reads an enum value from a stream. More...
 
template<typename Enum >
fcppt::enum_::range< Enum > fcppt::enum_::make_range () noexcept
 Creates an enum range over the whole enum. More...
 
template<typename Enum >
fcppt::enum_::range< Enum > fcppt::enum_::make_range_start (Enum const _start) noexcept
 Creates an enum range with a custom start value. More...
 
template<typename Enum >
fcppt::enum_::range< Enum > fcppt::enum_::make_range_start_end (Enum const _start, Enum const _end) noexcept
 Creates a closed enum range. More...
 
template<typename Enum >
fcppt::enum_::names_array< Enum > const & fcppt::enum_::names ()
 The names of an enum. More...
 
template<typename Enum >
fcppt::io::ostreamfcppt::enum_::output (fcppt::io::ostream &_stream, Enum const _value)
 Outputs an enum value to a stream. More...
 
template<typename Enum , typename Function >
decltype(auto) fcppt::enum_::to_static (Enum const _enum, Function const &_function)
 Converts a runtime enum value into a compile time one, passing it to a function. More...
 
template<typename Enum >
fcppt::string fcppt::enum_::to_string (Enum const _enum)
 Converts an enum to a string. More...
 

Typedef Documentation

◆ enum_range

template<typename Enum >
using fcppt::mpl::enum_range = typedef fcppt::mpl::enum_range_start_end< Enum, fcppt::enum_::min_value< Enum >::value, fcppt::enum_::max_value< Enum >::value >

An MPL range over enums.

◆ names_array

template<typename Enum >
using fcppt::enum_::names_array = typedef fcppt::enum_::array< Enum, fcppt::string >

Array type for The names of an enum.

Template Parameters
EnumMust be an enum type

◆ size_type

template<typename Type >
using fcppt::enum_::size_type = typedef typename fcppt::enum_::size_type_impl< Type >::type

The size type used to count the number of enumerators in an enum.

The size type used to count the number of enumerators in Type.

Template Parameters
TypeMust be an enum type

Function Documentation

◆ array_init()

template<typename Array , typename Function >
Array fcppt::enum_::array_init ( Function const &  _function)
inline

Constructs an array by calling a function with static enumerators.

Constructs an enum array of type Array by calling _function(std::integral_constant<Array::enum_type,E>) for every enumerator E.

Template Parameters
ArrayMust be an fcppt::enum_::array.
FunctionMust be a function callable as Array::value_type (std::integral_constant<Array::enum_type,E>).
See also
fcppt::algorithm::array_init

◆ from_int()

template<typename Enum , typename Value >
fcppt::optional::object< Enum> fcppt::enum_::from_int ( Value const &  _value)
noexcept

Cast an unsigned value to an enum.

Casts the unsigned value _value to Enum. Returns an empty optional if the cast fails.

Parameters
_valueThe value to cast from
Template Parameters
EnumMust be an enum type
ValueMust be an unsigned type

◆ from_int_exn()

template<typename Enum , typename Value >
Enum fcppt::enum_::from_int_exn ( Value const &  _value)

Cast an unsigned value to an enum.

Casts the unsigned value _value to Enum, throwing an exception if the value is out of range.

Parameters
_valueThe value to cast from
Template Parameters
EnumMust be an enum type
ValueMust be an unsigned type
Exceptions
fcppt::exceptionif _value is greater or equal to the enum's max size
Returns
The casted value if it fits into the enum's range

◆ from_string()

template<typename Enum >
fcppt::optional::object< Enum> fcppt::enum_::from_string ( fcppt::string const &  _string)
inline

Converts a string to an enum.

Uses fcppt::enum_::from_string_impl to convert a string to an enum.

Template Parameters
EnumMust be an enum type

◆ index_of_array()

template<typename Enum , typename Value >
fcppt::optional::object< Enum> fcppt::enum_::index_of_array ( fcppt::enum_::array< Enum, Value > const &  _array,
Value const &  _value 
)
inline

Returns the enum of the first element found in an enum array.

Searches for _value in _array and returns the index of the first occurrence as an enum if there is any, otherwise returns the empty optional.

◆ input()

template<typename Enum >
fcppt::io::istream& fcppt::enum_::input ( fcppt::io::istream _stream,
Enum &  _result 
)

Reads an enum value from a stream.

Uses fcppt::enum_::from_string to read an enum from _stream and store it in _result. In case this fails, the failbit of _stream is set. This function is useful to implement operator>> for an enum type.

Template Parameters
EnumMust be an enum type
Returns
_stream

◆ make_range()

template<typename Enum >
fcppt::enum_::range< Enum> fcppt::enum_::make_range ( )
inlinenoexcept

Creates an enum range over the whole enum.

Creates the enum range [fcppt::enum_::min_value<Enum>::value, fcppt::enum_::max_value<Enum>::value].

◆ make_range_start()

template<typename Enum >
fcppt::enum_::range< Enum> fcppt::enum_::make_range_start ( Enum const  _start)
inlinenoexcept

Creates an enum range with a custom start value.

Creates the closed range [_start, enum_max_value<Enum>::value].

Parameters
_startThe first element of the range.

◆ make_range_start_end()

template<typename Enum >
fcppt::enum_::range< Enum> fcppt::enum_::make_range_start_end ( Enum const  _start,
Enum const  _end 
)
inlinenoexcept

Creates a closed enum range.

Creates the enum range [_start,_end]. The range must be closed because there is no "one past the end" enum value.

Parameters
_startThe first element of the range.
_endThe last element of the range.

◆ names()

template<typename Enum >
fcppt::enum_::names_array< Enum> const& fcppt::enum_::names ( )
inline

The names of an enum.

Template Parameters
EnumMust be an enum type

◆ operator!=()

template<typename Enum , typename Value >
bool fcppt::enum_::operator!= ( fcppt::enum_::array< Enum, Value > const &  _a,
fcppt::enum_::array< Enum, Value > const &  _b 
)
inline

Compares two enum arrays for inequality.

Template Parameters
ValueMust be equality-comparable.

◆ operator==()

template<typename Enum , typename Value >
bool fcppt::enum_::operator== ( fcppt::enum_::array< Enum, Value > const &  _a,
fcppt::enum_::array< Enum, Value > const &  _b 
)

Compares two enum arrays for equality.

Template Parameters
ValueMust be equality-comparable.

◆ output()

template<typename Enum >
fcppt::io::ostream& fcppt::enum_::output ( fcppt::io::ostream _stream,
Enum const  _value 
)

Outputs an enum value to a stream.

Uses fcppt::enum_::to_string to output _value to _stream. This function is useful to implement operator<< for an enum type.

Template Parameters
EnumMust be an enum type
Returns
_stream

◆ to_static()

template<typename Enum , typename Function >
decltype( auto ) fcppt::enum_::to_static ( Enum const  _enum,
Function const &  _function 
)
inline

Converts a runtime enum value into a compile time one, passing it to a function.

◆ to_string()

template<typename Enum >
fcppt::string fcppt::enum_::to_string ( Enum const  _enum)
inline

Converts an enum to a string.

Uses fcppt::enum_::to_string_impl to convert an enum to a string.

Template Parameters
EnumMust be an enum type