/**
\defgroup fcpptcasts fcppt.casts
\ingroup fcpptmain
\brief Cast helpers which provide more type information or do additional checks

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

<ul>
	<li>\ref fcpptcasts_motivation</li>
	<li>\ref fcpptcasts_special</li>
	<li>\ref fcpptcasts_safe</li>
	<li>\ref fcpptcasts_truncation_check</li>
	<li>\ref fcpptcasts_dynamic_casting</li>
	<li>\ref fcpptcasts_structure_cast</li>
</ul>

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

\section fcpptcasts_motivation Motivation

C++ offers four different casts: <code>static_cast</code>,
<code>const_cast</code>, <code>reinterpret_cast</code> and
<code>dynamic_cast</code> which cover a wide area of explicit conversions.
Some conversions can only be done by casts, e.g. <code>dynamic_cast</code> to
cast in a polymorphic class hierarchy or <code>reinterpret_cast</code> to
access the bytes of an object. <code>static_cast</code> can be used to reverse
implicit conversions or make implicit conversions explicit. Therefore,
<code>static_cast</code> does too many things at once, often hiding the intent
of the programmer. Also, <code>static_cast</code> involves no checking which
can be undesirable.

In order to fix these shortcomings, this module provides special casts, which
highlight the intent of the programmer, and casts that check for truncation at
compile time or at runtime.

\section fcpptcasts_special Special Casts

Special casts are used to replace <code>static_cast</code> and
<code>reinterpret_cast</code> where possible:

<table>
<tr>
	<td>
	Casting between signed and unsigned integers
	</td>
	<td>
	#fcppt::cast::to_signed, #fcppt::cast::to_unsigned
	</td>
</tr>
<tr>
	<td>
	Casting between types of the same signedness but different sizes
	</td>
	<td>
	#fcppt::cast::size
	</td>
</tr>
<tr>
	<td>
	Casting between floats and integers
	</td>
	<td>
	#fcppt::cast::int_to_float, #fcppt::cast::float_to_int
	</td>
</tr>
<tr>
	<td>
	Casting between enums and integers
	</td>
	<td>
	#fcppt::cast::int_to_enum, #fcppt::cast::enum_to_int, #fcppt::cast::enum_to_underlying
	</td>
</tr>
<tr>
	<td>
	Casting between objects in a class hierarchy
	</td>
	<td>
	#fcppt::cast::static_downcast, #fcppt::cast::dynamic
	</td>
</tr>
<tr>
	<td>
	Casting between unrelated types
	</td>
	<td>
	#fcppt::cast::dynamic_cross
	</td>
</tr>
<tr>
	<td>
	Casting from pointers to void
	</td>
	<td>
	#fcppt::cast::from_void_ptr
	</td>
</tr>
<tr>
	<td>
	Casting to a byte array
	</td>
	<td>
	#fcppt::cast::to_char_ptr
	</td>
</tr>
</table>

Here is a small example:

\snippet cast.cpp float_to_int

An important thing to note is that these casts can't be used with the wrong
types on accident:

\snippet cast.cpp to_unsigned

\section fcpptcasts_safe Safe conversions

#fcppt::cast::safe_numeric is a cast that doesn't do any runtime checking (as
opposed to #fcppt::cast::truncation_check). Instead, it checks at compile time
which conversions between arithmetic types are safe. See
#fcppt::cast::safe_numeric for a detailed description on which conditions must
hold in order for the cast to compile.

The following example shows how a class's constructor can be strengthened by
#fcppt::cast::safe_numeric:

\snippet cast/safe_numeric.cpp safe_numeric_cast_class

Here are some examples of how the constructor can and can't be called:

\snippet cast/safe_numeric.cpp safe_numeric_cast_objects

\section fcpptcasts_truncation_check Checking truncation

#fcppt::cast::truncation_check complements #fcppt::cast::safe_numeric by checking at runtime if a conversion
truncates.

In the following example, it is tested if the biggest <code>unsigned
long</code> value fits into an <code>unsigned int</code>. This might be true,
depending on the architecture.

\snippet cast/truncation_check.cpp truncation_check_cast_int_long

Truncating conversions of negative values are also detected.

\snippet cast/truncation_check.cpp truncation_check_cast_negative

\section fcpptcasts_dynamic_casting Dynamic casting

<code>dynamic_cast</code> can cast between pointers or references to objects in
a class hierarchy. The cast can fail at runtime in which case the null pointer
is returned for pointers and <code>bad_cast</code> is thrown for references.
#fcppt::cast::dynamic returns an empty optional on failure instead:

\snippet cast/dynamic.cpp dynamic

To catch more mistakes, #fcppt::cast::dynamic only works on related types: The type to cast
to must inherit from the source type. In case you need to cast between
unrelated types, #fcppt::cast::dynamic_cross can be used:

\snippet cast/dynamic_cross.cpp dynamic_cross

\section fcpptcasts_structure_cast Casting user-defined types

For user-defined types static_cast and all of the casts from fcppt::cast can't
be used directly. Instead, custom cast functions have to be defined. For
example, fcppt.math defines functions called structure_cast to cast between
vectors, dims and matrices. To incorporate cast functions from fcppt::cast, an
additional template argument has to be added to the function's signature which
then will be used to cast each element of the user-defined structure. For this
purpose, this module defines several function objects suffixed with _fun, for
example #fcppt::cast::float_to_int_fun.

\snippet math/casts.cpp float_to_int_fun
*/

namespace fcppt
{
/// Cast helpers which provide more type information or do additional checks
namespace cast {}
}
