namespace fcppt
{
/**
\brief Contains fcppt::either::object and helper types/functions for it
*/
namespace either
{
}
}

/**
\defgroup fcppteither fcppt.either
\ingroup fcpptmain
\brief An optional with an error type

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

<ul>
	<li>\ref either_motivation</li>
	<li>\ref either_operations</li>
	<li>\ref either_error</li>
	<li>\ref either_headers</li>
</ul>

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

\section either_motivation Motivation

The downside of exceptions, which are the usual way to handle errors in C++, is that they do not appear in the type system.
If a function changes which exceptions it throws, all the code that uses the function will still compile.
This can make keeping track of which errors to handle where extremely difficult.
Instead of having a function that throws an exception, i.e.

\snippet either.cpp either_motivation_exception

we can move the exception into the return type instead, like so:

\snippet either.cpp either_motivation_either

In the first example, where the exception is used, a caller has to know that such an exception may be thrown and catch it.

\snippet either.cpp either_motivation_exception_call

In the second example, where the either is used, we cannot ignore that an error can occur.
The simplest way to deconstruct an <code>either<F,S></code> is to call the #fcppt::either::match function.
It gets two lambdas, where the first one receives <code>F</code>
and the second one receives <code>S</code>.

\snippet either.cpp either_motivation_either_call

In general, an <code>either<F,S></code> is basically the same as a <code>std::variant<F,S></code>
but with additional meaning assigned to <code>F</code> and <code>S</code>.
This becomes apparant in functions like #fcppt::either::map, #fcppt::either::apply and #fcppt::either::bind.

\note Either does not make exceptions obsolete. They are still crucial to implement RAII,
and there might be cases where it is simply not desired to make an error explicit in the type system.

\section either_operations Operations

The simplest operation on eithers is #fcppt::either::map.
It allows us to transform the success value while keeping the error value.
For example, consider a function that might return an int, which we want to transform into a string.
This can be done as follows:

\snippet either.cpp either_map

We often have to chain multiple eithers together.
For example, if we want to call two functions, each of which can fail, we only want to produce
a result if both succeeed.
This can be done with #fcppt::either::apply.

\snippet either.cpp either_apply

Note that since #fcppt::either::apply is a variadic template, so it can work on arbitrarly many eithers,
the function is its first parameter.

Another, even more basic operation, is #fcppt::either::bind.
As an example, let us look at how reading from a <code>std::istream</code> would work using eithers.
Consider a function that tries to read an int and if that succeeds tries to read a string.

\snippet either.cpp either_read_raw

First note that the function reading from the stream, which is <code>operator>> </code>,
uses a reference parameter to store its result.
Since <code>operator>></code> returns a reference to <code>_stream</code>,
the expression <code>!(_stream >> something)</code> checks if reading <code>something</code>
produced an error. If that is the case, we cannot use the stream to read more data,
and we need to abort early.

To do this with eithers instead, first, let us encapsulate reading a single value in a template function
which returns an either.

\snippet either.cpp either_read

Then, we can use this function to read the two eithers in succession,
which is done using #fcppt::either::bind.

\snippet either.cpp either_read_bind

Note that the difference to using #fcppt::either::apply is that the second operation
is not done if the first one returned an error.
Unfortunately, chaining more of these operations together creates more and more nested code.
In other programming languages like Haskell, there is special notation to bring every operation
on the same indentation level, called the \em Do-Notation.

If at some point you want to turn an either back into an exception, you can use #fcppt::either::to_exception.

\snippet either.cpp either_to_exception

\section either_error Errors

When functions return optional errors but <em>no success</em> values, it can be more
convenient to handle such cases as eithers. An #fcppt::either::error
is an either with a success type that only has one value, which is
#fcppt::unit. For example:

\snippet either.cpp either_error

\section either_headers Header files

<table>
<tr>
<th>Header file</th>
<th>Description</th>
</tr>
<tr>
<td><code>object_fwd.hpp</code></td>
<td>Contains #fcppt::either::object either's  declaration.</td>
</tr>
<tr>
<td><code>object_decl.hpp</code></td>
<td>Contains #fcppt::either::object either's  definition.</td>
</tr>
<tr>
<td><code>object_impl.hpp</code></td>
<td>Contains the definition of #fcppt::either::object either'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>apply.hpp</code></td>
<td>Contains #fcppt::either::apply.</td>
</tr>
<tr>
<td><code>bind.hpp</code></td>
<td>Contains #fcppt::either::bind.</td>
</tr>
<tr>
<td><code>comparison.hpp</code></td>
<td>Contains <code>operator==</code> and <code>operator!=</code>.</td>
</tr>
<tr>
<td><code>error_fwd.hpp</code></td>
<td>Contains #fcppt::either::error error's  declaration.</td>
</tr>
<tr>
<td><code>error.hpp</code></td>
<td>Contains #fcppt::either::error error's  definition.</td>
</tr>
<tr>
<td><code>error_from_optional.hpp</code></td>
<td>Contains #fcppt::either::error_from_optional.</td>
</tr>
<tr>
<td><code>failure_opt.hpp</code></td>
<td>Contains #fcppt::either::failure_opt.</td>
</tr>
<tr>
<td><code>first_success.hpp</code></td>
<td>Contains #fcppt::either::first_success.</td>
</tr>
<tr>
<td><code>from_optional.hpp</code></td>
<td>Contains #fcppt::either::from_optional.</td>
</tr>
<tr>
<td><code>make_failure.hpp</code></td>
<td>Contains #fcppt::either::make_failure.</td>
</tr>
<tr>
<td><code>make_success.hpp</code></td>
<td>Contains #fcppt::either::make_success.</td>
</tr>
<tr>
<td><code>map.hpp</code></td>
<td>Contains #fcppt::either::map.</td>
</tr>
<tr>
<td><code>map_failure.hpp</code></td>
<td>Contains #fcppt::either::map_failure.</td>
</tr>
<tr>
<td><code>match.hpp</code></td>
<td>Contains #fcppt::either::match.</td>
</tr>
<tr>
<td><code>no_error_fwd.hpp</code></td>
<td>Contains #fcppt::either::no_error no_error's  declaration.</td>
</tr>
<tr>
<td><code>no_error.hpp</code></td>
<td>Contains #fcppt::either::no_error no_error's  definition.</td>
</tr>
<tr>
<td><code>output.hpp</code></td>
<td>Contains <code>operator<<</code>.</td>
</tr>
<tr>
<td><code>sequence.hpp</code></td>
<td>Contains #fcppt::either::sequence.</td>
</tr>
<tr>
<td><code>sequence_error.hpp</code></td>
<td>Contains #fcppt::either::sequence_error.</td>
</tr>
<tr>
<td><code>success_opt.hpp</code></td>
<td>Contains #fcppt::either::success_opt.</td>
</tr>
<tr>
<td><code>to_exception.hpp</code></td>
<td>Contains #fcppt::either::to_exception.</td>
</tr>
<tr>
<td><code>try_call.hpp</code></td>
<td>Contains #fcppt::either::try_call.</td>
</tr>
</table>
*/
