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 "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/nonstd -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.

Not provided are reference-type expecteds. expected lite doesn't handle overloaded address of operators.

For more examples, see [1].

License

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

Configuration macros

-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

Interface of expected

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

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

Implementation notes

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) (PDF). (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, [email protected].

[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).

Appendix

A.1 expected lite test specification

unexpected_type<>: Disallows default construction
unexpected_type<>: Disallows default construction, std::exception_ptr specialization
unexpected_type<>: Allows to copy-construct from error_type
unexpected_type<>: Allows to copy-construct from error_type, std::exception_ptr specialization
unexpected_type<>: Allows to move-construct from error_type
unexpected_type<>: Allows to move-construct from error_type, std::exception_ptr specialization
unexpected_type<>: Allows to copy-construct from an exception, std::exception_ptr specialization
unexpected_type<>: Allows to observe its value
unexpected_type<>: Allows to observe its value, std::exception_ptr specialization
unexpected_type<>: Allows to modify its value
unexpected_type<>: Allows to modify its value, std::exception_ptr specialization
unexpected_type<>: Provides relational operators
unexpected_type<>: Provides relational operators, std::exception_ptr specialization
is_unexpected<X>: Is true for unexpected_type
is_unexpected<X>: Is false for non-unexpected_type (int)
make_unexpected(): Allows to create an unexpected_type<E> from an E
make_unexpected_from_current_exception(): Allows to create an unexpected_type<std::exception_ptr> from the current exception
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
expected<>: Allows default construction
expected<>: Allows to copy-construct from value_type
expected<>: Allows to move-construct from value_type
expected<>: Allows to copy-construct from expected<>
expected<>: Allows to move-construct from expected<>
expected<>: Allows to in-place-construct value_type
expected<>: Allows to copy-construct from unexpected_type<>
expected<>: Allows to move-construct from unexpected_type<>
expected<>: Allows to in-place-construct unexpected_type<>
expected<>: Allows to copy-assign from expected<>
expected<>: Allows to move-assign from expected<>
expected<>: Allows to copy-assign from type convertible to value_type
expected<>: Allows to move-assign from type convertible to value_type
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 reference
expected<>: Allows to observe its value via a r-value reference
expected<>: Allows to modify its value via a 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 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<>: Provides relational operators
...