namespace fcppt
{
/// Conversions between isomorphic types
namespace type_iso {}
}

/**
\defgroup fcppttypeiso fcppt.type_iso
\ingroup fcpptmain
\brief Conversions between isomorphic types

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

<ul>
	<li>\ref typeiso_motivation</li>
	<li>\ref typeiso_design</li>
	<li>\ref typeiso_example</li>
	<li>\ref typeiso_headers</li>
</ul>

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

\section typeiso_motivation Motivation

Types can be decorated to constrain their use in a program, for example, strong
typedefs, boost units and so on. This is mainly done to prevent accidental
usage of their values. Sometimes, however, it is necessary to undecorate them
in a generic way. Consider a range of strong typedefs of integers. To compute
the size of such a range (for example as a <code>std::size_t</code>), the
strong typedefs have to be undecorated first. Because the integer range is a
generic class, it needs to know how to do this for every type.

\section typeiso_design Design

A type <code>T</code> can be decorated by a type constructor <code>D</code> to
yield <code>D<T></code>. An isomorphism between <code>T</code> and
<code>D<T></code> is a pair of functions:
<ul>
<li><code>T undecorate(D<T>)</code> and
<li><code>D<T> decorate(T)</code>
</ul>
such that their compositions are the identity.
How they are implemented exactly can vary for every <code>D</code>
significantly.
In fcppt, these two functions are implemented as a specialization of #fcppt::type_iso::transform. A specialization needs to contain the two
aforementioned functions along with the typedefs <code>decorated_type</code>
and <code>undecorated_type</code>.

In general, multiple type constructors can be applied one by one to yield:
<code>D_1<...D_n<T>...></code>. The lifted functions that decorate and
undecorate between this type and <code>T</code> are called #fcppt::type_iso::decorate and #fcppt::type_iso::undecorate.

\section typeiso_example Example

The first example shows how the decorate and undecorate functions can be used:
\snippet type_iso.cpp decorate_simple_include
\snippet type_iso.cpp decorate_simple

The next example shows how to implement a type decoration:
\snippet type_iso.cpp decorate_custom

\section typeiso_headers Header files
<table>
<tr>
<th>Header file</th>
<th>Description</th>
</tr>
<tr>
<td><code>decorate.hpp</code></td>
<td>Contains #fcppt::type_iso::decorate.</td>
</tr>
<tr>
<td><code>undecorate.hpp</code></td>
<td>Contains #fcppt::type_iso::undecorate.</td>
</tr>
<tr>
<td><code>undecorated_type.hpp</code></td>
<td>Contains the #fcppt::type_iso::undecorated_type typedef.</td>
</tr>
<tr>
<td><code>transform_fwd.hpp</code></td>
<td>Contains the forward declaration of #fcppt::type_iso::transform.</td>
</tr>
<tr>
<td><code>strong_typedef.hpp</code></td>
<td>Bindings for \ref fcpptstrongtypedef.</td>
</tr>
<tr>
<td><code>boost_units.hpp</code></td>
<td>Bindings for Boost.Units.</td>
</tr>
<tr>
<td><code>enum.hpp</code></td>
<td>Bindings for \ref fcpptenum.</td>
</tr>
</table>
*/
