std::ios_base::failure

Определён в заголовочном файле `<ios>`
class failure;

Класс std::ios_base::failure определяет объект исключения, который выбрасывается функциями библиотеки ввода-вывода при сбое.

std::ios_base::failure может быть определён либо как вложенный класс std::ios_base, либо как псевдоним (typedef) другого класса с эквивалентной функциональностью.

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

Диаграмма наследования	(до C++11)
Диаграмма наследования	(начиная с C++11)

Методы

(constructor)	создаёт новый объект `failure` с заданным сообщением (открытый метод)
operator=	заменяет объект `failure` (открытый метод)
what	возвращает поясняющую строку (открытый метод)

std::ios_base::failure::failure

explicit failure( const std::string& message );	(1)	(до C++11)
explicit failure( const std::string& message, const std::error_code& ec = std::io_errc::stream );	(1)		(начиная с C++11)
explicit failure( const char* message, const std::error_code& ec = std::io_errc::stream );	(2)	(начиная с C++11)
failure( const failure& other );	(3)	(до C++11)
failure( const failure& other ) noexcept;	(3)		(начиная с C++11)

1,2) Создаёт объект исключения, используя message в качестве поясняющей строки, которую впоследствии можно получить с помощью what(). ec используется для определения конкретной причины сбоя.(начиная с C++11)

3) Конструктор копирования. Инициализирует содержимое значениями из other. Если *this и other имеют динамический тип std::ios_base::failure, то std::strcmp(what(), other.what()) == 0.(начиная с C++11)

Параметры

message	-	поясняющая строка
ec	-	код ошибки, указывающий конкретную причину сбоя
other	-	другой объект `failure` для копирования

Примечания

Поскольку копирование std::ios_base::failure не должно приводить к выбрасыванию исключений, это сообщение обычно хранится внутри в виде отдельно выделенной строки со счётчиком ссылок. По этой же причине отсутствует конструктор, принимающий std::string&&: содержимое всё равно пришлось бы копировать.

std::ios_base::failure::operator=

failure& operator=( const failure& other );		(до C++11)
failure& operator=( const failure& other ) noexcept;			(начиная с C++11)

Присваивает содержимому значения из other. Если *this и other имеют динамический тип std::ios_base::failure, то после присваивания std::strcmp(what(), other.what()) == 0.(начиная с C++11)

Параметры

other

другой объект исключения, значения которого присваиваются

Возвращаемое значение

*this

std::ios_base::failure::what

virtual const char* what() const throw();		(до C++11)
virtual const char* what() const noexcept;			(начиная с C++11)

Возвращает поясняющую строку.

Возвращаемое значение

Указатель на строку с завершающим нулём, содержащую поясняющую информацию; её представление определяется реализацией. Строка подходит для преобразования и отображения в виде std::wstring. Указатель гарантированно действителен как минимум до уничтожения объекта исключения, из которого он получен, или до вызова неконстантной функции-члена (например, оператора присваивания копированием) для этого объекта исключения.

Во время вычисления константного выражения возвращаемая строка кодируется с использованием обычной кодировки литералов.

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

Примечания

Реализация может переопределить what(), но не обязана этого делать.

Унаследовано от std::system_error

Методы

code	возвращает код ошибки (открытый метод класса `std::system_error`)
what [виртуальная]	возвращает поясняющую строку (виртуальный открытый метод класса `std::system_error`)

Унаследовано от std::runtime_error

Унаследовано от std::exception

Методы

(деструктор) [виртуальная]	уничтожает объект исключения (виртуальный открытый метод класса `std::exception`)
what [виртуальная]	возвращает поясняющую строку (виртуальный открытый метод класса `std::exception`)

Примечания

До принятия решения по вопросу LWG 331 в std::ios_base::failure был объявлен деструктор без throw(), тогда как std::exception::~exception() был объявлен с throw()^[1]. Это означает, что у std::ios_base::failure::~failure() была менее строгая спецификация исключений. В рамках решения это объявление удаляется, чтобы сохранить спецификацию, запрещающую выбрасывание исключений.

Вопрос LWG 363 касается того же дефекта, и в рамках его решения предлагается добавить throw() в объявление std::ios_base::failure::~failure(). Это решение не было применено из-за конфликта между двумя решениями.

Теперь спецификация исключений, запрещающая их выбрасывание, применяется ко всей стандартной библиотеке, поэтому деструкторы классов стандартной библиотеки не объявляются с throw() или noexcept.

Пример

#include <fstream>
#include <iostream>

int main()
{
    std::ifstream f("doesn't exist");
    
    try
    {
        f.exceptions(f.failbit);
    }
    catch (const std::ios_base::failure& e)
    {
        std::cout << "Caught an ios_base::failure.\n"
                  << "Explanatory string: " << e.what() << '\n'
                  << "Error code: " << e.code() << '\n';
    }
}

Возможный вывод:

Caught an ios_base::failure.
Explanatory string: ios_base::clear: unspecified iostream_category error
Error code: iostream:1

Отчёты об ошибках

Следующие отчёты об ошибках, изменяющие поведение, были ретроактивно применены к ранее опубликованным стандартам C++.

DR	Применён к	Поведение согласно опубликованной версии	Корректное поведение
LWG 48	C++98	перегрузка конструктора (1) инициализировала базовый класс `std::exception` значением `msg`, но у базового класса нет соответствующего конструктора	соответствующее описание удалено
LWG 331	C++98	`std::ios_base::failure` объявлял деструктор без throw()	объявление деструктора удалено

См. также

io_errc

(C++11)

коды ошибок потоков ввода-вывода
(перечисление)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/io/ios_base/failure