Skip to content
expected lite - Expected objects in C++11 and later in a single-file header-only library
C++ Python CMake Batchfile
Branch: master
Clone or download
mabraham and martinmoene Improve is_nothrow_swappable for icpc (#31, thanks to @mabraham)
Works with icpc 19 in at least C++-14 mode.

Fixes #30
Latest commit 6fad61b Jul 25, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmake Make CMake install arch independent (nonstd-lite issue 32) Mar 24, 2019
example Improve macro usage consistency (package_config_version) May 23, 2019
include/nonstd Improve is_nothrow_swappable for icpc (#31, thanks to @mabraham) Jul 25, 2019
project/CodeBlocks Release 0.3.0 Apr 25, 2019
script [skip ci] Change vcpkg install to use CMake May 27, 2019
test Prevent compilation error in test for issue #29 (wip) May 27, 2019
.gitattributes Initial code commit Mar 13, 2016
.gitignore Ignore test executable from sources Jun 2, 2018
.travis.yml Fix force use of nonstd::expected in CI (thanks to @flexferrum) Nov 6, 2018
CHANGES.txt Initial code commit Mar 13, 2016
CMakeLists.txt
LICENSE.txt Add license file Jun 4, 2018
Notes.md Add, implement CMake files Mar 26, 2016
README.md [skip ci] Use ```Cpp consistently May 30, 2019
appveyor.yml Align Appveyor configuration (plan 9) Dec 24, 2018
conanfile.py [skip ci] Add settings options to conanfile (thanks to @ngrodzitski) May 14, 2019

README.md

expected lite: expected objects for C++11 and later

Language License Build Status Build status Version download Conan Try it online

expected lite is a single-file header-only library for objects that either represent a valid value or an error that you can pass by value. It is intended for use with C++11 and later. The library is based on the std::expected proposal [1] .

Contents

Example usage

#include "nonstd/expected.hpp"

#include <cstdlib>
#include <iostream>
#include <string>

using namespace nonstd;
using namespace std::literals;

auto to_int( char const * const text ) -> expected<int, std::string> 
{
    char * pos = nullptr;
    auto value = strtol( text, &pos, 0 );

    if ( pos != text ) return value;
    else               return make_unexpected( "'"s + text + "' isn't a number" );
}

int main( int argc, char * argv[] )
{
    auto text = argc > 1 ? argv[1] : "42";

    auto ei = to_int( text );

    if ( ei ) std::cout << "'" << text << "' is " << *ei << ", ";
    else      std::cout << "Error: " << ei.error();
}

Compile and run

prompt> g++ -std=c++14 -Wall -I../include -o 01-basic.exe 01-basic.cpp && 01-basic.exe 123 && 01-basic.exe abc
'123' is 123, Error: 'abc' isn't a number

In a nutshell

expected lite is a single-file header-only library to represent value objects that either contain a valid value or an error. The library is a partly implementation of the proposal for std::expected [1,2,3] for use with C++11 and later.

Some Features and properties of expected lite are ease of installation (single header), default and explicit construction of an expected, construction and assignment from a value that is convertible to the underlying type, copy- and move-construction and copy- and move-assignment from another expected of the same type, testing for the presence of a value, operators for unchecked access to the value or the error (pointer or reference), value() and value_or() for checked access to the value, relational operators, swap() and various factory functions.

expected lite shares the approach to in-place tags with any-lite, optional-lite and with variant-lite and these libraries can be used together.

Not provided are reference-type expecteds. expected lite doesn't honour triviality of value and error types. expected lite doesn't handle overloaded address of operators.

For more examples, see [1].

License

expected lite is distributed under the Boost Software License.

Dependencies

expected lite has no other dependencies than the C++ standard library.

Installation

expected lite is a single-file header-only library. Put expected.hpp directly into the project source tree or somewhere reachable from your project.

Synopsis

Contents

Configuration macros

Standard selection macro

-Dnsel_CPLUSPLUS=199711L
Define this macro to override the auto-detection of the supported C++ standard, or if your compiler does not set the __cplusplus macro correctly.

Select std::expected or nonstd::expected

At default, expected lite uses std::expected if it is available and lets you use it via namespace nonstd. You can however override this default and explicitly request to use std::expected or expected lite's nonstd::expected as nonstd::expected via the following macros.

-Dnsel_CONFIG_SELECT_EXPECTED=nsel_EXPECTED_DEFAULT
Define this to nsel_EXPECTED_STD to select std::expected as nonstd::expected. Define this to nsel_EXPECTED_NONSTD to select nonstd::expected as nonstd::expected. Default is undefined, which has the same effect as defining to nsel_EXPECTED_DEFAULT.

-Dnsel_P0323R=7 (default)
Define this to the proposal revision number to control the presence and behavior of features (see tables). Default is 7 for the latest revision.

Enable compilation errors

-Dnsel_CONFIG_CONFIRMS_COMPILATION_ERRORS=0
Define this macro to 1 to experience the by-design compile-time errors of the library in the test suite. Default is 0.

Types in namespace nonstd

Purpose Type Note / Object
Expected template<typename T, typename E = std::exception_ptr>
class expected;
nsel_P0323 <= 2
Expected template<typename T, typename E>
class expected;
nsel_P0323 > 2
Error type template<typename E>
class unexpected_type;
 
Error type template<>
class unexpected_type<std::exception_ptr>;
nsel_P0323 <= 2
Error type template<typename E>
class unexpected;
>= C++17
Traits template<typename E>
struct is_unexpected;
nsel_P0323 <= 3
In-place value construction struct in_place_t; in_place_t in_place{};
In-place error construction struct in_place_unexpected_t; in_place_unexpected_t
unexpect{};
In-place error construction struct in_place_unexpected_t; in_place_unexpected_t
in_place_unexpected{};
Error reporting class bad_expected_access;  

Interface of expected

Kind Method Result
Construction [constexpr] expected() noexcept(...) an object with default value
  [constexpr] expected( expected const & other ) initialize to contents of other
  [constexpr] expected( expected && other ) move contents from other
  [constexpr] expected( value_type const & value ) initialize to value
  [constexpr] expected( value_type && value ) noexcept(...) move from value
  [constexpr] explicit expected( in_place_t, Args&&... args ) construct value in-place from args
  [constexpr] explicit expected( in_place_t,
 std::initializer_list<U> il, Args&&... args )
construct value in-place from args
  [constexpr] expected( unexpected_type const & error ) initialize to error
  [constexpr] expected( unexpected_type && error ) move from error
  [constexpr] explicit expected( in_place_unexpected_t,
 Args&&... args )
construct error in-place from args
  [constexpr] explicit expected( in_place_unexpected_t,
 std::initializer_list<U> il, Args&&... args )
construct error in-place from args
Destruction ~expected() destruct current content
Assignment expected operator=( expected const & other ) assign contents of other;
destruct current content, if any
  expected & operator=( expected && other ) noexcept(...) move contents of other
  expected & operator=( U && v ) move value from v
  expected & operator=( unexpected_type const & u ) initialize to unexpected
  expected & operator=( unexpected_type && u ) move from unexpected
  template<typename... Args>
void emplace( Args &&... args )
emplace from args
  template<typename U, typename... Args>
void emplace( std::initializer_list<U> il, Args &&... args )
emplace from args
Swap void swap( expected & other ) noexcept swap with other
Observers constexpr value_type const * operator->() const pointer to current content (const);
must contain value
  value_type * operator->() pointer to current content (non-const);
must contain value
  constexpr value_type const & operator *() const & the current content (const ref);
must contain value
  constexpr value_type && operator *() && the current content (non-const ref);
must contain value
  constexpr explicit operator bool() const noexcept true if contains value
  constexpr has_value() const noexcept true if contains value
  constexpr value_type const & value() const & current content (const ref);
see note 1
  value_type & value() & current content (non-const ref);
see note 1
  constexpr value_type && value() && move from current content;
see note 1
  constexpr error_type const & error() const & current error (const ref);
must contain error
  error_type & error() & current error (non-const ref);
must contain error
  constexpr error_type && error() && move from current error;
must contain error
  constexpr unexpected_type get_unexpected() const the error as unexpected<>;
must contain error
  template<typename Ex>
bool has_exception() const
true of contains exception (as base)
  value_type value_or( U && v ) const & value or move from v
  value_type value_or( U && v ) && move from value or move from v
  ...  

Note 1: checked access: if no content, for std::exception_ptr rethrows error(), otherwise throws bad_expected_access(error()).

Algorithms for expected

Kind Function
Comparison with expected  
== != template<typename T1, typename E1, typename T2, typename E2>
constexpr bool operator op(
 expected<T1,E1> const & x,
 expected<T2,E2> const & y )
Comparison with expected nsel_P0323R <= 2
< > <= >= template<typename T, typename E>
constexpr bool operator op(
 expected<T,E> const & x,
 expected<T,E> const & y )
Comparison with unexpected_type  
== != template<typename T1, typename E1, typename E2>
constexpr bool operator op(
 expected<T1,E1> const & x,
 unexpected_type<E2> const & u )
  template<typename T1, typename E1, typename E2>
constexpr bool operator op(
 unexpected_type<E2> const & u,
 expected<T1,E1> const & x )
Comparison with unexpected_type nsel_P0323R <= 2
< > <= >= template<typename T, typename E>
constexpr bool operator op(
 expected<T,E> const & x,
 unexpected_type<E> const & u )
  template<typename T, typename E>
constexpr bool operator op(
 unexpected_type<E> const & u,
 expected<T,E> const & x )
Comparison with T  
== != template<typename T, typename E>
constexpr bool operator op(
 expected<T,E> const & x,
 T const & v )
  template<typename T, typename E>
constexpr bool operator op(
 T const & v,
 expected<T,E> const & x )
Comparison with T nsel_P0323R <= 2
< > <= >= template<typename T, typename E>
constexpr bool operator op(
 expected<T,E> const & x,
 T const & v )
  template<typename T, typename E>
constexpr bool operator op(
 T const & v,
 expected<T,E> const & x )
Specialized algorithms  
Swap template<typename T, typename E>
void swap(
 expected<T,E> & x,
 expected<T,E> & y ) noexcept( noexcept( x.swap(y) ) )
Make expected from nsel_P0323R <= 3
 Value template<typename T>
constexpr auto make_expected( T && v ) ->
 expected< typename std::decay<T>::type>
 Nothing auto make_expected() -> expected<void>
 Current exception template<typename T>
constexpr auto make_expected_from_current_exception() -> expected<T>
 Exception template<typename T>
auto make_expected_from_exception( std::exception_ptr v ) -> expected<T>
 Error template<typename T, typename E>
constexpr auto make_expected_from_error( E e ) ->
 expected<T, typename std::decay<E>::type>
 Call template<typename F>
auto make_expected_from_call( F f ) ->
 expected< typename std::result_of<F()>::type>
 Call, void specialization template<typename F>
auto make_expected_from_call( F f ) -> expected<void>

Interface of unexpected_type

Kind Method Result
Construction unexpected_type() = delete; no default construction
  constexpr explicit unexpected_type( E const & error ) copy-constructed from an E
  constexpr explicit unexpected_type( E && error ) move-constructed from an E
Observers constexpr error_type const & value() const can observe contained error
  error_type & value() can modify contained error

Algorithms for unexpected_type

Kind Function
Comparison with unexpected  
== != template<typename E>
constexpr bool operator op(
 unexpected_type<E> const & x,
 unexpected_type<E> const & y )
Comparison with unexpected nsel_P0323R <= 2
< > <= >= template<typename E>
constexpr bool operator op(
 unexpected_type<E> const & x,
 unexpected_type<E> const & y )
Comparison with exception_ptr  
== != constexpr bool operator op(
 unexpected_type<std::exception_ptr> const & x,
 unexpected_type<std::exception_ptr> const & y )
Comparison with exception_ptr nsel_P0323R <= 2
< > <= >= constexpr bool operator op(
 unexpected_type<std::exception_ptr> const & x,
 unexpected_type<std::exception_ptr> const & y )
Specialized algorithms  
Make unexpected from  
 Error template<typename E>
[constexpr] auto make_unexpected( E && v) ->
 unexpected_type< typename std::decay<E>::type>
Make unexpected from nsel_P0323R <= 3
 Current exception [constexpr] auto make_unexpected_from_current_exception() ->
 unexpected_type< std::exception_ptr>

Comparison with like types

Feature
std::pair
std:: optional std:: expected nonstd:: expected Boost. Expected Nonco expected Andrei Expected Hagan required
More information see [14] see [5] see [1] this work see [4] see [7] see [8] see [13]
C++03 yes no no no/not yet no (union) no no yes
C++11 yes no no yes yes yes yes yes
C++14 yes no no yes yes yes yes yes
C++17 yes yes no yes yes yes yes yes
DefaultConstructible T param yes yes yes yes no no no
In-place construction no yes yes yes yes yes no no
Literal type yes yes yes yes yes no no no
Disengaged information possible no yes yes yes yes yes no
Vary disengaged type yes no yes yes yes no no no
Engaged nonuse throws no no no no error_traits no no yes
Disengaged use throws no yes, value() yes, value() yes, value() yes,
value()
yes,
get()
yes,
get()
n/a
Proxy (rel.ops) no yes yes yes yes no no no
References no yes no/not yet no/not yet no/not yet yes no no
Chained visitor(s) no no yes maybe yes no no no

Note 1: std::experimental::expected

Note 2: sources for Nonco expected, Andrei Expected and Hagan required can befound in the spike-expected repository.

Reported to work with

Implementation notes

Other implementations of expected

Notes and references

[1] Vicente J. Botet Escriba. p0323 - A proposal to add a utility class to represent expected object (latest) (HTML). (r7, r6, r5, r4, r3, r2, r1, r0, draft).

[2] Vicente J. Botet Escriba. JASEL: Just a simple experimental library for C++. Reference implementation of expected.

[3] Vicente J. Botet Escriba. Expected - An exception-friendly Error Monad. C++Now 2014. 24 September 2014.

[4] Pierre Talbot. Boost.Expected. Unofficial Boost candidate. 5 May 2013. GitHub, GSoC 2013 Proposal, boost@lists.boost.org.

[5] Fernando Cacciola and Andrzej Krzemieński. A proposal to add a utility class to represent optional objects (Revision 4). ISO/IEC JTC1 SC22 WG21 N3672 2013-04-19.

[6] Andrzej Krzemieński, Optional library implementation in C++11.

[7] Anto Nonco. Extending expected to deal with references. 27 May 2013.

[8] Andrei Alexandrescu. Systematic Error Handling in C++. Prepared for The C++and Beyond Seminar 2012. Video. Slides.

[9] Andrei Alexandrescu. Choose your Poison: Exceptions or Error Codes? (PDF). ACCU Conference 2007.

[10] Andrei Alexandrescu. The Power of None (PPT). Northwest C++ Users' Group. May 17th, 2006.

[11] Jon Jagger. A Return Type That Doesn't Like Being Ignored. Overload issue 53, February 2003.

[12] Andrei Alexandrescu. Error Handling in C++: Are we inching towards a total solution?. ACCU Conference 2002.

[13] Ken Hagan et al. Exploding return codes. comp.lang.c++.moderated. 11 February 2000.

[14] std::pair. cppreference.com

[15] Niall Douglas. Outcome. Very lightweight outcome<T> and result<T> (non-Boost edition).

[16] Niall Douglas. p0762 - Concerns about expected<T, E> from the Boost.Outcome peer review. 15 October 2017.

Appendix

A.1 Compile-time information

The version of expected lite is available via tag [.version]. The following tags are available for information on the compiler and on the C++ standard library used: [.compiler], [.stdc++], [.stdlanguage] and [.stdlibrary].

A.2 Expected lite test specification

unexpected_type: Disallows default construction
unexpected_type: Allows to copy-construct from unexpected_type, default
unexpected_type: Allows to move-construct from unexpected_type, default
unexpected_type: Allows to in-place-construct
unexpected_type: Allows to in-place-construct from initializer_list
unexpected_type: Allows to copy-construct from error_type
unexpected_type: Allows to move-construct from error_type
unexpected_type: Allows to copy-construct from unexpected_type, explicit converting
unexpected_type: Allows to copy-construct from unexpected_type, non-explicit converting
unexpected_type: Allows to move-construct from unexpected_type, explicit converting
unexpected_type: Allows to move-construct from unexpected_type, non-explicit converting
unexpected_type: Allows to copy-assign from unexpected_type, default
unexpected_type: Allows to move-assign from unexpected_type, default
unexpected_type: Allows to copy-assign from unexpected_type, converting
unexpected_type: Allows to move-assign from unexpected, converting
unexpected_type: Allows to observe its value via a l-value reference
unexpected_type: Allows to observe its value via a r-value reference
unexpected_type: Allows to modify its value via a l-value reference
unexpected_type: Allows to be swapped
unexpected_type<std::exception_ptr>: Disallows default construction
unexpected_type<std::exception_ptr>: Allows to copy-construct from error_type
unexpected_type<std::exception_ptr>: Allows to move-construct from error_type
unexpected_type<std::exception_ptr>: Allows to copy-construct from an exception
unexpected_type<std::exception_ptr>: Allows to observe its value
unexpected_type<std::exception_ptr>: Allows to modify its value
unexpected_type: Provides relational operators
unexpected_type: Provides relational operators, std::exception_ptr specialization
make_unexpected(): Allows to create an unexpected_type<E> from an E
unexpected: C++17 and later provide unexpected_type as unexpected
bad_expected_access: Disallows default construction
bad_expected_access: Allows construction from error_type
bad_expected_access: Allows to observe its error
bad_expected_access: Allows to change its error
bad_expected_access: Provides non-empty what()
expected: Allows to default construct
expected: Allows to copy-construct from expected: value
expected: Allows to copy-construct from expected: error
expected: Allows to move-construct from expected: value
expected: Allows to move-construct from expected: error
expected: Allows to copy-construct from expected; value, explicit converting
expected: Allows to copy-construct from expected; error, explicit converting
expected: Allows to copy-construct from expected; value, non-explicit converting
expected: Allows to copy-construct from expected; error, non-explicit converting
expected: Allows to move-construct from expected; value, explicit converting
expected: Allows to move-construct from expected; error, explicit converting
expected: Allows to move-construct from expected; value, non-explicit converting
expected: Allows to move-construct from expected; error, non-explicit converting
expected: Allows to forward-construct from value, explicit converting
expected: Allows to forward-construct from value, non-explicit converting
expected: Allows to in-place-construct value
expected: Allows to in-place-construct value from initializer_list
expected: Allows to copy-construct from unexpected, explicit converting
expected: Allows to copy-construct from unexpected, non-explicit converting
expected: Allows to move-construct from unexpected, explicit converting
expected: Allows to move-construct from unexpected, non-explicit converting
expected: Allows to in-place-construct error
expected: Allows to in-place-construct error from initializer_list
expected: Allows to copy-assign from expected, value
expected: Allows to copy-assign from expected, error
expected: Allows to move-assign from expected, value
expected: Allows to move-assign from expected, error
expected: Allows to forward-assign from value
expected: Allows to copy-assign from unexpected
expected: Allows to move-assign from unexpected
expected: Allows to emplace value
expected: Allows to emplace value from initializer_list
expected: Allows to be swapped
expected: Allows to observe its value via a pointer
expected: Allows to observe its value via a pointer to constant
expected: Allows to modify its value via a pointer
expected: Allows to observe its value via a l-value reference
expected: Allows to observe its value via a r-value reference
expected: Allows to modify its value via a l-value reference
expected: Allows to modify its value via a r-value reference
expected: Allows to observe if it contains a value (or error)
expected: Allows to observe its value
expected: Allows to modify its value
expected: Allows to move its value
expected: Allows to observe its error
expected: Allows to modify its error
expected: Allows to move its error
expected: Allows to observe its error as unexpected
expected: Allows to query if it contains an exception of a specific base type
expected: Allows to observe its value if available, or obtain a specified value otherwise
expected: Allows to move its value if available, or obtain a specified value otherwise
expected: Throws bad_expected_access on value access when disengaged
expected<void>: Allows to default-construct
expected<void>: Allows to copy-construct from expected<void>: value
expected<void>: Allows to copy-construct from expected<void>: error
expected<void>: Allows to move-construct from expected<void>: value
expected<void>: Allows to move-construct from expected<void>: error
expected<void>: Allows to in-place-construct
expected<void>: Allows to copy-construct from unexpected, explicit converting
expected<void>: Allows to copy-construct from unexpected, non-explicit converting
expected<void>: Allows to move-construct from unexpected, explicit converting
expected<void>: Allows to move-construct from unexpected, non-explicit converting
expected<void>: Allows to in-place-construct unexpected_type
expected<void>: Allows to in-place-construct error from initializer_list
expected<void>: Allows to copy-assign from expected, value
expected<void>: Allows to copy-assign from expected, error
expected<void>: Allows to move-assign from expected, value
expected<void>: Allows to move-assign from expected, error
expected<void>: Allows to emplace value
expected<void>: Allows to be swapped
expected<void>: Allows to observe if it contains a value (or error)
expected<void>: Allows to observe its value
expected<void>: Allows to observe its error
expected<void>: Allows to modify its error
expected<void>: Allows to move its error
expected<void>: Allows to observe its error as unexpected
expected<void>: Allows to query if it contains an exception of a specific base type
expected<void>: Throws bad_expected_access on value access when disengaged
operators: Provides expected relational operators
swap: Allows expected to be swapped
std::hash: Allows to compute hash value for expected
You can’t perform that action at this time.