C++ named requirements: UnformattedInputFunction

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Diagnostics library

Memory management library

Metaprogramming library (C++11)

General utilities library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library (C++17)

Concurrency support library (C++11)

Execution control library (C++26)

Technical specifications

Symbols index

External libraries

 

C++ named requirements

Basic DefaultConstructible MoveConstructible (C++11) CopyConstructible CopyAssignable MoveAssignable (C++11) Destructible Type properties ScalarType PODType TriviallyCopyable (C++11) TrivialType (C++11) StandardLayoutType (C++11)   ImplicitLifetimeType Library-wide BooleanTestable EqualityComparable LessThanComparable Swappable ValueSwappable (C++11) NullablePointer (C++11) Hash (C++11) Allocator FunctionObject Callable Predicate BinaryPredicate Compare

Container Container ReversibleContainer AllocatorAwareContainer SequenceContainer ContiguousContainer (C++17) AssociativeContainer UnorderedAssociativeContainer (C++11)   Container element DefaultInsertable (C++11) CopyInsertable (C++11) MoveInsertable (C++11) EmplaceConstructible (C++11) Erasable (C++11) Iterator LegacyIterator LegacyInputIterator LegacyOutputIterator LegacyForwardIterator LegacyBidirectionalIterator LegacyRandomAccessIterator LegacyContiguousIterator (C++17) ConstexprIterator (C++20) Stream I/O FormattedInputFunction UnformattedInputFunction FormattedOutputFunction UnformattedOutputFunction Formatters BasicFormatter (C++20) Formatter (C++20)

Random Numbers SeedSequence (C++11) RandomNumberEngine (C++11) RandomNumberDistribution (C++11) UniformRandomBitGenerator (C++11) RandomNumberEngineAdaptor (C++11) Concurrency BasicLockable (C++11) Lockable (C++11) TimedLockable (C++11) SharedLockable (C++14) SharedTimedLockable (C++14) Mutex (C++11) TimedMutex (C++11) SharedMutex (C++17) SharedTimedMutex (C++14) Ranges RangeAdaptorObject (C++20) RangeAdaptorClosureObject (C++20) Multidimensional View LayoutMapping (C++23) LayoutMappingPolicy (C++23) AccessorPolicy (C++23) Other CharTraits RegexTraits (C++11)   BitmaskType LiteralType (C++11) NumericType UnaryTypeTrait (C++11) BinaryTypeTrait (C++11) TransformationTrait (C++11) Clock (C++11) TrivialClock (C++11)

 

Requirements

An UnformattedInputFunction is a stream input function that performs the following:

1) Constructs an object of type basic_istream::sentry with automatic storage duration and with the noskipws argument set to true, 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.

2) Checks the status of the sentry by calling sentry::operator bool(), which is equivalent to basic_ios::good.

• If the operator returns false or sentry's constructor throws an exception:

• Sets the number of extracted characters (gcount) in the input stream to zero.
• If the function was called to write to an array of CharT, writes CharT() (the null character) to the first location of the array.

• If the operator returns 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.

• Exceptions thrown from basic_ios::clear are not caught or rethrown.

• If no exception was thrown during input, sets the number of extracted characters (gcount) in the input stream.

3) 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 UnformattedInputFunctions.

• std::getline, except that it does not modify gcount.
• basic_istream::operator>>(basic_streambuf*)
• basic_istream::get
• basic_istream::getline
• basic_istream::ignore
• basic_istream::peek
• basic_istream::read
• basic_istream::readsome
• basic_istream::putback, except that it first clears eofbit
• basic_istream::unget, except that it first clears eofbit
• basic_istream::sync, except that it does not modify gcount
• basic_istream::tellg, except that it does not modify gcount
• basic_istream::seekg, except that it first clears eofbit and does not modify gcount
• std::ws, except that it does not modify gcount

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 61	C++98	it was unclear whether throwing an exception because of setting eofbit and/or failbit will result in setting badbit	exceptions thrown from basic_ios::clear are not caught or rethrown
LWG 160	C++98	the process of determining whether the exception caught is rethrown mentioned a non-existing function exception()	corrected to exceptions()
LWG 243	C++98	the behavior when sentry::operator bool() returns false or the sentry object fails to be constructed was not specified	specified