Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit

Otherwise they cause noise when this library is used as a git
submodule and a CMake subdirectory in a project like this:

  Changes not staged for commit:
    (use "git add <file>..." to update what will be committed)
    (use "git restore <file>..." to discard changes in working directory)
    (commit or discard the untracked or modified content in submodules)
	  modified:   vendor/expected (untracked content)

Running `cmake .` in such a project creates CMake artifacts and
then `git status` reports them "untracked content".

Signed-off-by: Vratislav Podzimek <>

Git stats


Failed to load latest commit information.
Latest commit message
Commit time
February 24, 2023 11:52
March 15, 2023 10:28
February 15, 2023 16:34
November 24, 2022 13:02
October 27, 2017 12:08
November 24, 2022 19:54
October 28, 2017 14:17


Single header implementation of std::expected with functional-style extensions.

Documentation Status Clang + GCC: Linux Build Status MSVC: Windows Build Status

Available on Vcpkg and Conan.

std::expected is proposed as the preferred way to represent object which will either have an expected value, or an unexpected value giving information about why something failed. Unfortunately, chaining together many computations which may fail can be verbose, as error-checking code will be mixed in with the actual programming logic. This implementation provides a number of utilities to make coding with expected cleaner.

For example, instead of writing this code:

std::expected<image,fail_reason> get_cute_cat (const image& img) {
    auto cropped = crop_to_cat(img);
    if (!cropped) {
      return cropped;

    auto with_tie = add_bow_tie(*cropped);
    if (!with_tie) {
      return with_tie;

    auto with_sparkles = make_eyes_sparkle(*with_tie);
    if (!with_sparkles) {
       return with_sparkles;

    return add_rainbow(make_smaller(*with_sparkles));

You can do this:

tl::expected<image,fail_reason> get_cute_cat (const image& img) {
    return crop_to_cat(img)

The interface is the same as std::expected as proposed in p0323r3, but the following member functions are also defined. Explicit types are for clarity.

  • map: carries out some operation on the stored object if there is one.
    • tl::expected<std::size_t,std::error_code> s =;
  • map_error: carries out some operation on the unexpected object if there is one.
    • my_error_code translate_error (std::error_code);
    • tl::expected<int,my_error_code> s = exp_int.map_error(translate_error);
  • and_then: like map, but for operations which return a tl::expected.
    • tl::expected<ast, fail_reason> parse (const std::string& s);
    • tl::expected<ast, fail_reason> exp_ast = exp_string.and_then(parse);
  • or_else: calls some function if there is no value stored.
    • exp.or_else([] { throw std::runtime_error{"oh no"}; });

p0323r3 specifies calling .error() on an expected value, or using the * or -> operators on an unexpected value, to be undefined behaviour. In this implementation it causes an assertion failure. The implementation of assertions can be overridden by defining the macro TL_ASSERT(boolean_condition) before #including <tl/expected.hpp>; by default, assert(boolean_condition) from the <cassert> header is used. Note that correct code would not rely on these assertions.

Compiler support

Tested on:

  • Linux
    • clang++ 3.5, 3.6, 3.7, 3.8, 3.9, 4, 5, 6, 7, 8, 9, 10, 11
    • g++ 4.8, 4.9, 5.5, 6.4, 7.5, 8, 9, 10
  • Windows
    • MSVC 2015, 2017, 2019, 2022


To the extent possible under law, Sy Brand has waived all copyright and related or neighboring rights to the expected library. This work is published from: United Kingdom.