home | help 
std::ios_base::failure(3)      C++ Standard Libary     std::ios_base::failure(3)

NAME
     std::ios_base::failure - std::ios_base::failure

Synopsis
	Defined in header <ios>
	class failure;

	The  class  std::ios_base::failure  defines  an exception object that is
     thrown on
	failure by the functions in the Input/Output library.

	std::ios_base::failure may be defined either as a member class of
	std::ios_base  or  as  a  synonym  (typedef)  for  another  class   with
     (since C++17)
	equivalent functionality.

	std-ios base-failure-2003-inheritance.svg
						  (until C++11)
		   Inheritance diagram
	std-ios base-failure-inheritance.svg
						  (since C++11)
		   Inheritance diagram

Member functions
	constructor   constructs a new failure object with the given message
		      (public member function)
	operator=     replaces the failure object
		      (public member function)
	what	      returns the explanatory string
		      (public member function)

     std::ios_base::failure::failure

	explicit failure( const std::string& message ); 	 (until C++11)
	explicit failure( const std::string& message,
			  const std::error_code& ec =		 (since C++11)
	std::io_errc::stream );
	explicit failure( const char* message,		 (1)
			  const std::error_code& ec =	     (2) (since C++11)
	std::io_errc::stream );
	failure(     const    failure&	  other    );			     (3)
     (until C++11)
	failure(       const	   failure&	  other       )        noexcept;
     (since C++11)

	1,2) Constructs the exception object using message as explanation string
     which can
	later be retrieved using what().
	ec is used to identify the specific reason for the failure.
	(since C++11)
	3) Copy constructor. Initialize the contents with those of other.
	If *this and other both have dynamic type std::ios_base::failure then
	std::strcmp(what(), other.what()) == 0.
	(since C++11)

Parameters
	message - explanatory string
	ec	- error code to identify the specific reason for the failure
	other	- another failure to copy

Notes
	Because  copying std::ios_base::failure is not permitted to throw excep-
     tions, this
	message is typically stored internally as a separately-allocated  refer-
     ence-counted
	string.  This  is also why there is no constructor taking std::string&&:
     it would have
	to copy the content anyway.

     std::ios_base::failure::operator=

	failure& operator=( const failure& other );	      (until C++11)
	failure& operator=( const failure& other ) noexcept;  (since C++11)

	Assigns the contents with those of other.
	If *this and other both have dynamic type std::ios_base::failure then
	std::strcmp(what(), other.what()) == 0 after assignment.
	(since C++11)

Parameters
	other - another exception object to assign with

Return value
	*this

     std::ios_base::failure::what

	virtual const char* what() const throw();   (until C++11)
	virtual const char* what() const noexcept;  (since C++11)

	Returns the explanatory string.

Parameters
	(none)

Return value
	Pointer to a null-terminated string with  explanatory  information.  The
     string is
	suitable  for  conversion  and display as a std::wstring. The pointer is
     guaranteed to
	be valid at least until the exception object from which it  is	obtained
     is destroyed,
	or  until a non-const member function (e.g. copy assignment operator) on
     the
	exception object is called.

Notes
	Implementations are allowed but not required to override what().

     Inherited from std::system_error

Member functions
	code	  returns error code
		  (public member function of std::system_error)
	what	  returns an explanatory string
	[virtual] (virtual public member function of std::system_error)

     Inherited from std::runtime_error

     Inherited from std::exception

Member functions
	destructor   destroys the exception object
	[virtual]    (virtual public member function of std::exception)
	what	     returns an explanatory string
	[virtual]    (virtual public member function of std::exception)

Notes
	Before the resolution of LWG issue 331, std::ios_base::failure	declared
     a destructor
	without  throw(),  where  std::exception::~exception() was declared with
     throw()^[1].
	This means the std::ios_base::failure::~failure() had a weaker exception
	specification. The resolution is to remove that declaration so that  the
     non-throwing
	exception specification is kept.

	LWG  issue  363  targets  the  same  defect and its resolution is to add
     throw() to the
	declaraion of std::ios_base::failure::~failure().  That  resolution  was
     not applied
	due to the confict between the two resolutions.

	 1.  a	The non-throwing exception specification is now applied globally
     across the
	    standard library, so the destructors of standard library classes are
     not
	    declared with throw() or noexcept.

Example
     // Run this code

      #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';
	  }
      }

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

	Defect reports

	The following behavior-changing defect	reports  were  applied	retroac-
     tively to
	previously published C++ standards.

	  DR	Applied to	     Behavior as published		 Correct
     behavior
			   the constructor overload (1) initialized
	LWG  48   C++98       the  base class std::exception		  corre-
     sponding
			   with msg, but the base class does not  have	descrip-
     tion removed
			   a matching constructor
	LWG  331  C++98       std::ios_base::failure declared a 	 removed
     the destructor
			   destructor without  throw()			declara-
     tion

See also
	io_errc the IO stream error codes
	(C++11) (enum)

http://cppreference.com 	   2024.06.10	       std::ios_base::failure(3)
home | help