expected-proposal.tex

\documentclass[a4paper,10pt]{article}
\usepackage[american]
           {babel} % needed for iso dates
\usepackage{url}
\usepackage{lmodern}
\usepackage{listings}
\usepackage{graphicx}
\usepackage{xcolor}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{hyperref}
\usepackage{array}
\usepackage{underscore}
\usepackage{changepage}   % for the adjustwidth environment
\usepackage{verbatim}     % improved verbatim environment
\usepackage{alltt}

\usepackage[top=2cm, bottom=2cm, left=2cm, right=2cm]{geometry}

\usepackage{color}
\usepackage{textpos}
\usepackage{titling}
\usepackage{titlesec}

\hypersetup{
  hidelinks
}

\setcounter{secnumdepth}{6}

% From std draft
% We use the 'listings' package, with some small customizations.  The
% most interesting customization: all TeX commands are available
% within comments.  Comments are set in italics, keywords and strings
% don't get special treatment.
% General code style
\lstset{language=C++,
        basicstyle=\small\ttfamily,
        keywordstyle=,
        stringstyle=,
        xleftmargin=1em,
        showstringspaces=false,
        commentstyle=\itshape\rmfamily,
        columns=flexible,
        keepspaces=true,
        texcl=true
}
% end from std draft
\definecolor{dkgreen}{rgb}{0,0.6,0}
\definecolor{update_color}{cmyk}{0.1,0,0.1,0}
\definecolor{suppress_color}{cmyk}{0,0.1,0,0}

