std::unexpected

Определён в заголовочном файле `<expected>`
template< class E > class unexpected;		(начиная с C++23)

Шаблон класса std::unexpected представляет неожиданное значение, хранящееся в std::expected. В частности, std::expected имеет конструкторы с std::unexpected в качестве единственного аргумента, который создаёт объект expected, содержащий неожиданное значение.

Программа некорректна, если она инстанцирует unexpected с типом, не являющимся объектным, типом массива, специализацией std::unexpected или типом с квалификатором cv.

Параметры шаблона

E - тип неожиданного значения. Тип не должен быть типом массива, типом, не являющимся объектным, специализацией std::unexpected или типом с квалификатором cv.

Функции-члены

(конструктор)	создаёт объект `unexpected` (открытая функция-член)
(деструктор) (объявляется неявно)	уничтожает объект `unexpected` вместе с хранящимся значением (открытая функция-член)
operator= (объявляется неявно)	присваивает хранящееся значение (открытая функция-член)
error	предоставляет доступ к хранящемуся значению (открытая функция-член)
swap	меняет хранящееся значение местами (открытая функция-член)

Функции, не являющиеся членами

operator== (C++23)	сравнивает хранящееся значение (шаблон функции)
swap(std::unexpected) (C++23)	специализирует алгоритм `std::swap` (шаблон функции)

std::unexpected::unexpected

constexpr unexpected( const unexpected& ) = default;	(1)
constexpr unexpected( unexpected&& ) = default;	(2)
template< class Err = E > constexpr explicit unexpected( Err&& e );	(3)
template< class... Args > constexpr explicit unexpected( std::in_place_t, Args&&... args );	(4)
template< class U, class... Args > constexpr explicit unexpected( std::in_place_t, std::initializer_list<U> il, Args&&... args );	(5)

Создаёт объект std::unexpected.

1,2) Конструктор копирования/перемещения. Соответственно, копирует или перемещает хранящееся значение.

3) Создаёт хранящееся значение так, как если бы значение типа E непосредственно инициализировалось из std::forward<Err>(e).

Эта перегрузка участвует в разрешении перегрузки только в том случае, если
- std::is_same_v<std::remove_cvref_t<Err>, unexpected> имеет значение false и
- std::is_same_v<std::remove_cvref_t<Err>, std::in_place_t> имеет значение false и
- std::is_constructible_v<E, Err> имеет значение true.

4) Создаёт хранящееся значение так, как если бы значение типа E непосредственно инициализировалось аргументами std::forward<Args>(args)....

Эта перегрузка участвует в разрешении перегрузки только в том случае, если std::is_constructible_v<E, Args...> имеет значение true.

5) Создаёт хранящееся значение так, как если бы значение типа E непосредственно инициализировалось аргументами il, std::forward<Args>(args)....

Эта перегрузка участвует в разрешении перегрузки только в том случае, если std::is_constructible_v<E, std::initializer_list<U>&, Args...> имеет значение true.

Параметры

e	-	значение, которым инициализируется содержащееся значение
args...	-	аргументы, которыми инициализируется содержащееся значение
il	-	список инициализаторов, которым инициализируется содержащееся значение

Исключения

Выбрасывает любое исключение, выбрасываемое конструктором E.

std::unexpected::error

constexpr const E& error() const& noexcept;
constexpr E& error() & noexcept;
constexpr const E&& error() const&& noexcept;
constexpr E&& error() && noexcept;

Возвращает ссылку на хранящееся значение.

std::unexpected::swap

constexpr void swap( unexpected& other ) noexcept(std::is_nothrow_swappable_v<E>);

Меняет хранящиеся значения местами, как если бы это делалось с помощью using std::swap; swap(error(), other.error());.

Программа некорректна, если std::is_swappable_v<E> имеет значение false.

operator==(std::unexpected)

template< class E2 >
friend constexpr bool operator==( unexpected& x, std::unexpected<E2>& y );

Сравнивает хранящиеся значения так, как если бы это делалось с помощью return x.error() == y.error().

Если выражение x.error() == e.error() некорректно или его результат нельзя преобразовать в bool, программа некорректна.

Эта функция не видна при обычном поиске без уточнения или поиске с уточнением и может быть найдена только с помощью поиска с учётом аргументов, если std::unexpected<E> является ассоциированным классом аргументов.

swap(std::unexpected)

friend constexpr void
swap( unexpected& x, unexpected& y ) noexcept(noexcept(x.swap(y)));

Эквивалентна x.swap(y).

Эта перегрузка участвует в разрешении перегрузки только в том случае, если std::is_swappable_v<E> имеет значение true.

Вывод типов шаблонных аргументов

template< class E >
unexpected(E) -> unexpected<E>;

(начиная с C++23)

Для unexpected предусмотрено руководство по выводу типов, позволяющее выводить тип из аргумента конструктора.

Примечания

До C++17 имя std::unexpected обозначало функцию, вызываемую средой выполнения C++ при нарушении динамической спецификации исключений.

Пример

#include <expected>
#include <iostream>

enum class error
{
    compile_time_error,
    runtime_error
};

[[nodiscard]] auto unexpected_runtime_error() -> std::expected<int, error>
{
    return std::unexpected(error::runtime_error);
}

int main()
{
    std::expected<double, int> ex = std::unexpected(3);

    if (!ex)
        std::cout << "ex contains an error value\n";

    if (ex == std::unexpected(3))
        std::cout << "The error value is equal to 3\n";

    const auto e = unexpected_runtime_error();

    e.and_then([](const auto& e) -> std::expected<int, error>
    {
        std::cout << "and_then: " << int(e); // not printed
        return {};
    })
    .or_else([](const auto& e) -> std::expected<int, error>
    {
        std::cout << "or_else: " << int(e); // prints this line
        return {};
    });
}

Вывод:

ex contains an error value
The error value is equal to 3
or_else: 1

См. также

(конструктор)	создаёт объект `expected` (открытая функция-член)
operator== (C++23)	сравнивает объекты `expected` (шаблон функции)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/utility/expected/unexpected