/**
\defgroup fcpptoptional fcppt.optional
\ingroup fcpptmain
\brief A class that makes values optional.

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

<ul>
	<li>\ref optional_motivation</li>
	<li>\ref optional_design</li>
	<li>\ref optional_reference</li>
	<li>\ref optional_operations</li>
	<li>\ref optional_headers</li>
</ul>

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

\section optional_motivation Motivation

The goal of an optional type is to make it explicit that a value might be missing.
This includes operations that might return no result, for example looking for
an element in a container, performing a conversion that can fail,
a tree that might have no parent, and so on.
Values that may be nothing are common in C++ but are not handled consistently.
This includes special values like <code>std::string::npos</code>, <code>nullptr</code>
or end iterators. Modelling optionals explicitly has several advantages. Consider the
following example:

\snippet optional.cpp optional_example_bad

First of all, the example makes it clear that the function can deal with an
<code>unsigned int</code> or nothing at all. However, using optionals in this way
makes them no safer than using pointers that may be null. In order to fix this,
we must avoid calling <code>get_unsafe</code> manually.
The most basic operation that does this for us is called <code>maybe</code>.
The user provides two functions which act on the two different cases.

\snippet optional.cpp optional_example_good

Notice that by using <code>maybe</code>, the code checking if the optional has
a value and the code dereferencing the optional are both gone.

\section optional_design Design

The key differences to <code>std::optional</code> include:
<ul>
<li><code>%fcppt::optional::object</code> does not have
<code>operator-></code>, <code>operator*</code> nor <code>operator bool</code>,
so that it does not mimic pointers.</li>
<li><code>%fcppt::optional::object\<T></code> does not have an implicit
constructor, nor assignment operator from <code>T</code>.</li>
<li>A lot of functions are provided that make the use of optionals safe
by not having the user dereference optionals manually.</li>
</ul>

\section optional_reference Optional References

Instead of implementing optional references directly, fcppt offers #fcppt::optional::reference which is a typedef to
<code>%fcppt::optional::object<fcppt::reference<T>></code>. The reason behind
this is that code that acts on optionals might make use of references
itself. For example it is not uncommon to pass the object held by an optional
to functions like #fcppt::optional::maybe_void by (const)
reference, which can be used to change the object or to pass its address along.

\snippet optional.cpp optional_reference

On the other hand, if an optional holds a reference it does not hold the actual
object, so changing the object behind the reference or passing the reference
along has different semantics.

\snippet optional.cpp optional_reference_2

Using #fcppt::reference for optional references clearly
distinguishes these two cases.

\section optional_operations Common Operations

#fcppt::optional::maybe is the most basic function that operates
on optionals.

#fcppt::optional::map lifts a function to a function
on optionals:

\snippet optional.cpp optional_map

The more general #fcppt::optional::bind returns the function's
result directly:

\snippet optional.cpp optional_bind

Another commonly used function is #fcppt::optional::from:

\snippet optional.cpp from_optional

\section optional_headers Header files

<table>
<tr>
<th>Header file</th>
<th>Description</th>
</tr>
<tr>
<td><code>object_fwd.hpp</code></td>
<td>Contains #fcppt::optional::object optional's  declaration.</td>
</tr>
<tr>
<td><code>object_decl.hpp</code></td>
<td>Contains #fcppt::optional::object optional's  definition.</td>
</tr>
<tr>
<td><code>object_impl.hpp</code></td>
<td>Contains the definition of #fcppt::optional::object optional's  member functions.</td>
</tr>
<tr>
<td><code>object.hpp</code></td>
<td>Includes <code>object_impl.hpp</code> and <code>comparison.hpp</code>.</td>
</tr>
<tr>
<td><code>alternative.hpp</code></td>
<td>Contains #fcppt::optional::alternative .</td>
</tr>
<tr>
<td><code>apply.hpp</code></td>
<td>Contains #fcppt::optional::apply .</td>
</tr>
<tr>
<td><code>assign.hpp</code></td>
<td>Contains #fcppt::optional::assign .</td>
</tr>
<tr>
<td><code>bind.hpp</code></td>
<td>Contains #fcppt::optional::bind .</td>
</tr>
<tr>
<td><code>cat.hpp</code></td>
<td>Contains #fcppt::optional::cat .</td>
</tr>
<tr>
<td><code>combine.hpp</code></td>
<td>Contains #fcppt::optional::combine .</td>
</tr>
<tr>
<td><code>comparison.hpp</code></td>
<td>Contains <code>operator==</code>, <code>operator!=</code> and <code>operator< </code>.</td>
</tr>
<tr>
<td><code>copy_value.hpp</code></td>
<td>Contains #fcppt::optional::copy_value .</td>
</tr>
<tr>
<td><code>deref.hpp</code></td>
<td>Contains #fcppt::optional::deref .</td>
</tr>
<tr>
<td><code>filter.hpp</code></td>
<td>Contains #fcppt::optional::filter .</td>
</tr>
<tr>
<td><code>from.hpp</code></td>
<td>Contains #fcppt::optional::from .</td>
</tr>
<tr>
<td><code>from_pointer.hpp</code></td>
<td>Contains #fcppt::optional::from_pointer .</td>
</tr>
<tr>
<td><code>join.hpp</code></td>
<td>Contains #fcppt::optional::join .</td>
</tr>
<tr>
<td><code>make.hpp</code></td>
<td>Contains #fcppt::optional::make .</td>
</tr>
<tr>
<td><code>map.hpp</code></td>
<td>Contains #fcppt::optional::map .</td>
</tr>
<tr>
<td><code>maybe.hpp</code></td>
<td>Contains #fcppt::optional::maybe .</td>
</tr>
<tr>
<td><code>maybe_multi.hpp</code></td>
<td>Contains #fcppt::optional::maybe_multi .</td>
</tr>
<tr>
<td><code>maybe_void.hpp</code></td>
<td>Contains #fcppt::optional::maybe_void .</td>
</tr>
<tr>
<td><code>maybe_void_multi.hpp</code></td>
<td>Contains #fcppt::optional::maybe_void_multi .</td>
</tr>
<tr>
<td><code>output.hpp</code></td>
<td>Contains <code>operator<< </code>.</td>
</tr>
<tr>
<td><code>reference_fwd.hpp</code></td>
<td>Contains the #fcppt::optional::reference  typedef.</td>
</tr>
<tr>
<td><code>reference.hpp</code></td>
<td>Includes <code>reference_fwd.hpp</code> and <code>object_impl.hpp</code>.</td>
</tr>
<tr>
<td><code>sequence.hpp</code></td>
<td>Contains #fcppt::optional::sequence .</td>
</tr>
<tr>
<td><code>to_exception.hpp</code></td>
<td>Contains #fcppt::optional::to_exception .</td>
</tr>
</table>
*/
