home | help 
std::basic_ostream::sentry(3)  C++ Standard Libary std::basic_ostream::sentry(3)

NAME
     std::basic_ostream::sentry - std::basic_ostream::sentry

Synopsis
	class sentry;

	An  object  of class basic_ostream::sentry is constructed in local scope
     at the
	beginning of each member function of  std::basic_ostream  that	performs
     output (both
	formatted  and unformatted). Its constructor prepares the output stream:
     checks if
	the stream is already in a failed  state,  flushes  the  tie()'d  output
     streams, and
	performs  other  implementation-defined  tasks if necessary. Implementa-
     tion-defined
	cleanup, as well as flushing of the output stream if necessary, is  per-
     formed in the
	destructor,  so that it is guaranteed to happen if exceptions are thrown
     during
	output.

Member functions
	constructor   constructs the sentry object. All  the  preparation  tasks
     are done here
		      (public member function)
		      finalizes  the stream object after formatted output or af-
     ter exception,
	destructor    if necessary
		      (public member function)
	operator=     the assignment operator is deleted
		      (public member function)
	operator bool checks if the preparation of the stream  object  was  suc-
     cessful
		      (public member function)

     std::basic_ostream::sentry::sentry

	explicit sentry( std::basic_ostream<CharT, Traits>& os );

	Prepares the stream for formatted output.

	If  os.good()  is  false,  returns. Otherwise, if os.tie() is not a null
     pointer, calls
	os.tie()->flush() to  synchronize  the	output	sequence  with	external
     streams. During
	preparation, the constructor may call setstate(failbit) (which may throw
	std::ios_base::failure).

	If  after  preparation	is completed, os.good() == true, then any subse-
     quent calls to
	operator bool will return true.

Parameters
	os - output stream to prepare

Exceptions
	std::ios_base::failure if the end of file condition occurs.

     std::basic_ostream::sentry::~sentry

	~sentry();

	If (os.flags() & std::ios_base::unitbuf)  &&  !std::uncaught_exception()
     && os.good())
	is  true, calls os.rdbuf()->pubsync(). If that function returns -1, sets
     badbit in
	os.rdstate() without propagating an exception.

     std::basic_ostream::sentry::operator bool

	explicit operator bool() const;

	Checks whether the preparation of the output stream was successful.

Parameters
	(none)

Return value
	true if the preparation of the output stream was successful, false  oth-
     erwise.

Example
     // Run this code

      #include <iostream>
      #include <sstream>

      struct Foo
      {
	  char n[6];
      };

      std::ostream& operator<<(std::ostream& os, Foo& f)
      {
	  std::ostream::sentry s(os);
	  if (s)
	      os.write(f.n, 5);
	  return os;
      }

      int main()
      {
	  Foo f = {"abcde"};
	  std::cout << f << '\n';
      }

Output:
      abcde

	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
	LWG 397 C++98	   the destructor might call os.flush(), which	the  ex-
     ception is not
			   may	throw  exceptions			  propa-
     gated
	LWG 442 C++98	   operator bool was not declared  const  (it  is  added
     const
			   const in the synopsis)
			   if os sets unitbuf, the destructor would
			   call os.flush(), which		       calls
	LWG  835  C++98       is an UnformattedOutputFunction and creates os.rd-
     buf()->pubsync()
			   another sentry object			in  this
     case instead
			   (whose destructor then creates another
			   sentry object and so on)

See also
	operator<< inserts formatted data
		   (public member function)

http://cppreference.com 	   2024.06.10	   std::basic_ostream::sentry(3)
home | help