Class result<T, E>

///////////////////////////////////////////////////////////////////////////// /// \brief The class template result manages result results from APIs, /// while encoding possible failure conditions. /// /// A common use-case for result is the return value of a function that /// may fail. As opposed to other approaches, such as std::pair<T,bool> /// or std::optional, result more accurately conveys the intent of the /// user along with the failure condition to the caller. This effectively /// produces an orthogonal error handling mechanism that allows for exception /// safety while also allowing discrete testability of the return type. /// /// result<T,E> types may contain a T value, which signifies that an /// operation succeeded in producing the result value of type T. If an /// result does not contain a T value, it will always contain an E /// error condition instead. /// /// An result<T,E> can always be queried for a possible error case by /// calling the error() function, even if it contains a value. /// In the case that a result<T,E> contains a value object, this will /// simply return an E object constructed through default aggregate /// construction, as if through the expression E{}, which is assumed to be /// a “valid” (no-error) state for an E type. /// For example: /// /// * std::error_code{} produces a default-construct error-code, which is /// the “no error” state, /// * integral (or enum) error codes produce a 0 value (no error), thanks to /// zero-initialization, /// * std::exception_ptr{} produces a null-pointer, /// * std::string{} produces an empty string "", /// * etc. /// /// When a result<T,E> contains either a value or error, the storage for /// that object is guaranteed to be allocated as part of the result /// object’s footprint, i.e. no dynamic memory allocation ever takes place. /// Thus, a result object models an object, not a pointer, even though the /// operator*() and operator->() are defined. /// /// When an object of type result<T,E> is contextually converted to /// bool, the conversion returns true if the object contains a value and /// false if it contains an error. /// /// result objects do not have a “valueless” state like variants do. /// Once a result has been constructed with a value or error, the /// active underlying type can only be changed through assignment which may /// is only enabled if construction is guaranteed to be non-throwing. This /// ensures that a valueless state cannot occur naturally. /// /// Example Use: /// \code /// auto to_string(int x) -> resultstd::string /// { /// try { /// return std::stoi(x); /// } catch (const std::invalid_argument&) { /// return fail(std::errc::invalid_argument); /// } catch (const std::std::out_of_range&) { /// return fail(std::errc::result_out_of_range); /// } /// } /// \endcode /// /// \note If using C++17 or above, fail can be replaced with /// failure{...} thanks to CTAD. /// /// \tparam T the underlying value type /// \tparam E the underlying error type ///////////////////////////////////////////////////////////////////////////