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

NAME
     std::basic_istream::sentry - std::basic_istream::sentry

Synopsis
	class sentry;

	An  object  of class basic_istream::sentry is constructed in local scope
     at the
	beginning of each member function of  std::basic_istream  that	performs
     input (both
	formatted  and	unformatted). Its constructor prepares the input stream:
     checks if the
	stream is already in a failed state, flushes the tie()'d output streams,
     skips
	leading whitespace unless noskipws flag is set, and performs other
	implementation-defined tasks if necessary. All cleanup, if necessary, is
     performed
	in the destructor, so that it is guaranteed to happen if exceptions  are
     thrown
	during input.

Member types
	traits_type Traits

Member functions
	constructor    constructs  the	sentry object. All the preparation tasks
     are done here
		      (public member function)
		      finalizes the stream object after formatted input or after
     exception,
	destructor    if necessary
		      (public member function)
	operator=     not copy assignable
	[deleted]     (public member function)
	operator bool checks if the preparation of the stream  object  was  suc-
     cessful
		      (public member function)

     std::basic_istream::sentry::sentry

	explicit  sentry( std::basic_istream<CharT, Traits>& is, bool noskipws =
     false );

	Prepares the stream for formatted input.

	If is.good() is false, calls is.setstate(std::ios_base::failbit) and re-
     turns.
	Otherwise, if is.tie() is not a null pointer, calls is.tie()->flush() to
     synchronize
	the output sequence with external streams. This call can  be  suppressed
     if the put
	area  of  is.tie()  is	empty.	The implementation may defer the call to
     flush() until a
	call of is.rdbuf()->underflow() occurs. If no such  call  occurs  before
     the sentry
	object is destroyed, it may be eliminated entirely.

	If  noskipws  is zero and is.flags() & std::ios_base::skipws is nonzero,
     the function
	extracts and discards all whitespace characters until the next available
     character
	is not a whitespace character (as determined by the currently imbued lo-
     cale in is).
	If is.rdbuf()->sbumpc() or  is.rdbuf()->sgetc()  returns  traits::eof(),
     the function
	calls  setstate(std::ios_base::failbit	|  std::ios_base::eofbit) (which
     may throw
	std::ios_base::failure).

	Additional implementation-defined preparation may take place, which  may
     call
	setstate(std::ios_base::failbit)  (which  may throw std::ios_base::fail-
     ure).

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

Parameters
	is	 - input stream to prepare
	noskipws - true if whitespace should not be skipped

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

     std::basic_istream::sentry::~sentry

	~sentry();

	Does nothing.

     std::basic_istream::sentry::operator bool

	explicit operator bool() const;

	Checks whether the preparation of the input stream was successful.

Parameters
	(none)

Return value
	true  if  the  initialization  of the input stream was successful, false
     otherwise.

Example
     // Run this code

      #include <iostream>
      #include <sstream>

      struct Foo
      {
	  char n[5];
      };

      std::istream& operator>>(std::istream& is, Foo& f)
      {
	  std::istream::sentry s(is);
	  if (s)
	      is.read(f.n, 5);
	  return is;
      }

      int main()
      {
	  std::string input = "   abcde";
	  std::istringstream stream(input);
	  Foo f;
	  stream >> f;
	  std::cout.write(f.n, 5);
	  std::cout << '\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 195 C++98	   it was unclear whether the constructor  made clear
			   would set eofbit
	LWG 419 C++98	   the constructor did not set failbit if  sets  failbit
     in this case
			   eofbit has been set

See also
	operator>>		       extracts formatted data
				       (public member function)
	operator>>(std::basic_istream) extracts characters and character arrays
				       (function template)

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