Awesome

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

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
• In a nutshell
• License
• Dependencies
• Installation
• Synopsis
• Comparison with like types
• Reported to work with
• Implementation notes
• Other implementations of expected
• Notes and references
• Appendix

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.

Version 0.7.0 introduces the monadic operations of propsoal p2505.

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
• Types in namespace nonstd
• Interface of expected
• Algorithms for expected
• Interface of unexpected_type
• Algorithms for unexpected_type

Configuration

Tweak header

If the compiler supports __has_include(), expected lite supports the tweak header mechanism. Provide your tweak header as nonstd/expected.tweak.hpp in a folder in the include-search-path. In the tweak header, provide definitions as documented below, like #define expected_CPLUSPLUS 201103L.

Standard selection macro

-D<b>nsel_CPLUSPLUS</b>=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.

-D<b>nsel_CONFIG_SELECT_EXPECTED</b>=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.

-D<b>nsel_P0323R</b>=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.

Define WIN32_LEAN_AND_MEAN

-D<b>nsel_CONFIG_WIN32_LEAN_AND_MEAN</b>=1
Define this to 0 if you want to omit automatic definition of WIN32_LEAN_AND_MEAN. Default is 1 when _MSC_VER is present.

Disable C++ exceptions

-D<b>nsel_CONFIG_NO_EXCEPTIONS</b>=0 Define this to 1 if you want to compile without exceptions. If not defined, the header tries and detect if exceptions have been disabled (e.g. via -fno-exceptions or /kernel). Default determined in header.

Enable SEH exceptions

-D<b>nsel_CONFIG_NO_EXCEPTIONS_SEH</b>=0 Define this to 1 or 0 to control the use of SEH when C++ exceptions are disabled (see above). If not defined, the header tries and detect if SEH is available if C++ exceptions have been disabled (e.g. via -fno-exceptions or /kernel). Default determined in header.

Enable compilation errors

-D<b>nsel_CONFIG_CONFIRMS_COMPILATION_ERRORS</b>=0
Define this macro to 1 to experience the by-design compile-time errors of the library in the test suite. Default is 0.

Configure P2505 monadic operations

By default, expected lite provides monadic operations as described in P2505R5. You can disable these operations by defining the following macro.

-D<b>nsel_P2505R</b>=0

You can use the R3 revision of P2505, which lacks error_or, and uses remove_cvref for transforms, by defining the following macro.

-D<b>nsel_P2505R</b>=3

Types in namespace nonstd

Interface of expected

<a id="note1"></a>Note 1: checked access: if no content, for std::exception_ptr rethrows error(), otherwise throws bad_expected_access(error()).

Algorithms for expected

Interface of unexpected_type

Algorithms for unexpected_type

<a id="comparison"></a>

Comparison with like types

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

TBD

Implementation notes

TBD

Other implementations of expected

• Simon Brand. C++11/14/17 std::expected with functional-style extensions. Single-header.
• Isabella Muerte. MNMLSTC Core (C++11).
• Vicente J. Botet Escriba. stdmake's expected (C++17).
• Facebook. Folly's Expected.h (C++14).

Notes and references

[1] Vicente J. Botet Escriba. p0323 - A proposal to add a utility class to represent expected object (latest) (HTML). (r12, r11, r10, r9, r8, 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<T> 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.

[17] Jeff Garland. p2505 - Monadic Functions for std::expected (HTML). (r0, r1, r2, r3, r4, r5).

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
make_unexpected(): Allows to in-place 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 default construct from noncopyable, noncopyable value type
expected: Allows to default construct from noncopyable, noncopyable error type
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 move-assign from move-only 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: Allows to observe its unexpected value, or fallback to the specified value with error_or [monadic p2505r4]
expected: Allows to map value with and_then [monadic p2505r3]
expected: Allows to map unexpected with or_else [monadic p2505r3]
expected: Allows to transform value [monadic p2505r3]
expected: Allows to map errors with transform_error [monadic p2505r3]
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
expected<void>: Allows to observe unexpected value, or fallback to a default value with error_or [monadic p2505r4]
expected<void>: Allows to call argless functions with and_then [monadic p2505r3]
expected<void>: Allows to map to expected or unexpected with or_else [monadic p2505r3]
expected<void>: Allows to assign a new expected value using transform [monadic p2505r3]
expected<void>: Allows to map unexpected error value via transform_error [monadic p2505r3]
operators: Provides expected relational operators
operators: Provides expected relational operators (void)
swap: Allows expected to be swapped
std::hash: Allows to compute hash value for expected
tweak header: reads tweak header if supported [tweak]