\newcommand{\wordingSec}[2]{\vspace{15pt}
\noindent
{\large\textbf{X.Y\quad #1\hfill\textbf{[#2]}}}
}

% Counters
\newcounter{countWordingSubSec}
\newcounter{countWordingSubSubSec}[countWordingSubSec]

\renewcommand{\thecountWordingSubSec}{X.Y.\arabic{countWordingSubSec}}
\renewcommand{\thecountWordingSubSubSec}{X.Y.\arabic{countWordingSubSec}.\arabic{countWordingSubSubSec}}

% Defs of sub and subsub section (for the wording).
\newcommand{\wordingSubSec}[2]{\vspace{15pt}
\refstepcounter{countWordingSubSec}
\noindent
{\textbf{\thecountWordingSubSec\quad #1\hfill\textbf{[#2]}}}
\label{#2}
\vspace{7pt}
}

\newcommand{\wordingSubSubSec}[2]{\vspace{15pt}
\refstepcounter{countWordingSubSubSec}
\noindent
{\textbf{\thecountWordingSubSubSec\quad #1\hfill\textbf{[#2]}}}
\label{#2}
\vspace{7pt}
}

\newcommand{\cpp}[1]{\lstinline{#1}}

\newcommand{\todo}[1]{\emph{\textcolor{red}{TODO: #1}}}

% Wording items
\newcommand{\wordingItem}[1]{\noindent\textit{#1:}}

\newenvironment{wordingTextItem}[1]{\wordingItem{#1}\vspace{2pt}\noindent\begin{adjustwidth}{12pt}{}}{\vspace{2pt}\end{adjustwidth}}

\newenvironment{wordingNoteItem}{[\wordingItem{Note}}{---\textit{end note}]}

\newenvironment{wordingPara}{\begin{adjustwidth}{12pt}{}}{\end{adjustwidth}}

\lstset{
  xleftmargin=12pt
}

\newcommand{\add}[1]{\textcolor{dkgreen}{#1}}
\newcommand{\suppress}[1]{\colorbox{suppress_color}{#1}}
\newcommand{\update}[1]{\colorbox{update_color}{#1}}

\setlength{\droptitle}{10em}
\title{A proposal to add a utility class to represent expected monad - Revision 2}
\author{}
\date{}

\begin{document}

\maketitle
\begin{textblock*}{9cm}(7cm,-8cm)
\begin{tabular}{l l}
\textbf{Document number:} & DXXXX \\
\textbf{Date:}  & 2014-10-23 \\
\textbf{Revises:} & N4109 \\
\textbf{Project:} & JTC1.22.32 Programming \\
 & Language C++ \\
 & Library Evolution Working Group \\
\textbf{Reply to:} & Vicente J. Botet Escriba \\
 & <\href{mailto:vicente.botet@wanadoo.fr}{vicente.botet@wanadoo.fr}> \\
 & Pierre Talbot <\href{mailto:ptalbot@hyc.io}{ptalbot@hyc.io}>
\end{tabular}
\end{textblock*}

\vspace{-6em}
\setcounter{tocdepth}{1}
\tableofcontents

\section{History}
\label{history}
%%%%%%%%

\begin{itemize}
\item R2- Revision of N4109 \cite{ExpectedR1} after mailing list feedback: 
\begin{itemize}
\item Fix default constructor wording to default to \cpp{make_unexpected({E})}, add the alternative to default construct to \cpp{{T}} on the rationale and add an open point on how the default constructor must behave.
\end{itemize}
\item R1- Revision of N4015 \cite{ExpectedR0} after Rapperswil feedback: 
\begin{itemize}
\item Switch the \cpp{expected} class template parameter order from \cpp{expected<E,T>} to \cpp{expected<T,E>}.
\item Make the unexpected value a salient attribute of the \cpp{expected} class concerning the relational operators.
\item Removed open point about making \cpp{expected<T,E>} and \cpp{expected<T>} different classes.
\end{itemize}
\end{itemize}

\section{Introduction}
%%%%%%%%%%%

Class template \cpp{expected<T,E>} proposed here is a type that may contain a value of type \cpp{T} or a value of type \cpp{E} in its storage space. \cpp{T} represents the expected value, \cpp{E} represents the reason explaining why it doesn't contains a value of type \cpp{T}, that is the unexpected value. Its interface allows to query if the underlying value is either the expected value (of type \cpp{T}) or an unexpected value (of type \cpp{E}). The original idea comes from Andrei Alexandrescu C++ and Beyond 2012: Systematic Error Handling in C++ talk \cite{AlexandrescuExpected}. The interface and the rational are based on \cpp{std::optional} N3793 \cite{OptionalRev5} and Haskell monads. We can consider that \cpp{expected<T,E>} is a generalization of \cpp{optional<T>} providing in addition a monad interface and some specific functions associated to the unexpected type \cpp{E}. It requires no changes to core language, and breaks no existing code.

\section{Motivation and Scope}
\label{motiv-scope}
%%%%%%%%%%%%%%%%

Basically, the two main error mechanisms are exceptions and return codes. Before further explanation, we should ask us what are the characteristics of a good error mechanism.

\begin{itemize}
 \item \textbf{Error visibility} Failure cases should appears throughout the code review. Because the debug can be painful if the errors are hidden.
 \item \textbf{Information on errors} The errors should carry out as most as possible information from their origin, causes and possibly the ways to resolve it.
 \item \textbf{Clean code} The treatment of errors should be in a separate layer of code and as much invisible as possible. So the code reader could notice the presence of exceptional cases without stop his reading.
 \item \textbf{Non-Intrusive error} The errors should not monopolize a communication channel dedicated to the normal code flow. They must be as discrete as possible. For instance, the return of a function is a channel that should not be exclusively reserved for errors.
\end{itemize}

The first and the third characteristic seem to be quite contradictory and deserve further explanation. The former points out that errors not handled should appear clearly in the code. The latter tells us that the error handling mustn't interfere with the code reading, meaning that it clearly shows the normal execution flow. A comparison between the exception and return codes is given in the table \ref{comp-handling-error}.

\begin{table}[h!]
\centering
\bgroup
\def\arraystretch{1.5}
\begin{tabular}{|l|>{\raggedright\arraybackslash}p{5cm}|>{\raggedright\arraybackslash}p{5cm}|}
\hline
                    & \textbf{Exception} & \textbf{Return code} \\
\hline
\textbf{Visibility} & Not visible without further analysis of the code. However, if an exception is thrown, we can follow the stack trace. & Visible at the first sight by watching the prototype of the called function. However ignoring return code can lead to undefined results and it can be hard to figure out the problem. \\
\hline
\textbf{Informations} & Exceptions can be arbitrarily rich. & Historically a simple integer. Nowadays, the header \cpp{<system_error>} provides richer error code. \\
\hline
\textbf{Clean code} & Provides clean code, exceptions can be completely invisible for the caller. & Force you to add, at least, a if statement after each function call. \\
\hline
\textbf{Non-Intrusive} & Proper communication channel. & Monopolization of the return channel. \\
\hline
\end{tabular}
\egroup
\caption{Comparison between two error handling systems.}
\label{comp-handling-error}
\end{table}

\subsection{Expected class}
%%%%%%%%%%%%%%%%%%%%

We can do the same analysis for the \cpp{expected<T, E>} class and observe the advantages over the classic error reporting systems.

\begin{itemize}
 \item \textbf{Error visibility} It takes the best of the exception and error code. It's visible because the return type is \cpp{expected<T, E>} and the user cannot ignore the error case if he wants to retrieve the contained value.
 \item \textbf{Information} Arbitrarily rich.
 \item \textbf{Clean code} The monadic interface of expected provides a framework delegating the error handling to another layer of code. Note that \cpp{expected<T, E>} can also act as a bridge between an exception-oriented code and a nothrow world.
 \item \textbf{Non-Intrusive} Use the return channel without monopolizing it.
\end{itemize}

\noindent
It worths mentioning the other characteristics of \cpp{expected<T, E>}:

\begin{itemize}
 \item Associates errors with computational goals.
 \item Naturally allows multiple errors inflight.
 \item Teleportation possible.
 \begin{itemize}
  \item Across thread boundaries.
  \item Across nothrow subsystem boundaries.
  \item Across time: save now, throw later.
 \end{itemize}
 \item Collect, group, combine errors.
\end{itemize}

\section{Use cases}
%%%%%%%%%%

\subsection{Safe division}
\label{divide-example}
%%%%%%%%%%%

This example shows how to define a safe divide operation checking for divide-by-zero conditions. Using exceptions, we might write something like this:

\begin{lstlisting}
struct DivideByZero: public std::exception {...};

double safe_divide(double i, double j)
{
  if (j==0) throw DivideByZero();
  else return i / j;
}
\end{lstlisting}

With \cpp{expected<T,E>}, we are not required to use exceptions, we can use \cpp{std::error_condition} which is easier to introspect than \cpp{std::exception_ptr} if we want to use the error. For the purpose of this example, we use the following enumeration (the boilerplate code concerning \cpp{std::error_condition} is not shown):

\begin{lstlisting}
enum class arithmetic_errc
{
  divide_by_zero,   // 9/0 == ?
  not_integer_division  // 5/2 == 2.5 (which is not an integer)
};
\end{lstlisting}

\noindent
Using \cpp{expected<double, error_condition>}, the code becomes:

\begin{lstlisting}
expected<double,error_condition> safe_divide(double i, double j)
{
  if (j==0) return make_unexpected(arithmetic_errc::divide_by_zero); // (1)
  else return i / j; // (2)
}
\end{lstlisting}

(1) The implicit conversion from \cpp{unexpected_type<E>} to \cpp{expected<T,E>} and (2) from \cpp{T} to \cpp{expected<T,E>} prevents using too much boilerplate code. The advantages are that we have a clean way to fail without using the exception machinery, and we can give precise information about why it failed as well. The liability is that this function is going to be tedious to use. For instance, the exception-based function $i + j/k$ is:

\begin{lstlisting}
double f1(double i, double j, double k)
{
  return i + safe_divide(j,k);
}
\end{lstlisting}

\noindent
but becomes using \cpp{expected<double, error_condition>}:

\begin{lstlisting}
expected<double, error_condition> f1(double i, double j, double k)
{
  auto q = safe_divide(j, k)
  if(q) return i + *q;
  else return q;
}
\end{lstlisting}

\noindent
This example clearly doesn't respect the ``clean code'' characteristic introduced in section \ref{motiv-scope} and the readability doesn't differ much from the ``C return code''. Hopefully, we can see \cpp{expected<T,E>} through functional glasses as a monad. The code is cleaner using the member function \cpp{map}. This way, the error handling is not explicitly mentioned but we still know, thanks to the call to \cpp{map}, that something is going underneath and thus it is not as silent as exception.

\begin{lstlisting}
expected<double, error_condition> f1(double i, double j, double k)
{
  return safe_divide(j, k).map([&](double q){
    return i + q;
  });
}
\end{lstlisting}

The \cpp{map} member calls the continuation provided if expected contains a value, otherwise it forwards the error to the callee. Using lambda function might clutter the code, so here the same example using functor:

\begin{lstlisting}
expected<double, error_condition> f1(double i, double j, double k)
{
  return safe_divide(j, k).map(bind(plus, i, _1));
}
\end{lstlisting}

We can use \cpp{expected<T, E>} to represent different error conditions. For instance, with integer division, we might want to fail if the two numbers are not evenly divisible as well as checking for division by zero. We can overload our \cpp{safe_divide} function accordingly:

\begin{lstlisting}
expected<int, error_condition> safe_divide(int i, int j)
{
  if (j == 0) return make_unexpected(arithmetic_errc::divide_by_zero); 
  if (i%j != 0) return make_unexpected(arithmetic_errc::not_integer_division);
  else return i / j;
}
\end{lstlisting}

Now we have a division function for integers that possibly fail in two ways. We continue with the exception-oriented function $i/k + j/k$:

\begin{lstlisting}
int f2(int i, int j, int k)
{
  return safe_divide(i,k) + safe_divide(j,k);
}
\end{lstlisting}

\noindent
Now let's write this code using an \cpp{expected<T,E>} type and the functional \cpp{map} already used previously.

\begin{lstlisting}
expected<int,error_condition> f(int i, int j, int k)
{
  return safe_divide(i, k).map([=](int q1) {
      return safe_divide(j,k).map([=](int q2) {
        return q1+q2;
      });
    });
}
\end{lstlisting}

The compiler will gently say he can convert an \cpp{expected<expected<int, error_condition>, error_condition>} to \cpp{expected<int, error_condition>}. This is because the member \cpp{map} wraps the result in \cpp{expected} and since we use twice the \cpp{map} member it wraps it twice. The \cpp{bind}\footnote{To not confound with \cpp{std::bind} which is not related to monad.} member wraps the result of the continuation only if it is not already wrapped. The correct version is as follow:

\begin{lstlisting}
expected<int, error_condition> f(int i, int j, int k)
{
  return safe_divide(i, k).bind([=](int q1) {
      return safe_divide(j,k).map([=](int q2) {
        return q1+q2;
      });
    });
}
\end{lstlisting}

The error-handling code has completely disappeared but the lambda functions are a new source of noise, and this is even more important with $n$ expected variables. Propositions for a better monadic experience are discussed in section \ref{better-support-for-monad}, the subject is left open and is considered out of scope of this proposal.

\subsection{Error retrieval and correction}
%%%%%%%%%%%%%%%%

The major advantage of \cpp{expected<T,E>} over \cpp{optional<T>} is the ability to transport an error, but we didn't come yet to an example that retrieve the error. First of all, we should wonder what a programmer do when a function call returns an error:

\begin{enumerate}
 \item Ignore it.
 \item Delegate the responsibility of error handling to higher layer.
 \item Trying to resolve the error.
\end{enumerate}

Because the first behavior might lead to buggy application, we won't consider it in a first time. The handling is dependent of the underlying error type, we consider the \cpp{exception_ptr} and the \cpp{error_condition} types.

We spoke about how to use the value contained in the Expected but didn't discuss yet the error usage. A first imperative way to use our error is to simply extract it from the Expected using the \cpp{error()} member function. The following example shows a \cpp{divide2} function that return 0 if the error is \cpp{divide_by_zero}:

\begin{lstlisting}
expected<int, error_condition> divide2(int i, int j)
{
  auto e = safe_divide(i,j);
  if (!e && e.error().value() == arithmetic_errc::divide_by_zero) {
    return 0;
  }
  return e;
}
\end{lstlisting}

This imperative way is not entirely satisfactory since it suffers from the same disadvantages than \cpp{value()}. Again, a functional view leads to a better solution. The \cpp{catch_error} member calls the continuation passed as argument if the expected is erroneous.

\begin{lstlisting}
expected<int, error_condition> divide3(int i, int j)
{
  auto e = safe_divide(i,j);
  return e.catch_error([](const error_condition& e){
    if(e.value() == arithmetic_errc::divide_by_zero)
    {
      return 0;
    }
    return make_unexpected(e);
  });
}
\end{lstlisting}

An advantage of this version is to be coherent with the \cpp{bind} and \cpp{map} functions. It also provides a more uniform way to analyze error and recover from some of these. Finally, it encourages the user to code its own ``error-resolver'' function and leads to a code with distinct treatment layers.

\section{Impacts on the Standard}
%%%%%%%%%%%%%%%%%

These changes are entirely based on library extensions and do not require any language features beyond what is available in C++ 14. It requires however the \cpp{in_place_t} from N3793.

\section{Design rationale}
%%%%%%%%%%%%%

The same rationale described in \cite{OptionalRev4} for \cpp{optional<T>} applies to \cpp{expected<T,E>} and \cpp{expected<T, nullopt_t>} should behave as \cpp{optional<T>}.  That is, we see \cpp{expected<T,E>} as \cpp{optional<T>} for which all the values of \cpp{E} collapse into a single value \cpp{nullopt}. In the following sections we present the specificities of the rationale in \cite{OptionalRev4} applied to  \cpp{expected<T,E>}.

\subsection{Conceptual model of \cpp{expected<T,E>}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%

\cpp{expected<T,E>} models a discriminated union of types \cpp{T} and \cpp{unexpected_type<E>}. \cpp{expected<T,E>} is viewed as a value of type \cpp{T} or value of type \cpp{unexpected_type<E>}, allocated in the same storage, along with the way of determining which of the two it is. 

The interface in this model requires operations such as comparison to \cpp{T}, comparison to \cpp{E}, assignment and creation from either. It is easy to determine what the value of the expected object is in this model: the type it stores (\cpp{T} or \cpp{E}) and either the value of \cpp{T} or the value of \cpp{E}. 

Additionally, within the affordable limits, we propose the view that \cpp{expected<T,E>} extends the set of the values of \cpp{T} by the values of type \cpp{E}. This is reflected in initialization, assignment, ordering, and equality comparison with both \cpp{T} and \cpp{E}. In the case of  \cpp{optional<T>}, \cpp{T} can not be a \cpp{nullopt_t}. As the types \cpp{T} and \cpp{E} could be the same in \cpp{expected<T,E>}, there is need to tag the values of \cpp{E} to avoid ambiguous expressions. The \cpp{make_unexpected(E)} function is proposed for this purpose. However \cpp{T} can not be  \cpp{unexpected_type<E>} for a given \cpp{E}.

\begin{lstlisting}
expected<int, string> ei = 0;
expected<int, string> ej = 1;
expected<int, string> ek = make_unexpected(string());

ei = 1;
ej = make_unexpected(E());;
ek = 0;

ei = make_unexpected(E());;
ej = 0;
ek = 1;
\end{lstlisting}

\subsection{Initialization of \cpp{expected<T,E>}}
%%%%%%%%%%%%%%%%%%%%%%%

In cases \cpp{T} and \cpp{E} are value semantic types capable of storing \cpp{n} and \cpp{m} distinct values respectively, \cpp{expected<T,E>} can be seen as an extended \cpp{T} capable of storing \cpp{n + m} values: these that \cpp{T} and \cpp{E} stores. Any valid initialization scheme must provide a way to put an expected object to any of these states. In addition, some \cpp{T}'s  are not \cpp{CopyConstructible} and their expected variants still should be constructible with any set of arguments that work for \cpp{T}.

\noindent
As in \cite{OptionalRev4}, the model retained is to initialize either by providing an already constructed \cpp{T} or a tagged \cpp{E}. The default constructor required \cpp{E} to be default-constructible (which is more likely to happen than \cpp{T}).

\begin{lstlisting}
string s{"STR"};

expected<string, error_condition> es{s};              // requires Copyable<T>
expected<string, error_condition> et = s;             // requires Copyable<T>
expected<string, error_condition> ev = string{"STR"}; // requires Movable<T>

expected<string, error_condition> ew;                 // unexpected value
expected<string, error_condition> ex{};               // unexpected value
expected<string, error_condition> ey = {};            // unexpected value
expected<string,error_condition> ez = expected<string,error_condition>{};  // unexpected value
\end{lstlisting}

\noindent
In order to create an unexpected object, the special function \cpp{make_unexpected} needs to be used:

\begin{lstlisting}
expected<string, int> ep{make_unexpected(-1)};    // unexpected value, requires Movable<E>
expected<string, int> eq = make_unexpected(-1);   // unexpected value, requires Movable<E>
\end{lstlisting}

\noindent
As in \cite{OptionalRev4}, and in order to avoid calling move/copy constructor of \cpp{T}, we use a ``tagged'' placement constructor: 

\begin{lstlisting}
expected<MoveOnly, error_condition> eg;                  // unexpected value
expected<MoveOnly, error_condition> eh{};                // unexpected value
expected<MoveOnly, error_condition> ei{in_place};        // calls MoveOnly{} in place
expected<MoveOnly, error_condition> ej{in_place, "arg"}; // calls MoveOnly{"arg"} in place
\end{lstlisting}

\noindent
To avoid calling move/copy constructor of \cpp{E}, we use a ``tagged'' placement constructor: 

\begin{lstlisting}
expected<int, string> ei{unexpect};         // unexpected value, calls string{} in place
expected<int, string> ej{unexpect, "arg"};  // unexpected value, calls string{"arg"} in place
\end{lstlisting}

\noindent
An alternative name for \cpp{in_place} that is coherent with \cpp{unexpect} could be \cpp{expect}. Being compatible with \cpp{optional<T>} seems more important. So this proposal doesn't propose such a \cpp{expect} tag.
\newline

The alternative and also comprehensive initialization approach, which is not compatible with the default construction of \cpp{expected<T,E>} to \cpp{E()}, could have been a variadic perfect forwarding constructor that just forwards any set of arguments to the constructor of the contained object of type \cpp{T}. 

\subsection{Almost never-empty guaranty}
%%%%%%%%%%%%%%%%%%

As \cpp{boost::variant<unexpected_type<E>,T>}, \cpp{expected<T,E>} ensures that it is never empty. All instances \cpp{v} of type \cpp{expected<T,E>} guarantee that \cpp{v} has constructed content of one of the types \cpp{T} or \cpp{E}, even if an operation on \cpp{v} has previously failed.

This implies that expected may be viewed precisely as a union of exactly its bounded types. This ``never-empty'' property insulates the user from the possibility of undefined expected content and the significant additional complexity-of-use attendant with such a possibility.

\subsubsection{The default constructor}
%%%%%%%%%%%%%%%%%%

Similar data structure includes \cpp{optional<T>}, \lstinline[mathescape]{variant<$T_1$,...,$T_n$>} and \cpp{future<T>}. We can compare how they are default constructed.
\begin{itemize}
\item \cpp{std::experimental::optional<T>} default constructs to an optional with no value. 
\item \lstinline[mathescape]{boost::variant<$T_1$,...,$T_n$>} default constructs to the first type default constructible or it is ill-formed if none are default constructible.
\item \cpp{std::future<T>} default constructs to an invalid future with no shared state associated, that is, no value and no exception.
\item \cpp{std::experimental::optional<T>} default constructor is equivalent to \cpp{boost::variant<nullopt_t, T>}.
\end{itemize}

\noindent
It raises several questions about \cpp{expected<T,E>}:

\begin{itemize}
\item Should the default constructor of \cpp{expected<T,E>} behave like \cpp{variant<T,E>} or as \cpp{variant<E,T>}?
\item Should the default constructor of \cpp{expected<T,E>} behave like \cpp{optional<variant<T,E>>}?
\item Should the default constructor of \cpp{expected<T, nullopt_t>} behave like \cpp{optional<T>}? If yes, how should behave the default constructor of \cpp{expected<T,E>}? As if initialized with \cpp{make_unexpected(E())}? This would be equivalent to the initialization of \cpp{variant<E,T>}.
\item Should \cpp{expected<T,E>} provide a default constructor at all? \cite{OptionalRev3} presents valid arguments against this approach, e.g. \cpp{array<expected<T,E>>} would not be possible. 
\end{itemize}

Requiring \cpp{E} to be default constructible seems less constraining than requiring \cpp{T} to be default constructible (e.g. consider the \cpp{Date} example in \cite{OptionalRev3}). With the same semantics \cpp{expected<Date,E>} would be \cpp{Regular} with a meaningful not-a-date state created by default.

There is still a minor issue as the default constructor of \cpp{std::exception_ptr} doesn't contains an exception and so getting the value of a default constructed \cpp{expected<T>} would need to check if the stored \cpp{std::exception_ptr} is equal to \cpp{std::exception_ptr()} and throw a specific exception.

The current proposal follows the  \cite{OptionalRev3} and so  \cpp{expected<T,E>} default constructor should behave as constructed with \cpp{make_unexpected(E())}.

However, as the goal of expected is to behave as much as possible as \cpp{T}, the authors consider that the alternative merits discussion: \cpp{expected<T,E>} should have a default constructor if and only if \cpp{T} is default-constructible, and if so, default construct to \cpp{T\{\}}. If \cpp{T} is not default constructible, the user will be free to wrap it inside an optional (\cpp{expected<optional<T>, E>}).

\subsubsection{Conversion from \cpp{T}}
%%%%%%%%%%%%%%%%%%

An object of type \cpp{T} is convertible to an expected object of type \cpp{expected<T,E>}:

\begin{lstlisting}
expected<int, error_condition> ei = 1; // works
\end{lstlisting}
\noindent
This convenience feature is not strictly necessary because you can achieve the same effect by using tagged forwarding constructor:

\begin{lstlisting}
expected<int, error_condition> ei{in_place, 1};
\end{lstlisting}
\noindent
If the latter appears too cumbersome, one can always use function \cpp{make_expected} described below:

\begin{lstlisting}
expected<int> ei = make_expected(1);
auto ej = make_expected(1); 
\end{lstlisting}

\subsubsection{Conversion from \cpp{E}}
%%%%%%%%%%%%%%%%%%

An object of type \cpp{E} is not convertible to an unexpected object of type \cpp{expected<T,E>} since \cpp{E} and \cpp{T} can be of the same type. The proposed interface uses a special tag \cpp{unexpect} and a special non-member \cpp{make_unexpected} function to indicate an unexpected state for \cpp{expected<T,E>}. It is used for construction and assignment. This might rise a couple of objections. First, this duplication is not strictly necessary because you can achieve the same effect by using the \cpp{unexpect} tagged forwarding constructor:

\begin{lstlisting}
expected<string, int> exp1 = make_unexpected(1); 
expected<string, int> exp2 = {unexpect, 1};

exp1 = make_unexpected(1);
exp2 = {unexpect, 1};

\end{lstlisting}
\noindent
While some situations would work with the \cpp{\{unexpect, ...\}} syntax, using \cpp{make_unexpected} makes the programmer's intention as clear and less cryptic. Compare these:

\begin{lstlisting}
expected<vector<int>, int> get1() {
  return {unexpect, 1};
}

expected<vector<int>, int> get2() {
  return make_unexpected(1);
}

expected<vector<int>, int> get3() {
  return expected<vector<int>, int>{unexpect, 1};
}
\end{lstlisting}

The usage of \cpp{make_unexpected} is also a consequence of the adapted model for expected: a discriminated union of \cpp{T} and \cpp{unexpected_type<E>}. While \cpp{make_unexpected(E)} has been chosen because it clearly indicates that we are interested in creating an unexpected \cpp{expected<T,E>} (of unspecified type \cpp{T}), it could be also used to make a ready future with a specific error, but this is outside the scope of this proposal. Note also that the definition of the result type of \cpp{make_unexpected} has an explicitly deleted default constructor. This is in order to enable the reset idiom \cpp{exp2 = \{\}} which would otherwise not work due to the ambiguity when deducing the right-hand side argument.

\subsection{Observers}
%%%%%%%%%%%%%%%%%%

In order to be as efficient as possible, this proposal includes observers with narrow and wide contracts. Thus, the \cpp{value()} function has a wide contract. If the expected object doesn't contain a value, an exception is thrown. However, when the user knows that the expected object is valid, the use of \cpp{operator*} would be more appropriated. 

\subsubsection{Explicit conversion to \cpp{bool}}
%%%%%%%%%%%%%%%%%%

The rational described in \cite{OptionalRev4} for \cpp{optional<T>} applies to \cpp{expected<T,E>} and so, the following example combines initialization and value-checking in a boolean context.

\begin{lstlisting}
if (expected<char, error_condition> ch = readNextChar()) {
  // ...
}
\end{lstlisting}

\subsubsection{Accessing the contained value}
%%%%%%%%%%%%%%%%%%

Even if \cpp{expected<T,E>} has not been used in practice for a while as Boost.Optional, we consider that following the same interface that \cpp{std::experimental::optional<T>} makes the C++ standard library more homogeneous. The rational described in \cite{OptionalRev4} for \cpp{optional<T>} applies to \cpp{expected<T,E>}. 

\subsubsection{Dereference operator}
%%%%%%%%%%%%%%%%%%

It was chosen to use indirection operator because, along with explicit conversion to \cpp{bool}, it is a very common pattern for accessing a value that might not be there:

\begin{lstlisting}
if (p) use(*p);
\end{lstlisting}

This pattern is used for all sort of pointers (smart or raw) and \cpp{optional}; it clearly indicates the fact that the value may be missing and that we return a reference rather than a value. The indirection operator has risen some objections because it may incorrectly imply that \cpp{expected} and \cpp{optional} are a (possibly smart) pointer, and thus provides shallow copy and comparison semantics. All library components so far use indirection operator to return an object that is not part of the pointer's/iterator's value. In contrast, \cpp{expected} as well as \cpp{optional} indirects to the part of its own state. We do not consider it a problem in the design; it is more like an unprecedented usage of indirection operator. We believe that the cost of potential confusion is overweighted by the benefit of an intuitive interface for accessing the contained value.

We do not think that providing an implicit conversion to \cpp{T} would be a good choice. First, it would require different way of checking for the empty state; and second, such implicit conversion is not perfect and still requires other means of accessing the contained value if we want to call a member function on it.

Using the indirection operator for a object that doesn't contain a value is an undefined behavior. This behavior offers maximum runtime performance.

\subsubsection{Function value}
%%%%%%%%%%%%%%%%%%

In addition to the indirection operator, we propose the member function value as in \cite{OptionalRev4} that returns a reference to the contained value if one exists or throw an exception otherwise.

\begin{lstlisting}
void interact() {
  string s;
  cout << "enter number: ";
  cin >> s;
  expected<int, error> ei = str2int(s);
  
  try {
    process_int(ei.value());
  }
  catch(bad_expected_access<error>) {
    cout << "this was not a number.";
  }
}
\end{lstlisting}

The exception thrown depend on the expected error type. By default it throws \cpp{bad_expected_access<E>} (derived from \cpp{logic_error}) which will contain the stored error. In the case of \cpp{expected<T>}, it throws the exception stored in the \cpp{exception_ptr}. An approach enabling customization of this behavior is presented in the section \ref{configurable-expected}.

\cpp{bad_expected_access<E>} and \cpp{bad_optional_access} could inherit both from a \cpp{bad_access} exception derived from \cpp{logic_error}, but this is not proposed.

\subsubsection{Accessing the contained error}
%%%%%%%%%%%%%%%%%%%%%%%

Usually, accessing the contained error is done once we know the expected object has no value. This is why the \cpp{error()} function has a narrow contract: it works only if \cpp{!(*this)}.

\begin{lstlisting}
expected<int, errc> getIntOrZero(istream_range& r) {
  auto r = getInt();  // won't throw
  if (!r && r.error() == errc::empty_stream) {
    return 0;
  }
  return r;
}
\end{lstlisting}

\noindent
This behavior could not be obtained with the \cpp{value_or()} method since we want to return 0 only if the error is equal to \cpp{empty_stream}.

\subsubsection{Conversion to the unexpected value}
%%%%%%%%%%%%%%%%%%

As the \cpp{error()} function, the \cpp{get_unexpected()} works only if the expected object has no value. It is used to propagate errors. Note that the following equivalences yield:

\begin{lstlisting}
f.get_unexpected() == make_unexpected(f.error());
f.get_unexpected() == expected<T, E>{unexpect, f.error()};
\end{lstlisting}

\noindent
This member is provided for convenience, it is further demonstrated in the next example:

\begin{lstlisting}
expected<pair<int, int>, errc> getIntRange(istream_range& r) {
  auto f = getInt(r);
  if (!f) return f.get_unexpected();

  auto m = matchedString("..", r);
  if (!m) return m.get_unexpected();

  auto l = getInt(r);
  if (!l) return l.get_unexpected();

  return std::make_pair(*f, *l);
}
\end{lstlisting}

\cpp{get_unexpected} is also provided for symmetry purpose. On one side, there is an implicit conversion from \cpp{unexpected<E>} to \cpp{expected<T,E>} and on the other side there is an explicit conversion from \cpp{expected<T,E>} to \cpp{unexpected<E>}. A more pleasant function manipulating error is \cpp{catch_error(F)} and is explained in the monadic operations in section \ref{monadic-operations}.

\subsubsection{Function \cpp{value_or}}
%%%%%%%%%%%%%%%%%%

The function member \cpp{value_or()} has the same semantics than \cpp{optional}\cite{OptionalRev4} since the type of \cpp{E} doesn't matter; hence we can consider that \cpp{E == nullopt_t} and the optional semantics yields. Using the monadic interface, we can achieve a similar behavior:

\begin{lstlisting}
auto x = getInt();
int x = *(x.catch_error([](auto){return 0;})); // identical to x.value_or(0);
\end{lstlisting}

\subsubsection{Relational operators}
%%%%%%%%%%%%%%%%%%

As \cpp{optional}, one of the design goals of \cpp{expected} is that objects of type \cpp{expected<T,E>} should be valid elements in STL containers and usable with STL algorithms (at least if objects of type \cpp{T} and \cpp{E} are). Equality comparison is essential for \cpp{expected<T,E>} to model concept \cpp{Regular}. C++ does not have concepts, but being regular is still essential for the type to be effectively used with STL. Ordering is essential if we want to store expected values in ordered associative containers. A number of ways of including the unexpected state in comparisons have been suggested. The ones proposed, have been crafted such that the axioms of equivalence and strict weak ordering are preserved: unexpected values stored in \cpp{expected<T,E>} are simply treated as additional values that are always different from \cpp{T}; these values are always compared as less than any value of \cpp{T} when stored in an expected object. 

The main issue is how to compare the unexpected values between them.  \cpp{operator==()} is defined for \cpp{exception_ptr}, using shallow semantics but there is no order between two \cpp{exception_ptr}.

\begin{lstlisting}
template <class T, class E>
constexpr bool operator<(const expected<T,E>& x, const expected<T,E>& y)
{
  return (x)
       ? (y) ? *x < *y : false
       : (y) ? true : ?<?;
}

template <class T, class E>
constexpr bool operator==(const expected<T,E>& x, const expected<T,E>& y)
{
    return (x)
         ? (y) ? *x == *y : false
         : (y) ? false : ?==?;
}
\end{lstlisting}

If we follow the \cpp{optional<T>} semantics, two unexpected values should always be equal and do not compare. That is, \cpp{?<?} should be substituted by \cpp{false} and \cpp{?==?} by \cpp{true}. However considering all the unexpected value equals seems counterintuitive.

The alternative consists in forwarding the request to the respective  \cpp{unexpected_type<E>} relational operators. That is, \cpp{?<?} should be substituted by \cpp{x.get_unexpected() < y.get_unexpected()} and \cpp{?==?} by \cpp{x.get_unexpected()} \cpp{== y.get_unexpected()}. 

But how to define the relational operators for \cpp{unexpected_type<E>}? We can forward the request to the respective \cpp{E} relational operators when \cpp{E} defines these operators and follows the \cpp{optional<T>} semantics otherwise. 

The case of \cpp{unexpected_type<std::exception_ptr>} could follow the \cpp{optional<T>} semantics as the shallow comparison is not very useful.

This limitation is one of the main motivations for having a user defined type with strict weak ordering. E.g. if the user know the exact types of the exceptions that can be thrown \cpp{E1}, ..., \cpp{En}, the error parameter could be some kind of \cpp{variant<E1, ... En>} for which a strict weak ordering can be defined. If the user would like to take care of unknown exceptions something like \cpp{optional<variant<E1, ... En>>} would be a quite appropriated model. 

\begin{lstlisting}
expected<unsigned, int> e0{0};
expected<unsigned, int> e1{1};
expected<unsigned, int> eN{unexpect, -1};

assert (eN < e0);
assert (e0 < e1);
assert (!(eN  < eN));
assert (!(e1 < e1))

assert (eN != e0);
assert (e0 != e1);
assert (eN == eN);
assert (e0 == e0);
\end{lstlisting}

Unexpected values could have been as well considered greater than any value of \cpp{T}. The choice is a great degree arbitrary. We choose to stick to what \cpp{std::optional} does.

Given that both \cpp{unexpected_type<E>} and \cpp{T} are implicitly convertible to \cpp{expected<T,E>}, this implies the existence and semantics of mixed comparison between \cpp{expected<T,E>} and \cpp{T}, as well as between \cpp{expected<T,E>} and \cpp{unexpected_type<E>}:

\begin{lstlisting}
assert (e0 != make_unexpected(1));
assert (eN != 1);
assert (e1 == 1);

assert (eN < 1);
assert (e0 > make_unexpected(1));
\end{lstlisting}

Although it is difficult to imagine any practical use case of ordering relation between \cpp{expected<T,E>} and \cpp{unexpected_type<E>}, we still provide it for completness sake.

The mixed relational operators, especially those representing order, between \cpp{expected<T,E>} and \cpp{T} have been accused of being dangerous. In code examples like the following, it may be unclear if the author did not really intend to compare two \cpp{T}'s.

\begin{lstlisting}
auto count = get_expected_count();
if (count < 20) {}                        // or did you mean: *count < 20 ?
if (! count || *count < 20) {}   // verbose, but unambiguous
\end{lstlisting}

Given that \cpp{expected<T,E>} is comparable and implicitly constructible from \cpp{T}, the mixed comparison is there already. We would have to artificially create the mixed overloads only for them to cause controlled compilation errors. A consistent approach to prohibiting mixed relational operators would be to also prohibit the conversion from \cpp{T} or to also prohibit homogenous relational operators for \cpp{expected<T,E>} ; we do not want to do either, for other reasons discussed in this proposal. Also, mixed relational operations are available in \cpp{std::optional<T>} and we want to maintain the same behavior for \cpp{expected<T,nullopt_t>} and \cpp{optional<T>}. Mixed operators come as something natural when we consider the model "T with additional values".

For completeness sake, we also provide ordering relations between  \cpp{expected<T,E>} and  \cpp{unexpected_type<E>}, even though we see no practical use case for them:

\begin{lstlisting}
bool test(expected<unsigned, int> e)
{
  assert (e >= make_unexpected(1));    
  assert (!(e < make_unexpected(1)));  
  assert (make_unexpected(1) <= e);    
  return (e > make_unexpected(1));     
}
\end{lstlisting}

There exist two ways of implementing \cpp{operator>()} for expected objects: use \cpp{T::operator>()} or use \\
 \cpp{expected<T,E>::operator<()}

In case \cpp{T::operator>} and \cpp{T::operator<} are defined consistently, both above implementations are equivalent. If the two operators are not consistent, the choice of implementation makes a difference. 

For relational operations, we choose to implement all in terms of  \cpp{expected<T,E>::operator<()} to be consistent with the choice taken for \cpp{std::optional}.

The same applies to the relational operators for \cpp{unexpected_type<E>} .

\subsection{Modifiers}
%%%%%%%%%%%%%%%%%%

\subsubsection{Reseting the value}
%%%%%%%%%%%%%%%%%%

Reseting the value of \cpp{expected<T,E>} is similar to \cpp{optional<T>} but instead of building a disengaged \cpp{optional<T>}, we build a erroneous \cpp{expected<T,E>}. Hence, the semantics and rational is the same than in \cite{OptionalRev4}.

\subsubsection{Tag \cpp{in_place}}
%%%%%%%%%%%%%%%%%%

This proposal makes use of the "in-place" tag defined in \cite{OptionalRev5}. This proposal  provides the same kind of "in-place" constructor that forwards (perfectly) the arguments provided to \cpp{expected}'s constructor into the constructor of \cpp{T}. In order to trigger this constructor one has to use the tag struct \cpp{in_place}. We need the extra tag to disambiguate certain situations, like calling \cpp{expected}'s default constructor and requesting \cpp{T}'s default construction:

\begin{lstlisting}
expected<Big, error> eb{in_place, "1"}; // calls Big{"1"} in place (no moving)
expected<Big, error> ec{in_place};      // calls Big{} in place (no moving)
expected<Big, error> ed{};              // calls error{} (unexpected state)
\end{lstlisting}


\subsubsection{Tag \cpp{unexpect}}
%%%%%%%%%%%%%%%%%%

This proposal provides an "unexpect" constructor that forwards (perfectly) the arguments provided to \cpp{expected}'s constructor into the constructor of \cpp{E}. In order to trigger this constructor one has to use the tag struct \cpp{unexpect}. We need the extra tag to disambiguate certain situations, notably if \cpp{T == E}.

\begin{lstlisting}
expected<Big, error> eb{unexpect, "1"}; // calls error{"1"} in place (no moving)
expected<Big, error> ec{unexpect};      // calls error{} in place (no moving)
\end{lstlisting}

In order to make the tag uniform an additional "expect" constructor could be provided but this proposal doesn't propose it.

\subsubsection{Requirements on \cpp{T} and \cpp{E}}
%%%%%%%%%%%%%%%%%%

Class template \cpp{expected} imposes little requirements on \cpp{T} and \cpp{E}: they have to be  complete object type satisfying the requirements of \cpp{Destructible}. Each operations on \cpp{expected<T,E>} have different requirements and may be disable if \cpp{T} or \cpp{E} doesn't respect these requirements. For example, \cpp{expected<T,E>}'s move constructor requires that \cpp{T} and \cpp{E} are \cpp{MoveConstructible}, \cpp{expected<T,E>}'s copy constructor requires that \cpp{T} and \cpp{E} are \cpp{CopyConstructible}, and so on. This is because \cpp{expected<T,E>} is a wrapper for \cpp{T} or \cpp{E}: it should resemble \cpp{T} as much as possible. If \cpp{T} is \cpp{EqualityComparable} then (and only then) we expect \cpp{expected<T,E>} to be \cpp{EqualityComparable}. 

\subsubsection{Expected references}
%%%%%%%%%%%%%%%%%%

This proposal doesn't include expected references as \cpp{optional}\cite{OptionalRev5} doesn't include references neither.

\subsubsection{Expected void}
%%%%%%%%%%%%%%%%%%

While it could seem weird to instantiate optional with \cpp{void}, it has more sense for expected as it conveys in addition, as \cpp{future<T>}, an error state.

\subsection{Making \cpp{expected} a literal type}
%%%%%%%%%%%%%%%%%%

In \cite{OptionalRev4}, they propose to make \cpp{optional} a literal type, the same reasoning can be applied to \cpp{expected}. Under some conditions, such that \cpp{T} and \cpp{E} are trivially destructible, and the same described for \cpp{optional}, we propose that \cpp{expected} be a literal type.

\subsection{Moved from state}
%%%%%%%%%%%%%%%%%%

We follow the approach taken in \cpp{optional}\cite{OptionalRev4}. Moving \cpp{expected<T,E>} do not modify the state of the source (valued or erroneous) of \cpp{expected} and the move semantics is up to \cpp{T} or \cpp{E}.

\subsection{IO operations}
%%%%%%%%%%%%%%%%%%

For the same reasons than \cpp{optional}\cite{OptionalRev4} we do not add \cpp{operator<<} and \cpp{operator>>} IO operations.

\subsection{Monadic operations}
\label{monadic-operations}
%%%%%%%%%%

A monadic interface is not optional if we don't want to fall back in the problems of the old "C return code". The example section \ref{divide-example} shows how these operations are important to expected. The member function \cpp{map} and \cpp{bind} find their roots in the category theory if we consider \cpp{expected} as a functor and a monad.

\subsubsection{Functor \cpp{map}}

The operation \cpp{map} consider expected as a functor and just apply a function on the contained value, if any. The types of the two overloads are presented using a functional notation and the \cpp{[]} represent a context in which the value T or U is contained. The current context is \cpp{expected} and thus \cpp{[T]} is equivalent to \cpp{expected<T,E>}.

\begin{itemize}
\item \cpp{(T -> U) -> [U]}
\item \cpp{(T -> [U]) -> [[U]]}
\end{itemize}

Whatever the return type of the continuation, we observe that it is always wrapped into a context. The monadic bind do it differently.

\subsubsection{Monadic \cpp{bind}}

A monad is defined with a type constructor and two operations \cpp{return} and \cpp{bind}. The type constructor simply build a monad for a specific type, in the C++ jargon it is referred to template instantiation (we build \cpp{expected} from a type \cpp{Value} and \cpp{Error}).

The \cpp{return} operation wraps a value of type \cpp{T} inside a context \cpp{[T]}. In C++ we can consider the constructors as a \cpp{return} operation.

Finally, the \cpp{bind} operation is similar to \cpp{map} but doesn't wrap the value if the function already wraps it up. The functional signature of \cpp{bind} can be described as follow:

\begin{itemize}
\item \cpp{(T -> U) -> [U]}
\item \cpp{(T -> [U]) -> [U]}
\end{itemize}

If a do-notation is introduced in C++, as proposed in section \ref{better-support-for-monad}, these operations can become a powerful abstraction, they have been proven very useful in Haskell. For example, a similar interface could be used with \cpp{optional}..

\subsubsection{\cpp{then} operation}

The last operation has no direct counterpart in functional language and is inspired from \cite{ImprovementsAsync} proposing some improvements to \cpp{std::future<T>}. The functional signature is as follow:

\begin{itemize}
\item \cpp{([T] -> U) -> [U]}
\item \cpp{([T] -> [U]) -> [U]}
\end{itemize}

It has the same wrapping strategy than \cpp{bind}: it doesn't wrap if the continuation already wraps it up.

\subsubsection{Exception thrown in the continuation}

This behavior is left open in the section \ref{configurable-expected}. Currently, the exceptions thrown in the continuations are not caught.

\subsubsection{\cpp{catch_error} operation}

This last member function is used when we want to use or recover from an error. When chaining multiple \cpp{bind} or \cpp{map} operations we don't know if the operations have succeeded. A common way is thus to add a \cpp{catch_error} at the end and act in consequence.

\begin{lstlisting}
getInt().map([](int i){return i * 2;})
        .map(integer_divide_by_2)
        .catch_error(log_error);
\end{lstlisting}

\noindent
Here the last operation is simply used to log the error but the \cpp{catch_error} also accepts function that try to recover from a previous error.

\begin{lstlisting}
getInt().map([](int i){return i * 2;})
        .map(integer_divide_by_2)
        .catch_error([](auto e) { return 0; });
\end{lstlisting}
\noindent
This last example shows we can return a new value from the continuation passed to \cpp{catch_error}.
\newline

The \cpp{catch_error} member doesn't catch exceptions that could be thrown by the continuation. Since we already try to recover from an error it makes little sense to prevent the user to launch an exception.

\subsubsection{Function \cpp{unwrap}}
%%%%%%%%%%

In some scenarios, you might want to create an \cpp{expected} that returns another \cpp{expected}, resulting in nested expected. It is possible to write simple code to unwrap the outer \cpp{expected} and retrieve the nested \cpp{expected} and its result with the current interface as in:

\begin{lstlisting}
template <class T, class E>
expected<T,E> unwrap<expected<expected<T,E>,E> ee) {

  if (ee) return *ee;
  return ee.get_unexpected();
}
template <class T, class E>
expected<T,E> unwrap<expected<T,E>> e) { 
  return e;
}
\end{lstlisting}

We could add such a function to the standard, either as a free function or as a member function. The authors propose to add it as a member function to be in line with \cite{ImprovementsAsync}.

\section{Related types}
%%%%%%%%%%%

\subsection{Variant}
%%%%%%%%%%%%%%%%%%%%

\cpp{expected<T,E>} can be seen as a specialization of  \cpp{boost::variant<unexpected<E>,T>} which gives a specific intent to its second parameter, that is, it represents the type of the expected contained value. This specificity allows to provide a pointer like interface, as it is the case for \cpp{std::experimental::optional<T>}. Even if the standard included a class  \cpp{variant<T,E>}, the interface provided by \cpp{expected<T,E>} is more specific and closer to what the user could expect as the result type of a function. In addition, \cpp{expected<T,E>} doesn't intend to be used to define recursive data as \cpp{boost::variant<>} does.

The table \ref{comp-variant} presents a brief comparison between \cpp{boost::variant<unexpected<E>, T>} and \cpp{expected<T,E>}.

\begin{table}[h!]
\bgroup
\def\arraystretch{1.5}
\begin{tabular}
{|l|>{\raggedright\arraybackslash}p{6cm}|>{\raggedright\arraybackslash}p{6cm}|}
\hline
                    & \textbf{boost::variant<unexpected<E>, T>} & \textbf{expected<T,E>}  \\
\hline
\textbf{never-empty warranty} & yes & yes \\
\hline
\textbf{accepts is_same<T,E>} & no & yes \\
\hline
\textbf{swap} & yes & yes \\
\hline
\textbf{factories} & no & make\_expected / make\_unexpected  \\
\hline
\textbf{hash} & yes & yes  \\
\hline
\textbf{value_type} & no & yes  \\
\hline
\textbf{default constructor} & yes (if T is default constructible) & yes (if T is default constructible)  \\
\hline
\textbf{observers} & boost::get<T> and boost::get<E> & pointer-like / value / error / value_or \\
\hline
\textbf{continuations} & apply_visitor & map/bind/then/catch_error  \\
\hline
\end{tabular}
\egroup
\caption{Comparison between variant and expected.}
\label{comp-variant}
\end{table}


\subsection{Optional}
%%%%%%%%%%%

We can see \cpp{expected<T,E>} as an \cpp{std::experimental::optional<T>} that collapse all the values of \cpp{E} to \cpp{nullopt}. We can convert an \cpp{expected<T,E>} to an \cpp{optional<T>} with the possible loss of information.

\begin{lstlisting}
template <class T>
optional<T> make_optional(expected<T,E> v) {
  if (v) return make_optional(*v);
  else nullopt;
}
\end{lstlisting}
\noindent
We can convert an \cpp{optional<T>} to an \cpp{expected<T,E>} without knowledge of the root cause. We consider that \cpp{E()} is equal to \cpp{nullopt} since it shouldn't bring more informations (however it depends on the underlying error --- we considered \cpp{exception_ptr} and \cpp{error_condition}).

\begin{lstlisting}
template <class T, class E>
expected<T,E> make_expected(optional<T> v) {
  if (v) return make_expected(*v);
  else make_unexpected(E());
}
\end{lstlisting}

\subsection{Promise and Future}
%%%%%%%%%%%%%%%%%

We can see \cpp{expected<T>} as an always ready \cpp{future<T>}. While \cpp{promise<>}/\cpp{future<>} focuses on inter-thread asynchronous communication, \cpp{excepted<E,T>} focus on eager and synchronous computations.
We can move a ready \cpp{future<T>} to an \cpp{expected<T>} with no loss of information. 

\begin{lstlisting}
template <class T>
expected<T> make_expected(future<T>&& f) {
  assert (f.ready() && "future not ready");
  try {
    return f.get();
  } catch (...) {
    return make_unexpected_from_exception();
  }
}
\end{lstlisting}
\noindent
We can also create a \cpp{future<T>} from an \cpp{expected<T>}.

\begin{lstlisting}
template <class T>
future<T> make_ready_future(expected<T> e) {
  if (e) 
    return make_ready_future(*e);
  else 
    return make_unexpected_future<T>(e.error()); 
}
\end{lstlisting}
\noindent
where \cpp{make_unexpected_future} is defined as:

\begin{lstlisting}
template <class T, class E>
constexpr future<T> make_unexpected_future(E e)  {
  promise<T> p;
  future<T> f = p.get_future();
  p.set_exception(e);
  return move(f);
}
\end{lstlisting}
\noindent
We can combine them as follows:

\begin{lstlisting}
fut.then([](future<int> f) { 
  return make_ready_future(
    make_expected(f).bind([](i){ ... }).catch_error(...));
  });
\end{lstlisting}

As for the \cpp{future<T>} proposal, \cpp{expected<T,E>} provides also a way to visit the stored values.
\cpp{future<T>} provides a \cpp{then()} function that accepts a continuation having the \cpp{future<T>} as parameter. The synchronous nature of expected makes it easier to use two functions, one to manage with the case expected has a value and one to try to recover otherwise. This is more in line with the monad interface, as any function having a \cpp{T} as parameter can be used as parameter of the apply function, no need to have a \cpp{expected<T,E>}. This make it easier to reuse functions. 

\begin{itemize}
 \item \cpp{expected<T,E>::then()} is the counterpart of \cpp{future<T>.then()}
 \item \cpp{expected<T,E>::unwrap()} is the counterpart of \cpp{future<T>.unwrap()}
 \item \cpp{expected<T,E>::operator bool()} is the counterpart of \cpp{future<T>.has_value()}
\end{itemize}

\subsection{Comparison between optional, expected and future}

The table \ref{comp-monads} presents a brief comparison between \cpp{optional<T>}, \cpp{expected<T,E>}  and \cpp{promise<T>/future<T>}.

\begin{table}
\bgroup
\def\arraystretch{1.5}
\begin{tabular}{|l|>{\raggedright\arraybackslash}p{4cm}|>{\raggedright\arraybackslash}p{4cm}|>{\raggedright\arraybackslash}p{4cm}|}
\hline
                    & \textbf{optional} & \textbf{expected} & \textbf{promise/future} \\
\hline
\textbf{specific null value} & yes & no & no \\
\hline
\textbf{relational operators} & yes & yes & no \\
\hline
\textbf{swap} & yes & yes & yes \\
\hline
\textbf{factories} & make_optional / nullopt & make_expected / make_unexpected & make_ready_future / (make_exceptional, see \cite{MoreAsync}) \\
\hline
\textbf{hash} & yes & yes & yes \\
\hline
\textbf{value_type} & yes & yes & no / (yes, see \cite{MoreAsync}).  \\
\hline
\textbf{default constructor} & yes & yes (if T is default constructible) & yes \\
\hline
\textbf{allocators} & no & no & yes \\
\hline
\textbf{emplace} & yes & yes & no \\
\hline
\textbf{bool conversion} & yes & yes & no \\
\hline
\textbf{state} & bool()  &  bool() / valid & valid / ready / (has_value, see \cite{MoreAsync}) \\
\hline
\textbf{observers} & pointer-like / value / value_or & pointer-like / value / error / value_or & get / (get_exception_ptr, see \cite{MoreAsync}) \\
\hline
\textbf{visitation} & no & map / bind / then / catch_error  & then / (next/recover see \cite{MoreAsync}) \\
\hline
\textbf{grouping} & n/a & n/a & when_all / when_any \\
\hline
\end{tabular}
\egroup
\caption{Comparison between optional, expected and promise/future.}
\label{comp-monads}
\end{table}

\section{Open points}
%%%%%%%%%%%%%

\subsection{Better support for monad}
\label{better-support-for-monad}

In the use-cases section (\ref{divide-example}), we present expected as a better way to handle errors than exception or error code. However the current syntax using lambda and chaining monadic operations (such as \cpp{map}) can be tedious to use. We propose different solutions to overcome this problem, since the solutions are more general than the scope of this proposal we discuss them in the open points section.

A first solution that do not require change in the language is the use of variadic monadic operation. For example using a variadic free function \cpp{map}, we can write the $i/k + j/k$ function as following:

\begin{lstlisting}
expected<int> f(int i, int j, int k)
{
  return map(plus,
    safe_divide(i, k), 
    safe_divide(j, k));
}
\end{lstlisting}

This is most readable than the member \cpp{map} function and the use of lambda. However it suffers from two major deficiencies:

\begin{itemize}
\item \textbf{Eager evaluation} All arguments are evaluated even if the first fails.
\item \textbf{Unordered evaluation} We cannot control the order of evaluation thus it presupposed the function to have no side effects.
\end{itemize}

Considering these two problems we consider a possible C++ language extension: a do-notation similar to the one in Haskell. As with the variadic \cpp{map} function, it is not limited to \cpp{expected} but could work with any kind of monad. Next follow the grammar:

\begin{lstlisting}
expression ::= ...
            | do-expression
do-expression ::= do-initialization ':' expression
do-initialization ::= type var '<-' expression
\end{lstlisting}

\noindent
The previous function could be rewritten as:

\begin{lstlisting}
expected<int, error_condition> f2(int i, int j, int k)
{
  return (
    auto s1 <- safe_divide(i, k) :
    auto s2 <- safe_divide(j, k) :
    s1 + s2
  );
}
\end{lstlisting}

This syntax is far easier to read and to understand. A lazy evaluation of statement is possible and the order is well-defined. Nevertheless, it can be considered as a syntactic sugar for \cpp{bind}. We give a syntactic transformation following:

\begin{lstlisting}
[[do-expression]] =
  bind(expression, [&](type var) {
    return [[do-expression-or-expression]]
  });
\end{lstlisting}
\noindent
The transformed code of the previous function is:

\begin{lstlisting}
expected<int, error_condition> f2(int i, int j, int k)
{
  return bind(safe_divide(i, k) ,[=](auto s1) {
    return bind(safe_divide(j, k),[=](auto s2) {
      return s1 + s2;
    });
  }); 
}
\end{lstlisting}

This would give the exact same results as the previous version. However, the function \cpp{f2} is much simpler and clearer than \cpp{f} because it doesn't have to explicitly handle any of the error cases. When an error case occurs, it is returned as the result of the function, but if not, the correct result of a subexpression is bound to a name (\cpp{s1} or \cpp{s2}), and that result can be used in later parts of the computation. The code is a lot simpler to write. The more complicated the error-handling function, the more important this will be.

But, the standard doesn't have this DO expression yet.
Waiting for a do-statement the user could define some macros and define \cpp{f2} as

\begin{lstlisting}
expected<int> f2(int i, int j, int k)
{
    return DO (
         ( s1, safe_divide(i, k) )
         ( s2, safe_divide(j, k) )
         s1 + s2 
    );
}
\end{lstlisting}

In the case of expected and optional, and similarly to the proposed \cpp{await} keyword we could use an \cpp{expect} keyword (it returns if the expected is not valued):

\begin{lstlisting}
expected<int> f2(int i, int j, int k)
{
  EXPECT(s1, safe_divide(i, k));
  EXPECT(s2, safe_divide(j, k));
  return s1 + s2;
}
\end{lstlisting}

Note that this meaning of EXPECT is not valid for the list monad. 

\subsection{A Configurable Expected}
\label{configurable-expected}

Expected might be configurable through a trait \cpp{expected_traits}. The first variation point is the behavior of \cpp{value()} when \cpp{expected<T,E>} contains an error. The current strategy throw a \cpp{bad_expected_access} exception (or the contained exception if the type is \cpp{expected<T, exception_ptr>}) but it might not be satisfactory for every error types. For example, some might want to encapsulate an \cpp{error_condition} into a specific exception. Or in debug mode, they might want to use an \cpp{assert} call.

The other variation point is the behavior triggered when the continuation argument of \cpp{bind} or \cpp{map} throws an exception. If the exception thrown is \cpp{system_error} and the error type is \cpp{error_code}, we might want to store the error carried by the exception. Without more discussion, let's show how we could customize \cpp{expected<T, E>}, consider the following exception-oriented function:

\begin{lstlisting}
class error_cond : public std::exception {
  // Implementation similar to system_error but for error_condition here.
};

int safe_divide(int i, int j)
{
  if (j == 0) 
    throw error_cond(error_condition(arithmetic_errc::divide_by_zero));
  return i/j;
}
\end{lstlisting}

\noindent
Imagine \cpp{j} encapsulated into an \cpp{expected}, you will call \cpp{map} with \cpp{safe_divide} as the continuation. Let's see what it looks like:

\begin{lstlisting}
expected<int, error_condition> f(int i, const expected<int, error_condition>& j)
{
  return j.map(bind(safe_divide, i, _1));
}
\end{lstlisting}

\noindent
If we specialize \cpp{expected_traits} for \cpp{error_condition}, we can achieve the expected behavior:

\begin{lstlisting}
template <class T>
struct expected_traits<expected<T, error_condition>>
{
  static expected<T, error_condition> catch_exception(exception_ptr e)
  {
    try {
      rethrow_exception(e);
    } catch(const error_cond& e) {
      return make_unexpected(e.code());
    }
  }

  static void bad_access(const error_type &e)
  {
    throw error_cond(e);
  }
};
\end{lstlisting}

The semantics of \cpp{catch_exception} is to rethrow the current exception and catch only the exceptions we are interested in. The default behavior let flight the exception thrown by the continuation. We created a bridge between an \cpp{error_condition} and the \cpp{error_cond} exception.

\subsection{Allocator support}
%%%%%%%%%%%%%%%

As \cpp{optional<T>},  \cpp{expected<T,E>} does not allocate memory. So it can do without allocators. However, it can be useful in compound types like:

\begin{lstlisting}
typedef vector<expected<vector<int, MyAlloc>, error>, MyAlloc> MyVec;
MyVec v{ v2, MyAlloc{} };
\end{lstlisting}

\noindent
One could expect that the allocator argument is forwarded in this constructor call to the nested vectors that use the same allocator. Allocator support would enable this. \cpp{std::tuple} offers this functionality.

\subsection{Which exception throw when the user try to get the expected value but there is none?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

It has been suggested to let the user decide the Exception that would be throw when the user try to get the expected value but there is none, as third parameter. 

While there is no major complexity doing it, as it just needs a third parameter that could default to the appropriated class, 

\begin{lstlisting}
template <class T, class Error, class Exception = bad_expected_access>
  struct expected;
\end{lstlisting}

\noindent
The authors consider that this is not really needed and that this parameter should not really be part of the type.

The user could use \cpp{value_or_throw()} 

\begin{lstlisting}
expected<int, std::error_code> f();
expected<int, std::error_code> e = f();
auto i = e.value_or_throw<std::system_error>();  
\end{lstlisting}

\noindent
where 

\begin{lstlisting}
template <class Exception, class T, class E>
constexpr value_type value_or_throw(expected<T,E>& e) const&
{
  return *this
    ? move(**this)
    : throw Exception(e.error());
}
\end{lstlisting}

\noindent
A class like this one could be added to the standard, but this proposal doesn't request it. 

The user can also wrap the proposed class in its own expected class

\begin{lstlisting}
template <class T, class Error=std::error_code, class Exception=std::system_error>
struct MyExpected {
  expected <T,E> v;
  MyExpected(expected <T,E> v) : v(v) {}
  T value() {  
    if (e) return v.value();
    else throw Exception(v.error());
  }
  ...
};
\end{lstlisting}

\noindent
and use it as

\begin{lstlisting}
expected<int, std::error_code> f();
MyExpected<int> e = f();
auto i = e.value();  // std::system_error throw if not valid
\end{lstlisting}

\noindent
A class like this one could be added to the standard, but this proposal doesn't request it. 

An alternative could be to add a specialization on a error class that gives the storage and the exception to thrown.

\begin{lstlisting}
template <class Error, class Exception>
  struct error_exception {
    typedef Error error_type;
    typedef Exception exception_type;
  };
\end{lstlisting}

\noindent
that could be used as follows

\begin{lstlisting}
expected<T, std::error_exception<std::error_code, std::system_error>> e = make_unexpected(err);
e.value(); // will throw std::system_error(err);
\end{lstlisting}

A class like this one could be added to the standard, but this proposal doesn't request it. 

\subsection{About \cpp{expected<T, ErrorCode, Exception>}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%

It has been suggested also to extend the design into something that contains 

\begin{itemize}
\item a T, or
\item an error code, or
\item a \cpp{exception_ptr} 
\end{itemize}

Again there is no major difficulty to implement it, but instead of having one variation point we have two, that is, is there a value, and if not, if is there an exception_ptr. While this would need only an extra test on the exceptional case, the authors think that it is not worth doing it as all the copy/move/swap operations would be less efficient. 

\subsection{Should \cpp{expected<T,exception_ptr>} be equality comparable?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This proposal makes \cpp{expected<T,exception_ptr>} equality comparable making all the unexpected values equals as \cpp{exception_ptr} equality comparison is shallow and doesn't provides relational operators.

Should \cpp{expected<T,exception_ptr>} not be equality comparable?

Should \cpp{expected<T,exception_ptr>} be equality comparable using shallow comparison?

\subsection{Should \cpp{expected<T,E>} make all the unexpected values equal?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Currently \cpp{expected<T,E>} and \cpp{expected<T>} don't compare its values in the same way.
Should \cpp{expected<T,E>} make all the unexpected values equal as it does \cpp{expected<T>}?

As for Rapperswil decision, the unexpected values of \cpp{expected<T,E>} when \cpp{E} is not \cpp{exception_ptr} don't collapse to a unique value.

\subsection{Should \cpp{expected<T,E>} throw \cpp{E} instead of \cpp{bad_expected_access<E>}?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

As any type can be thrown as an exception, should \cpp{expected<T,E>} throw \cpp{E} instead of \\
\cpp{bad_expected_access<E>}? 
If yes, should \cpp{optional<T>} throw \cpp{nullopt_t} to be coherent? 

\subsection{Should \cpp{expected<T,E>} be convertible from \cpp{E} when \cpp{E} it is not convertible to \cpp{T}?}

The implicit conversion from \cpp{E} has been forbidden to avoid ambiguity when \cpp{E} and \cpp{T} are the same type. 
However when \cpp{E} it is not convertible to \cpp{T} there wouldn't any ambiguity. 
Should the implicit conversion be allowed in this case?

\subsection{Should a specific exception be thrown when the \cpp{expected<T>} doesn't have a value neither an exception stored?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The following call in (1) is undefined behavior. Should a specific exception be thrown?

\begin{lstlisting}
expected<int> e;
e.value(); // (1)
\end{lstlisting}

\subsection{Should \cpp{map}/\cpp{bind}/\cpp{then} catch the exceptions throw by the continuation?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

It is easy to catch the exceptions when the type is \cpp{expected<T>}. However, doing it for \cpp{expected<T,E>} needs a conversion from the current exception and the error E.

This proposal requires that the continuation doesn't throw exceptions as we don't have a general solution.

Should  \cpp{expected<T>::map/bind/then} catch the exceptions and propagate them on the result?

Should  \cpp{expected<T,E>::map/bind/then} catch the exceptions and propagate them on the result by doing a transformation from the exception to the error? If yes, how to configure it?

\subsection{Do we need a \cpp{expected<T,E>::error_or} function?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

It has been argued that the error should be always available and that often there is a success value associated to the error.

\cpp{expected<T,E>} would be seen more like something  

\begin{lstlisting}
struct { E; optional<T> }. 
\end{lstlisting}

\noindent
The following code was show as use case

\begin{lstlisting}
auto e = function();
switch (e.status()) {
  success: ....; break;
  too_green: ....; break;
  too_pink: ....; break;
} 
\end{lstlisting}

\noindent
With the current interface the user could be tempted to do

\begin{lstlisting}
auto e = function();
if (e) {
  /*success:*/ ....;
} else {
  switch (e.status()) {
  case too_green: ....; break;
  case too_pink: ....; break;
  }
} 
\end{lstlisting}

\noindent
This could be done with the current interface as follows

\begin{lstlisting}
auto e = function();
switch (error_or(e, success)) {
  success: ....; break;
  too_green: ....; break;
  too_pink: ....; break;
} 
\end{lstlisting}

\noindent
where

\begin{lstlisting}
template <class E, class T>
E error_or(expected<T,E> const&, E err) {
  if(e) return err;
  else return error();
}
\end{lstlisting}

\noindent
Do we need to add such a \cpp{error_or} function? as member? 

\subsection{Do we need a  \cpp{expected<T,E>::has_error}  function?}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

An other use case which could look much uglier is if the user had to test for whether or not there was a status.

\begin{lstlisting}
  e = function();
  while ( e.status == timeout ) {
    sleep(delay);
    delay *=2;
  }
\end{lstlisting}

\noindent
Here we have a value or a hard error.  
This use case would need to use something like \cpp{has_error}

\begin{lstlisting}
  e = function();
  while ( has_error(e, timeout) ) {
    sleep(delay);
    delay *=2;
  }
\end{lstlisting}

\noindent
where

\begin{lstlisting}
template <class T, class E>
bool has_error(expected<T,E> const&, E err) {
  if (e) return false;
  else return error()==err;
}
\end{lstlisting}

Do we need to add such a \cpp{has_error} function? as member? 

%%%%%%%%%%%%%%
\section{Proposed Wording}
%%%%%%%%%%%%%%


The proposed changes are expressed as edits to N3908, the Working Draft - C++ Extensions for Library Fundamentals \cite{FundamentalsV1}. The wording has been adapted from the section  "Optional objects".
\newline

Insert a new section. 

\wordingSec{Unexpected objects}{unexpected}
%%%%%%%%%%%%%%%%%%%%%

\wordingSubSec{In general}{unexpected.general}
%%%%%%%%%%%%%%%%%%%%%%%%

This subclause describes class template \cpp{unexpected_type} that wraps objects intended as unexpected. This wrapped unexpected object is used to be implicitly convertible to other objects.

\wordingSubSec{Header <experimental/unexpected> synopsis}{unexpected.synop}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{lstlisting}[language=C++][xleftmargin=0pt]
namespace std {
namespace experimental {
inline namespace fundamentals_v2 {
  // \ref{unexpected.object}, Unexpected object type
  template <class E>
  struct unexpected_type; 
  // \ref{unexpected.exception_ptr}, Unexpected exception_ptr specialization
  template <>
  struct unexpected_type<exception_ptr>; 

  // \ref{unexpected.factories}, Unexpected factories
  template <class E>
  constexpr unexpected_type<decay_t<E>> make_unexpected(E&& v);
  unexpected_type<std::exception_ptr> make_unexpected_from_current_exception();
}}}
\end{lstlisting}

A program that necessitates the instantiation of template \cpp{unexpected_type} for a reference type or \cpp{void} is ill-formed.

\wordingSubSec{Unexpected object type}{unexpected.object}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% unexpected_type object type
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class E=std::exception_ptr>
class unexpected_type {
public:
    unexpected_type() = delete;
    constexpr explicit unexpected_type(E const&);   
    constexpr explicit unexpected_type(E&&);
    constexpr E const& value() const;                              
private:
    E val; // exposition only
}; 
\end{lstlisting}

% unexpected_type constructor from underlying.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr explicit unexpected_type(E const&);   
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Build an unexpected by copying the parameter to the internal storage \cpp{val}.
\end{wordingTextItem}
\end{wordingPara}

% unexpected_type move constructor from underlying.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr explicit unexpected_type(E &&);   
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Build an unexpected by moving the parameter to the internal storage \cpp{val}.
\end{wordingTextItem}
\end{wordingPara}

% unexpected_type constructor from underlying.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr E const& value() const;                              
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{val}.
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSec{Unexpected exception_ptr specialization}{unexpected.exception_ptr}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <>
class unexpected_type<std::exception_ptr> {
public:
    unexpected_type() = delete;
    explicit unexpected_type(std::exception_ptr const&);
    explicit unexpected_type(std::exception_ptr&&);
    template <class E>
      explicit unexpected_type(E);     
    std::exception_ptr const &value() const;                              
private:
    E val; // exposition only
}; 
\end{lstlisting}
\noindent

% unexpected_type constructor from underlying.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr explicit unexpected_type(exception_ptr const&);   
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Build an unexpected by copying the parameter to the internal storage \cpp{val}.
\end{wordingTextItem}
\end{wordingPara}

% unexpected_type move constructor from underlying.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr explicit unexpected_type(exception_ptr &&);   
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Build an unexpected by moving the parameter to the internal storage \cpp{val}.
\end{wordingTextItem}
\end{wordingPara}

% unexpected_type constructor from an Exception.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr explicit unexpected_type(E e);   
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Build an unexpected storing the result of \cpp{val(make_exception_ptr(e))}.
\end{wordingTextItem}
\end{wordingPara}

% unexpected_type constructor from underlying.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr exception_ptr const& value() const;                              
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{val}.
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSec{Factories}{unexpected.factories}

% make_unexpected  factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class E>
constexpr unexpected_type<decay_t<E>> make_unexpected(E&& v);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{unexpected<decay_t<E>>(v)}.
\end{wordingTextItem}
\end{wordingPara}

% make_unexpected  factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr unexpected_type<std::exception_ptr> make_unexpected_from_current_exception();
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{unexpected<std::exception_ptr>(std::current_exception())}.
\end{wordingTextItem}
\end{wordingPara}

Insert a new section.

\wordingSec{Expected objects}{expected}
%%%%%%%%%%%%%%%%%%%%%

\wordingSubSec{In general}{expected.general}
%%%%%%%%%%%%%%%%%%%%%%%%

This subclause describes class template expected that represents expected objects. An \cpp{expected<T,E>} object is an object that contains the storage for another object and manages the lifetime of this contained object T, alternatively it could contain the storage for another unexpected object E. The contained object may not be initialized after the expected object has been initialized, and may not be destroyed before the expected object has been destroyed. The initialization state of the contained object is tracked by the expected object.

\wordingSubSec{Header <experimental/expected> synopsis}{expected.synop}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{lstlisting}[language=C++][xleftmargin=0pt]
namespace std {
namespace experimental {
inline namespace fundamentals_v2 {
  // \ref{expected.holder}, holder class used as default.  
  class holder;
  // \ref{expected.object}, expected for object types  
  template <class E= exception_ptr, class T=holder>
  class expected;
  // \ref{expected.object.void}, Specialization for void.  
  template <class E>
  class expected<void, E>;
  // \ref{expected.object.meta}, Specialization of expected as a meta-function : T-> expected<T,E>.  
  template <class E>
  class expected<holder, E>;
   
  // \ref{expected.unexpect}, unexpect tag
  struct unexpect_t{};
  constexpr unexpet_t unexpect{};
   
  // \ref{expected.bad_expected_access}, class bad_expected_access
  class bad_expected_access;
 
  
  // \ref{expected.relational_op}, Expected relational operators
  template <class T, class E>
    constexpr bool operator==(const expected<T,E>&, const expected<T,E>&);
  template <class T, class E>
    constexpr bool operator!=(const expected<T,E>&, const expected<T,E>&);
  template <class T, class E>
    constexpr bool operator<(const expected<T,E>&, const expected<T,E>&);
  template <class T, class E>
    constexpr bool operator>(const expected<T,E>&, const expected<T,E>&);
  template <class T, class E>
    constexpr bool operator<=(const expected<T,E>&, const expected<T,E>&);
  template <class T, class E>
    constexpr bool operator>=(const expected<T,E>&, const expected<T,E>&);
    
  // \ref{expected.comparison_T}, Comparison with T 
  template <class T, class E> constexpr bool operator==(const expected<T,E>&, const T&);
  template <class T, class E> constexpr bool operator==(const T&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator!=(const expected<T,E>&, const T&);
  template <class T, class E> constexpr bool operator!=(const T&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator<(const expected<T,E>&, const T&);
  template <class T, class E> constexpr bool operator<(const T&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator<=(const expected<T,E>&, const T&);
  template <class T, class E> constexpr bool operator<=(const T&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator>(const expected<T,E>&, const T&);
  template <class T, class E> constexpr bool operator>(const T&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator>=(const expected<T,E>&, const T&);
  template <class T, class E> constexpr bool operator>=(const T&, const expected<T,E>&);

  // \ref{expected.comparison_unexpected_E}, Comparison with unexpected_type<E>
  template <class T, class E> constexpr bool operator==(const expected<T,E>&, const unexpected<E>&);
  template <class T, class E> constexpr bool operator==(const unexpected<E>&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator!=(const expected<T,E>&, const unexpected<E>&);
  template <class T, class E> constexpr bool operator!=(const unexpected<E>&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator<(const expected<T,E>&, const unexpected<E>&);
  template <class T, class E> constexpr bool operator<(const unexpected<E>&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator<=(const expected<T,E>&, const unexpected<E>&);
  template <class T, class E> constexpr bool operator<=(const unexpected<E>&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator>(const expected<T,E>&, const unexpected<E>&);
  template <class T, class E> constexpr bool operator>(const unexpected<E>&, const expected<T,E>&);
  template <class T, class E> constexpr bool operator>=(const expected<T,E>&, const unexpected<E>&);
  template <class T, class E> constexpr bool operator>=(const unexpected<E>&, const expected<T,E>&);

  // \ref{expected.specalg}, Specialized algorithms
    void swap(expected<E,T>&, expected<E,T>&) noexcept(see below);
    void swap(expected<T,E>&, expected<T,E>&) noexcept(see below);

  // \ref{expected.factories}, Factories
  template <class T> constexpr expected<decay_t<T>> make_expected(T&& v);
  expected<void> make_expected();
  template <class E> expected<void, E> make_expected();
  
  template <class T>
  expected<T> make_expected_from_current_exception();
  template <class T, class E>
   constexpr expected<T> make_expected_from_exception(E e); 
  template <class T>
   constexpr expected<T> make_expected_from_exception(std::exception_ptr v);   
 
  template <class T, class E>
   constexpr expected<T, decay_t<E>> make_expected_from_error(E v);

  template <class F>
   constexpr expected<typename result_type<F>::type>
   make_expected_from_call(F f);

  // \ref{expected.hash}, hash support
  template <class T> struct hash;
  template <class T> struct hash<expected<T,E>>;
}}}
\end{lstlisting}

A program that necessitates the instantiation of template \cpp{expected<T,E>} with \cpp{T} for a reference type\, or for possibly cv-qualified types \cpp{in_place_t}, \cpp{unexpect_t} or \cpp{unexpected_type<E>} is ill-formed.

\wordingSubSec{Definitions}{expected.defs}
%%%%%%%%%%%%%%%%%%%%%%

An instance of \cpp{expected<T,E>} is said to be valued if it contains an value of type \cpp{T}.
An instance of \cpp{expected<T,E>} is said to be unexpected if it contains an object of type \cpp{E}.

\wordingSubSec{expected for object types}{expected.object}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{lstlisting}[language=C++][xleftmargin=0pt]

  template <class T, class E>
  class expected
  {
  public:
    typedef T value_type;
    typedef E error_type;
    
    template <class U>
    struct rebind {
      typedef expected<U, error_type> type;
    };
    
     // \ref{expected.object.ctor}, constructors
    constexpr expected() noexcept(see below);
    expected(const expected&);
    expected(expected&&) noexcept(see below);
    
    constexpr expected(const T&);
    constexpr expected(T&&);
    template <class... Args> 
      constexpr explicit expected(in_place_t, Args&&...);     
    template <class U, class... Args>
      constexpr explicit expected(in_place_t, initializer_list<U>, Args&&...);
      
    constexpr expected(unexpected_type<E> const&);
    template <class Err> 
    constexpr expected(unexpected_type<Err> const&);

    // \ref{expected.object.dtor}, destructor
    ~expected();

    // \ref{expected.object.assign}, assignment
    expected& operator=(const expected&);
    expected& operator=(expected&&) noexcept(see below);
    
    template <class U> expected& operator=(U&&);
    
    expected& operator=(const unexpected_type<E>&);
    expected& operator=(unexpected_type<E>&&) noexcept(see below);
    
    template <class... Args> void emplace(Args&&...);
    template <class U, class... Args>
      void emplace(initializer_list<U>, Args&&...);

    // \ref{expected.object.swap}, swap
    void swap(expected&) noexcept(see below);

    // \ref{expected.object.observe}, observers
    constexpr T const* operator ->() const;
    T* operator ->();
    
    constexpr T const& operator *() const&;
    T& operator *() &;
    constexpr T&& operator *() &&;
    
    constexpr explicit operator bool() const noexcept;
    
    constexpr T const& value() const&;
    T& value() &;
    constexpr T&& value() &&;
    
    constexpr E const& error() const&;
    E& error() &;
    constexpr E&& error() &&;
    
    constexpr unexpected<E>  get_unexpected() const;
    
    template <typename Ex>
    bool has_exception() const;
      
    template <class U> constexpr T value_or(U&&) const&;
    template <class U> T value_or(U&&) &&;
    
    template constexpr 'see below' unwrap() const&;
    template 'see below' unwrap() &&;

    // \ref{expected.object.factories}, factories
    template <typename Ex, typename F>
    expected<T,E> catch_exception(F&& f);

    template <typename F>
      expected<decltype(func(declval<T>())),E> map(F&& func) ;
    template <typename F>
      'see below' bind(F&& func);
    template <typename F>
      expected<T,E> catch_error(F&& f);
    template <typename F>
      'see below' then(F&& func);
  
  private:
    bool has_value;    // exposition only
    union
    {
      value_type val;  // exposition only
      error_type err;  // exposition only
    };
  };

\end{lstlisting}


Valued instances of \cpp{expected<T,E>} where \cpp{T} and \cpp{E} is of object type shall contain a value of type \cpp{T} or a value of type \cpp{E} within its own storage. This value is referred to as the contained or the unexpected value of the expected object. Implementations are not permitted to use additional storage, such as dynamic memory, to allocate its contained or unexpected value. The contained or unexpected value shall be allocated in a region of the \cpp{expected<T,E>} storage suitably aligned for the type \cpp{T} and \cpp{E}.
\newline

Members \cpp{has_value}, \cpp{val} and \cpp{err} are provided for exposition only. Implementations need not provide those members. \cpp{has_value} indicates whether the expected object's contained value has been initialized (and not yet destroyed); when \cpp{has_value} is true \cpp{val} points to the contained value, and when it is false \cpp{err} points to the erroneous value. 

\cpp{T} and \cpp{E} shall be an object type and shall satisfy the requirements of \cpp{Destructible}.

\wordingSubSubSec{Constructors}{expected.object.ctor}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Default Constructor
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr expected() noexcept('see below');
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Initializes the contained value as if direct-non-list-initializing an object of type \cpp{T} with the expression \cpp{T()}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the default constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The expression inside \cpp{noexcept} is equivalent to:\\
\cpp{is_nothrow_default_constructible<T>::value}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
 \cpp{is_default_constructible<T>::value}.
\end{wordingTextItem}


\end{wordingPara}

% Copy Constructor
\begin{lstlisting}[language=C++][xleftmargin=0pt]
expected(const expected& rhs);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
If \cpp{bool(rhs)} initializes the contained value as if direct-non-list-initializing an object of type \cpp{T} with the expression \cpp{*rhs}.\\

\noindent
If \cpp{!bool(rhs)} initializes the contained value as if direct-non-list-initializing an object of type \cpp{E} with the expression \cpp{rhs.error()}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(rhs) == bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T} or \cpp{E}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_copy_constructible<T>::value} and\\
\cpp{is_copy_constructible<E>::value}.
\end{wordingTextItem}
\end{wordingPara}

% Move Constructor
\begin{lstlisting}[language=C++][xleftmargin=0pt]
expected(expected && rhs) noexcept('see below');
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
If \cpp{bool(rhs)} initializes the contained value as if direct-non-list-initializing an object of type \cpp{T} with the expression \cpp{std::move(*rhs)}. \\

\noindent
If \cpp{!bool(rhs)} initializes the contained value as if direct-non-list-initializing an object of type \cpp{E} with the expression \cpp{std::move(rhs.error())}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(rhs) == bool(*this)} and \\
\cpp{bool(rhs)} is unchanged.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T} or \cpp{E}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The expression inside \cpp{noexcept} is equivalent to:\\
\cpp{is_nothrow_move_constructible<T>::value == trye} and   \\
\cpp{is_nothrow_move_constructible<E>::value}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_move_constructible<T>::value} and \\
\cpp{is_move_constructible<E>::value}.
\end{wordingTextItem}
\end{wordingPara}

% Value Constructor
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr expected(const T& v);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Initializes the contained value as if direct-non-list-initializing an object of type \cpp{T} with the expression \cpp{v}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
If \cpp{T}'s selected constructor is a \cpp{constexpr} constructor, this constructor shall be a \cpp{constexpr} constructor.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_copy_constructible<T>::value}. 
\end{wordingTextItem}
\end{wordingPara}

% Move value constructor
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr expected(T&& v); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Initializes the contained value as if direct-non-list-initializing an object of type \cpp{T} with the expression \cpp{std::move(v)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
If \cpp{T}'s selected constructor is a \cpp{constexpr} constructor, this constructor shall be a \cpp{constexpr} constructor.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_move_constructible<T>::value}.
\end{wordingTextItem}
\end{wordingPara}

% Emplace constructor
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class... Args>
constexpr explicit expected(in_place_t, Args&&... args); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Initializes the contained value as if direct-non-list-initializing an object of type \cpp{T} with the arguments \cpp{std::forward<Args>(args)...}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
If \cpp{T}'s constructor selected for the initialization is a \cpp{constexpr} constructor, this constructor shall be a \cpp{constexpr} constructor.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_constructible<T, Args&&...>::value}.
\end{wordingTextItem}
\end{wordingPara}

% Emplace constructor with initializer list.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class U, class... Args>
constexpr explicit expected(in_place_t, initializer_list<U> il, Args&&... args); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Initializes the contained value as if direct-non-list-initializing an object of type \cpp{T} with the arguments \cpp{il, std::forward<Args>(args)...}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless:\\
\noindent
\cpp{is_constructible<T, initializer_list<U>&, Args&&...>::value}.\\

\noindent
If \cpp{T}'s constructor selected for the initialization is a \cpp{constexpr} constructor, this constructor shall be a \cpp{constexpr} constructor.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_constructible<T, initializer_list<U>&, Args&&...>::value}.
\end{wordingTextItem}
\end{wordingPara}


% Unexpected Constructor
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr expected(unexpected_type<E> const& e);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Initializes the unexpected value as if direct-non-list-initializing an object of type \cpp{E} with the expression \cpp{e.value()}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{! *this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{E}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
If \cpp{E}'s selected constructor is a \cpp{constexpr} constructor, this constructor shall be a \cpp{constexpr} constructor.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_copy_constructible<E>::value}. 
\end{wordingTextItem}
\end{wordingPara}

% Unexpected move constructor
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr expected(unexpected_type<E>&& e); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Initializes the unexpected value as if direct-non-list-initializing an object of type \cpp{E} with the expression \cpp{std::move(e.value())}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{! *this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{E}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
If \cpp{E}'s selected constructor is a \cpp{constexpr} constructor, this constructor shall be a \cpp{constexpr} constructor.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_move_constructible<E>::value}.
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSubSec{Destructor}{expected.object.dtor}
%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Destructor.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
~expected();
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
If \cpp{is_trivially_destructible<T>::value != true} and \cpp{bool(*this)}, calls \cpp{val->T::~T()}.\\
If \cpp{is_trivially_destructible<E>::value != true} and \cpp{! *this}, calls \cpp{err->E::~E()}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
If \cpp{is_trivially_destructible<T>::value} and \cpp{is_trivially_destructible<E>::value} then this destructor shall be a trivial destructor.
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSubSec{Assignment}{expected.object.assign}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Copy assignment operator.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
expected<T,E>& operator=(const expected<T,E>& rhs); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
if \cpp{bool(*this)} and \cpp{bool(rhs)}, assigns \cpp{*rhs} to the contained value \cpp{val}, otherwise \\
if \cpp{bool(*this)} and \cpp{! rhs}, destroys the contained value by calling \cpp{val->T::~T()} and  initializes the contained value as if direct-non-list-initializing an object of type \cpp{E} with \cpp{rhs.error()}, otherwise \\
if \cpp{! *this} and \cpp{! rhs}, assigns \cpp{rhs.error()} to the contained value \cpp{err}, otherwise \\
if \cpp{! *this} and \cpp{bool(rhs)}, destroys the contained value by calling \cpp{err->E::~E()} and  initializes the contained value as if direct-non-list-initializing an object of type \cpp{E} with \cpp{rhs.error()}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{*this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(rhs) == bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
If any exception is thrown, the values of \cpp{bool(*this)} and \cpp{bool(rhs)} remain unchanged. If an exception is thrown during the call to \cpp{T}'s copy constructor, no effect. If an exception is thrown during the call to \cpp{T}'s copy assignment, the state of its contained value is as defined by the exception safety guarantee of \cpp{T}'s copy assignment. If an exception is thrown during the call to \cpp{E}'s copy constructor, no effect. If an exception is thrown during the call to \cpp{E}'s copy assignment, the state of its contained value is as defined by the exception safety guarantee of \cpp{E}'s copy assignment.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_copy_constructible<T>::value} and\\
\cpp{is_copy_assignable<T>::value} and\\
\cpp{is_copy_constructible<E>::value} and\\
\cpp{is_copy_assignable<E>::value}.
\end{wordingTextItem}

\end{wordingPara}

% Move assignment operator.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
expected<T,E>& operator=(expected<T,E>&& rhs) noexcept(/*see below*/); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
if \cpp{bool(*this)} and \cpp{rhs} is values, assigns \cpp{std::move(*rhs)} to the contained value \cpp{val}, otherwise \\
if \cpp{bool(*this)} and \cpp{! rhs}, destroys the contained value by calling \cpp{val->T::~T()} and  initializes the contained value as if direct-non-list-initializing an object of type \cpp{E} with \cpp{rhs.error()}, otherwise \\
if \cpp{! *this} and \cpp{! rhs}, assigns \cpp{std::move(rhs.error())} to the contained value \cpp{err}, otherwise  
if \cpp{! *this} and \cpp{bool(rhs)}, destroys the contained value by calling \cpp{err->E::~E()} and  initializes the contained value as if direct-non-list-initializing an object of type \cpp{E} with \cpp{rhs.error()}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{*this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(rhs) == bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The expression inside \cpp{noexcept} is equivalent to:\\
\cpp{is_nothrow_move_assignable<T>::value &&}\\
\cpp{is_nothrow_move_constructible<T>::value &&}\\
\cpp{is_nothrow_move_assignable<E>::value &&}\\
\cpp{is_nothrow_move_constructible<E>::value}.
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
If any exception is thrown, the values of  \cpp{bool(*this)} and \cpp{bool(rhs)} remain unchanged. If an exception is thrown during the call to \cpp{T}'s move constructor, the state of \cpp{rhs.val} is determined by exception safety guarantee of \cpp{T}'s move constructor. If an exception is thrown during the call to \cpp{T}'s move assignment, the state of \cpp{val} and \cpp{rhs.val} is determined by exception safety guarantee of \cpp{T}'s move assignment. If an exception is thrown during the call to \cpp{E}'s move constructor, the state of \cpp{rhs.err} is determined by exception safety guarantee of \cpp{E}'s move constructor. If an exception is thrown during the call to \cpp{E}'s move assignment, the state of \cpp{err} and \cpp{rhs.err} is determined by exception safety guarantee of \cpp{E}'s move assignment.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_move_constructible<T>::value} and \\
\cpp{is_move_assignable<T>::value} and \\
\cpp{is_move_constructible<E>::value} and
\cpp{is_move_assignable<E>::value}.
\end{wordingTextItem}
\end{wordingPara}

% Value assignment operator.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class U>
expected<T,E>& operator=(U&& v); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
If \cpp{bool(*this)} assigns \cpp{std::forward<U>(v)} to the contained value; otherwise destroys the contained value by calling \cpp{err->E::~E()} and initializes the unexpected value as if direct-non-list-initializing object of type \cpp{T} with \cpp{std::forward<U>(v)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{*this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
If any exception is thrown, \cpp{bool(*this)} remains unchanged. If an exception is thrown during the call to \cpp{E}'s constructor, the state of \cpp{e} is determined by exception safety guarantee of \cpp{E}'s constructor. If an exception is thrown during the call to \cpp{E}'s assignment, the state of \cpp{err} and \cpp{e} is determined by exception safety guarantee of \cpp{E}'s assignment.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_constructible<T,U>::value} and \\
\cpp{is_assignable<T&, U>::value}.
\end{wordingTextItem}
\begin{wordingNoteItem}
The reason to provide such generic assignment and then constraining it so that effectively \cpp{T == U} is to guarantee that assignment of the form \cpp{o = \{\}} is unambiguous.
\end{wordingNoteItem}
\end{wordingPara}

% unexpected assignment operator.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
expected<T,E>& operator=(unexpected_type<E>&& e); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
If \cpp{! *this} assigns \cpp{std::forward<E>(e.value())} to the contained value; otherwise destroys the contained value by calling \cpp{val->T::~T()} and initializes the contained value as if direct-non-list-initializing object of type \cpp{E} with \cpp{std::forward<unexpected_type<E>>(e).value()}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{*this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{! *this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
If any exception is thrown, value of valued remains unchanged. If an exception is thrown during the call to \cpp{T}'s constructor, the state of \cpp{v} is determined by exception safety guarantee of \cpp{T}'s constructor. If an exception is thrown during the call to \cpp{T}'s assignment, the state of \cpp{val} and \cpp{v} is determined by exception safety guarantee of \cpp{T}'s assignment.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_copy_constructible<E>::value} and \\
\cpp{is_assignable<E&, E>::value}.
\end{wordingTextItem}
\end{wordingPara}

% Emplace assignment.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class... Args>
void emplace(Args&&... args); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}if \cpp{bool(*this)}, assigns the contained value \cpp{val} as if constructing an object of type \cpp{T} with the arguments \cpp{std::forward<Args>(args)...}, otherwise destroys the contained value by calling \cpp{err->E::~E()} and  initializes the contained value as if constructing an object of type \cpp{T} with the arguments \cpp{std::forward<Args>(args)...}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
If an exception is thrown during the call to \cpp{T}'s constructor, \cpp{*this} is disengaged, and the previous \cpp{val} (if any) has been destroyed.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This signature shall not participate in overload resolution unless\\
\cpp{is_constructible<T, Args&&...>::value}.
\end{wordingTextItem}
\end{wordingPara}

% Emplace with initializer list assignment.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class U, class... Args>
void emplace(initializer_list<U> il, Args&&... args); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
if \cpp{bool(*this)}, assigns the contained value \cpp{val} as if constructing an object of type \cpp{T} with the arguments \cpp{il,std::forward<Args>(args)...}, otherwise 
destroys the contained value by calling \cpp{err->E::~E()} and  initializes the contained value as if constructing an object of type \cpp{T} with the arguments \cpp{il,std::forward<Args>(args)...}.
\end{wordingTextItem}
\begin{wordingTextItem}{Postconditions}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
If an exception is thrown during the call to \cpp{T}'s constructor, \cpp{! *this} , and the previous \cpp{val} (if any) has been destroyed.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless: \\
\cpp{is_constructible<T, initializer_list<U>&, Args&&...>::value}.
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSubSec{Swap}{expected.object.swap}
%%%%%%%%%%%%%%%%%%%%%%%%%%

% swap operation.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
void swap(expected<T,E>& rhs) noexcept(/*see below*/); 
\end{lstlisting}
\begin{wordingPara}

\begin{wordingTextItem}{Effects}
if \cpp{bool(*this)} and \cpp{bool(rhs)}, calls \cpp{swap(val, rhs.val)}, otherwise \\
if \cpp{! *this} and \cpp{! rhs}, calls \cpp{swap(err, rhs.err)}, otherwise \\
if \cpp{bool(*this)} and \cpp{! rhs}, initializes a temporary variable e by direct-initialization with \cpp{std::move(rhs.err))}, initializes the contained value of \cpp{rhs} by direct-initialization with \cpp{std::move(*(*this))}, initializes the expected value of \cpp{*this} by direct-initialization with \cpp{std::move(rhs.err)} and swaps \cpp{has_value} and \cpp{rhs.has_value}, otherwise \\
calls to \cpp{rhs.swap(*this)};
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
\todo{This must be worded.}
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exceptions that the expressions in the Effects clause throw.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The expression inside \cpp{noexcept} is equivalent to: \\
\cpp{is_nothrow_move_constructible<T>::value && noexcept(swap(declval<T&>(), declval<T&>())) &&} \\
\cpp{is_nothrow_move_constructible<E>::value && noexcept(swap(declval<E&>(), declval<E&>()))}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless: \\
LValues of type \cpp{T} shall be swappable, \cpp{is_move_constructible<T>::value}, LValues of type \cpp{E} shall be swappable and \cpp{is_move_constructible<T>::value}.
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSubSec{Observers}{expected.object.observe}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% -> operator.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr T const* operator->() const;
T* operator->(); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Requires}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{&val}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
Unless \cpp{T} is a user-defined type with overloaded unary operator\&, the first function shall be a \cpp{constexpr} function.
\end{wordingTextItem}
\end{wordingPara}

% * operator.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr T const& operator *() const&;
T& operator *() &;
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Requires}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{val}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The first function shall be a \cpp{constexpr} function.
\end{wordingTextItem}
\end{wordingPara}

% && operator*.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr T&& operator *() &&;
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Requires}
\cpp{bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{move(val)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This function shall be a \cpp{constexpr} function.
\end{wordingTextItem}
\end{wordingPara}

% bool conversion operator.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr explicit operator bool() noexcept; 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{has_value}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
This function shall be a \cpp{constexpr} function.
\end{wordingTextItem}
\end{wordingPara}

% value accessor.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr T const& value() const&;
T& value() &;
constexpr T&& value() &&;
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{*val}, \cpp{if bool(*this)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
\begin{itemize}
\item When \cpp{E} is \cpp{std::exception_ptr} as if \cpp{rethrow_exception(error())} if \cpp{!*this} 
\item Otherwise \cpp{bad_expected_access(err)} if \cpp{!*this}.
\end{itemize}

\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The first and third functions shall be \cpp{constexpr} functions.
\end{wordingTextItem}
\end{wordingPara}

% error accessor.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr E const& error() const&;
constexpr E& error() &; 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Requires}
\cpp{!*this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{err}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The first function shall be a \cpp{constexpr} function.
\end{wordingTextItem}
\end{wordingPara}

% error accessor.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr E&& error() &&; 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Requires}
\cpp{!*this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{move(err)}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The first function shall be a \cpp{constexpr} function.
\end{wordingTextItem}
\end{wordingPara}

% has_exception accessor.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class Ex>
bool expected<T>::has_exception() const;
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{true} if and only if \cpp{!(*this)} and the stored exception is a base type of \cpp{Ex}.
\end{wordingTextItem}
\end{wordingPara}


% unexpected conversion.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr unexpected<E> get_unexpected() const;
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Requires}
\cpp{!*this}.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
\cpp{make_unexpected(err)}.
\end{wordingTextItem}
\end{wordingPara}

% value_or method.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class U>
constexpr T value_or(U&& v) const&; 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{bool(*this) ? **this : static_cast<T>(std::forward<U>(v))}.
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
If \cpp{has_value} and exception is thrown during the call to \cpp{T}'s constructor, the value of \cpp{has_value} and \cpp{v} remains unchanged and the state of \cpp{val} is determined by the exception safety guarantee of the selected constructor of \cpp{T}. Otherwise, when exception is thrown during the call to \cpp{T}'s constructor, the value of \cpp{*this} remains unchanged and the state of \cpp{v} is determined by the exception safety guarantee of the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
If both constructors of \cpp{T} which could be selected are \cpp{constexpr} constructors, this function shall be a \cpp{constexpr} function.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless: \\
\cpp{is_copy_constructible<T>::value} and \\
\cpp{is_convertible<U&&, T>::value}.
\end{wordingTextItem}
\end{wordingPara}

% move value_or.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class U>
T value_or(U&& v) &&; 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{bool(*this) ? std::move(**this) : static_cast<T>(std::forward<U>(v))}.
\end{wordingTextItem}
\begin{wordingTextItem}{Exception Safety}
If \cpp{has_value} and exception is thrown during the call to \cpp{T}'s constructor, the value of \cpp{has_value} and \cpp{v} remains unchanged and the state of \cpp{val} is determined by the exception safety guarantee of the \cpp{T}'s constructor. Otherwise, when exception is thrown during the call to \cpp{T}'s constructor, the value of \cpp{*this} remains unchanged and the state of \cpp{v} is determined by the exception safety guarantee of the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{T}.
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless: \\
\cpp{is_move_constructible<T>::value} and \\
\cpp{is_convertible<U&&, T>::value}.
\end{wordingTextItem}
\end{wordingPara}

% nested copy unwrap.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class U, class E>
constexpr expected<U,E> expected<expected<U,E>,E>::unwrap() const&;
\end{lstlisting}

\begin{wordingPara}

\begin{wordingTextItem}{Returns}
If \cpp{bool(*this)} then \cpp{**this}.
else \cpp{get_unexpected()}
\end{wordingTextItem}

\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{expected<U,E>}.
\end{wordingTextItem}

\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless: \\
\cpp{is_copy_constructible<expected<T,E>>::value} \\
\end{wordingTextItem}

\end{wordingPara}

% copy unwrap.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class T, class E>
constexpr expected<T,E> expected<T,E>::unwrap() const&;
\end{lstlisting}

\begin{wordingPara}

\begin{wordingTextItem}{Returns}
\cpp{*this}.
\end{wordingTextItem}

\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{expected<T,E>}.
\end{wordingTextItem}

\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless: \\
\cpp{T} is not  \cpp{expected<U,E>}  and \\
\cpp{is_copy_constructible<expected<T,E>>::value} \\
\end{wordingTextItem}

\end{wordingPara}

% nested move unwrap.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class U, class E>
expected<U,E> expected<expected<U,E>, E>::unwrap() &&;
\end{lstlisting}

\begin{wordingPara}

\begin{wordingTextItem}{Returns}
If \cpp{bool(*this)} then \cpp{std::move(**this)}.
else \cpp{get_unexpected()}
\end{wordingTextItem}

\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{expected<U,E>}.
\end{wordingTextItem}

\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless: \\
\cpp{is_move_constructible<expected<U,E>>::value} \\
\end{wordingTextItem}

\end{wordingPara}

% move unwrap.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class T, class E>
template expected<T,E> expected<T,E>::unwrap() &&;
\end{lstlisting}

\begin{wordingPara}

\begin{wordingTextItem}{Returns}
\cpp{std::move(**this)}.
\end{wordingTextItem}

\begin{wordingTextItem}{Throws}
Any exception thrown by the selected constructor of \cpp{expected<T,E>}.
\end{wordingTextItem}

\begin{wordingTextItem}{Remarks}
The function shall not participate in overload resolution unless: \\
\cpp{is_move_constructible<expected<T,E>>::value} \\
\end{wordingTextItem}

\end{wordingPara}


\wordingSubSubSec{Factories}{expected.object.factories}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% catch_exception factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class Ex,class F>
expected<T> expected<T>::catch_exception(F&& func);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
if \cpp{has_exception<Ex>()} call the continuation function \cpp{fuct} with the stored exception as parameter.
\end{wordingTextItem}
\begin{wordingTextItem}{Returns}
if \cpp{has_exception<Ex>()} returns the result of the call continuation function \cpp{fuct} possibly wrapped on a \cpp{expected<T>}, 
otherwise, returns \cpp{*this}.
\end{wordingTextItem}
\end{wordingPara}

% map factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class Ex,class F>
'see below' map(F&& func) 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
if \cpp{bool(*this)} returns returns \cpp{expected<decltype(func(move(val))), E>(func(move(val)))}, 
otherwise, returns \cpp{get_unexpected()}.
\end{wordingTextItem}
\end{wordingPara}

% bind factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class Ex,class F>
'see below' bind(F&& func) 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
if \cpp{bool(*this)} returns returns \cpp{unwrap(expected<decltype(func(move(val))), E>(func(move(val))))}, 
otherwise, returns \cpp{get_unexpected()}.
\end{wordingTextItem}
\end{wordingPara}

% then factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class Ex,class F>
'see below' then(F&& func);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
returns \cpp{unwrap(expected<decltype(func(move(*this))), E>(func(move(*this))))}, 
\end{wordingTextItem}
\end{wordingPara}

% catch_error factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class Ex,class F>
expected<T,E> catch_error(F&& func);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
if \cpp{! (*this)} returns \cpp{unwrap(expected<decltype(func(val)), E>(funct(**this)))}, 
if \cpp{! *this} returns the result of the call continuation function \cpp{fuct} possibly wrapped on a \cpp{expected<T,E>}, 
otherwise, returns \cpp{*this}.
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSec{\cpp{expected} as a meta-fuction}{expected.object.meta}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{lstlisting}[language=C++][xleftmargin=0pt]
  template <class E>
  class expected<holder, E>
  {
  public:
    template <class T>
    using type = expected<T,E>
  };
\end{lstlisting}

\wordingSubSec{expected for void}{expected.object.void}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{lstlisting}[language=C++][xleftmargin=0pt]
  template <class E>
  class expected<void, E>
  {
  public:
    typedef void value_type;
    typedef E error_type;
    
    template <class U>
    struct rebind {
      typedef expected<U, error_type> type;
    };
    
     // \ref{expected.object.void.ctor}, constructors
    constexpr expected() noexcept;
    expected(const expected&);
    expected(expected&&) noexcept(see below);
    constexpr explicit expected(in_place_t);     
      
    constexpr expected(unexpected_type<E> const&);
    template <class Err> 
    constexpr expected(unexpected_type<Err> const&);

    // \ref{expected.object.void.dtor}, destructor
    ~expected();

    // \ref{expected.object.void.assign}, assignment
    expected& operator=(const expected&);
    expected& operator=(expected&&) noexcept(see below);
    void emplace();

    // \ref{expected.object.void.swap}, swap
    void swap(expected&) noexcept(see below);

    // \ref{expected.object.void.observe}, observers
    constexpr explicit operator bool() const noexcept;
    void value() const;
    constexpr E const& error() const&;
    constexpr E& error() &;
    constexpr E&& error() &&;
    constexpr unexpected<E>  get_unexpected() const;
    
    template <typename Ex>
    bool has_exception() const;
    
    template constexpr 'see below' unwrap() const&;
    template 'see below' unwrap() &&;

    // \ref{expected.object.void.factories}, factories

    template <typename Ex, typename F>
    expected<void,E> catch_exception(F&& f);

    template <typename F>
      expected<decltype(func()), E> map(F&& func) ;
    template <typename F>
      'see below' bind(F&& func) ;
    template <typename F>
      expected<void,E> catch_error(F&& f);
    template <typename F>
      'see below' then(F&& func);

  private:
    bool has_value;    // exposition only
    union
    {
      unsigned char dummy;  // exposition only
      error_type err;  // exposition only
    };
  };

\end{lstlisting}

\todo{Describe the functions.}



\wordingSubSec{unexpect tag}{expected.unexpect}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% unexpect tag
\begin{lstlisting}[language=C++][xleftmargin=0pt]
struct unexpet_t{};
constexpr unexpet_t unexpet{};
\end{lstlisting}
\noindent


\wordingSubSec{Template Class bad_expected_access}{expected.bad_expected_access}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{lstlisting}[language=C++][xleftmargin=0pt]
namespace std {
  template <class E>
  class bad_expected_access : public logic_error {
  public:
    explicit bad_expected_access(E);
    constexpr error_type const& error() const;
    error_type& error();
  };
}
\end{lstlisting}

The template class \cpp{bad_expected_access} defines the type of objects thrown as exceptions to report the situation where an attempt is made to access the value of a unexpected expected object.

% constructor with string message.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
bad_expected_access::bad_expected_access(E e); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
Constructs an object of class \cpp{bad_expected_access} storing the parameter.
\end{wordingTextItem}
\end{wordingPara}

% error accessor.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
constexpr E const& bad_expected_access::error() const; 
E& bad_expected_access::error(); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
The stored error..
\end{wordingTextItem}
\begin{wordingTextItem}{Remarks}
The first function shall be a \cpp{constexpr} function.
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSec{Expected Relational operators}{expected.relational_op}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\todo{Describe the functions.}

\wordingSubSec{Comparison with \cpp{T}}{expected.comparison_T}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\todo{Describe the functions.}

\wordingSubSec{Comparison with \cpp{unexpected<E>}}{expected.comparison_unexpected_E}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\todo{Describe the functions.}

\wordingSubSec{Specialized algorithms}{expected.specalg}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% swap free function.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class T, class E>
void swap(expected<T,E>& x, expected<T,E>& y) noexcept(noexcept(x.swap(y))); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Effects}
calls \cpp{x.swap(y)}.
\end{wordingTextItem}
\end{wordingPara}


\wordingSubSec{Expected Factories}{expected.factories}

% make_expected move value factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class T>
constexpr expected<typename decay<T>::type> make_expected(T&& v);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{expected<typename decay<T>::type>(std::forward<T>(v))}.
\end{wordingTextItem}
\end{wordingPara}

% make_expected factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
expected<exception_ptr, void> make_expected(); 
template <class E>
expected<E, void> make_expected(); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{expected<E,void>(in_place)}.
\end{wordingTextItem}
\end{wordingPara}

% make_expected_from_error factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class T>
expected<exception_ptr,T> make_expected_from_exception(std::exception_ptr v); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{expected<exception_ptr,T>(unexpected_type<E>(std::forward<E>(v)))}.
\end{wordingTextItem}
\end{wordingPara}

% make_expected_from_error factory.
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class T, class E>
constexpr expected<decay_t<E>,T> make_expected_from_error(E e);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{expected<decay_t<E>,T>(make_unexpected(e));}
\end{wordingTextItem}
\end{wordingPara}


% make_expected_from_error factory (flying exception).
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class T>
constexpr expected<exception_ptr,T> make_expected_from_current_exception(); 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Returns}
\cpp{expected<exception_ptr,T>(make_unexpected_from_current_exception())}
\end{wordingTextItem}
\end{wordingPara}

% make_expected_from_call
\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class F>
constexpr typename expected<result_of<F()>::type make_expected_from_call(F funct);
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Equivalent to}
\begin{lstlisting}
  try
  {
    return make_expected(funct());
  }
  catch (...)
  {
    return make_unexpected_from_current_exception();
  }
\end{lstlisting}
\end{wordingTextItem}
\end{wordingPara}

\wordingSubSec{Hash support}{expected.hash}

\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class T, class E>
struct hash<expected<T,E>>; 
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Requires}
The template specialization \cpp{hash<T>} and \cpp{hash<E>} shall meet the requirements of class template \cpp{hash} (Z.X.Y). The template specialization \cpp{hash<expected<T,E>>} shall meet the requirements of class template \cpp{hash}. For an object \cpp{e} of type \\
\cpp{expected<T,E>}, \cpp{if bool(e)}, \cpp{hash<expected<T,E>>()(e)} shall evaluate to the same value as \cpp{hash<T, E>()(*e);} otherwise it evaluates to an unspecified value if \cpp{E} is \cpp{exception_ptr}  or \cpp{hash<T, E>()(e.error());}.
\end{wordingTextItem}
\end{wordingPara}

\begin{lstlisting}[language=C++][xleftmargin=0pt]
template <class E>
struct hash<expected<void, E>>;
\end{lstlisting}
\begin{wordingPara}
\begin{wordingTextItem}{Requires}
\end{wordingTextItem}
\end{wordingPara}

\section{Implementability}
This proposal can be implemented as pure library extension, without any compiler magic support, in C++14. An almost full reference implementation of this proposal can be found at TBoost.Expected \cite{boost.expected}. 
\section{Acknowledgement}

We are very grateful to Andrei Alexandrescu for his talk, which was the origin of this work.
We thanks also to every one that has contributed to the Haskell either monad, as either's interface was a source of inspiration.
Thanks to Fernando Cacciola, Andrzej Krzemieński and every one that has contributed to the wording and the rationale of N3793 \cite{OptionalRev5}.

Vicente thanks personnaly Evgeny Panasyuk and Johannes Kapfhammer for their remarks on the DO-expression. 

Pierre thanks the IRCAM and Carlos Agon who allowed him to work on this proposal during its internship.

\newpage
\bibliographystyle{plain}
\bibliography{references}

\end{document}