W3cubDocs

/C++

C++ named requirements: FormattedInputFunction

Requirements

A FormattedInputFunction is a stream input function that performs the following:

  • Constructs an object of type basic_istream::sentry with automatic storage duration and with the noskipws argument set to false, which performs the following
  • if eofbit or badbit are set on the input stream, sets the failbit as well, and if exceptions on failbit are enabled in this input stream's exception mask ((exceptions() & failbit) != 0), throws ios_base::failure.
  • flushes the tie()'d output stream, if applicable
  • if ios_base::skipws flag is set on this input stream, extracts and discards characters from the input stream until one of the following becomes true:
    • the next available character on the input stream is not a whitespace character, as tested by the std::ctype facet of the locale currently imbued in this input stream. The non-whitespace character is not extracted.
    • the end of the stream is reached, in which case failbit and eofbit are set and if the stream is on for exceptions on one of these bits, ios_base::failure is thrown.
  • Checks the status of the sentry by calling sentry::operator bool(), which is equivalent to basic_ios::good.
  • If the sentry returned false or sentry's constructor threw an exception, no input takes place
  • If the sentry returned true, performs the input as if by calling rdbuf()->sbumpc() or rdbuf()->sgetc().
    • if the end of the stream is reached (the call to rdbuf()->sbumpc() or rdbuf()->sgetc() returns Traits::eof()), sets eofbit. If exceptions on eofbit are enabled in this stream's exception mask ((exceptions() & eofbit) != 0), throws ios_base::failure.
    • if an exception is thrown during input, sets badbit in the input stream. If exceptions on badbit are enabled in this stream's exception mask ((exceptions() & badbit) != 0), the exception is also rethrown.
    • If no exception was thrown, returns *this.
  • In any event, whether terminating by exception or returning, the sentry's destructor is called before leaving this function.

Standard library

The following standard library functions are FormattedInputFunctions.

Defect reports

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

DR Applied to Behavior as published Correct behavior
LWG 160 C++98 the process of determining whether the exception caught
is rethrown mentioned a non-existing function exception()
corrected to exceptions()

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/named_req/FormattedInputFunction