Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/named req/UnformattedInputFunction"

From cppreference.com
< cpp‎ | named req
m (T. Canens moved page cpp/concept/UnformattedInputFunction to cpp/named req/UnformattedInputFunction without leaving a redirect: Text replace - "cpp/concept" to "cpp/named req")
(Added LWG issue #243 DR.)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{cpp/concept/title|UnformattedInputFunction}}
+
{{cpp/named req/title|UnformattedInputFunction}}
−
{{cpp/concept/navbar}}
+
{{cpp/named req/navbar}}
  
 
===Requirements===
 
===Requirements===
 +
An {{named req/core|UnformattedInputFunction}} is a stream input function that performs the following:
  
−
An {{tt|UnformattedInputFunction}} is a stream input function that performs the following:
+
@1@ Constructs an object of type {{l2tt|cpp/io/basic_istream/sentry}} with automatic storage duration and with the {{tt|noskipws}} argument set to {{c|true}}, which performs the following:
−
 
+
* If {{ltt|cpp/io/ios_base/iostate|eofbit}} or {{ltt|cpp/io/ios_base/iostate|badbit}} are set on the input stream, sets the {{ltt|cpp/io/ios_base/iostate|failbit}} as well, and if exceptions on {{tt|failbit}} are enabled in this input stream's [[cpp/io/basic_ios/exceptions|exception mask]] ({{c|1=(exceptions() & failbit) != 0}}), throws {{l2tt|cpp/io/ios_base/failure}}.
−
* Constructs an object of type {{l2tt|cpp/io/basic_istream/sentry}} with automatic storage duration and with the {{tt|noskipws}} argument set to {{c|true}}, which performs the following
+
* Flushes the tie()'d output stream, if applicable.
−
:* if {{ltt|cpp/io/ios_base/iostate|eofbit}} or {{ltt|cpp/io/ios_base/iostate|badbit}} are set on the input stream, sets the {{tt|failbit}} as well, and if exceptions on failbit are enabled in this input stream's exception mask, throws {{l2tt|cpp/io/ios_base/failure}}.
+
@2@ Checks the status of the sentry by calling {{tt|sentry::operator bool()}}, which is equivalent to {{l2tt|cpp/io/basic_ios/good}}.
−
:* flushes the tie()'d output stream, if applicable
+
* If the operator returns {{c|false}} or sentry's constructor throws an exception:
−
* Checks the status of the sentry by calling {{tt|sentry::operator bool()}}, which is equivalent to {{l2tt|cpp/io/basic_ios/good}}.
+
:* Sets the number of extracted characters (gcount) in the input stream to zero.
−
* If the sentry returned {{c|false}} or sentry's constructor threw an exception:
+
:* If the function was called to write to an array of {{tt|CharT}}, writes {{tt|CharT()}} (the null character) to the first location of the array.
−
:* sets the number of extracted characters (gcount) in the input stream to zero
+
* If the operator returns {{c|true}}, performs the input as if by calling {{c|rdbuf()->sbumpc()}} or {{c|rdbuf()->sgetc()}}.
−
:* if the function was called to write to an array of {{tt|CharT}}, writes {{tt|CharT()}} (the null character) to the first location of the array
+
:* If the end of the stream is reached (the call to {{c|rdbuf()->sbumpc()}} or {{c|rdbuf()->sgetc()}} returns {{c|Traits::eof()}}), sets {{tt|eofbit}}. If exceptions on {{tt|eofbit}} are enabled in this stream's [[cpp/io/basic_ios/exceptions|exception mask]] ({{c|1=(exceptions() & eofbit) != 0}}), throws {{l2tt|cpp/io/ios_base/failure}}.
−
* If the sentry returned {{c|true}}, performs the input as if by calling {{c|rdbuf()->sbumpc()}} or {{c|rdbuf()->sgetc()}}.
+
:* If an exception is thrown during input, sets {{tt|badbit}} in the input stream. If exceptions on {{tt|badbit}} are enabled in this stream's [[cpp/io/basic_ios/exceptions|exception mask]] ({{c|1=(exceptions() & badbit) != 0}}), the exception is also rethrown.
−
:* if the end of the stream is reached (the call to {{c|rdbuf()->sbumpc()}} or {{c|rdbuf()->sgetc()}} returns {{c|Traits::eof()}}, sets {{tt|eofbit}}. If exceptions on eofbit are enabled in this stream's exception mask, throws {{l2tt|cpp/io/ios_base/failure}}.
+
::* Exceptions thrown from {{l2tt|cpp/io/basic_ios/clear}} are not caught or rethrown.
−
:* if an exception is thrown during input, sets {{tt|badbit}} in the input stream. If exceptions on badbit are enabled in this stream's exception mask, the exception is also rethrown.
+
 
:* If no exception was thrown during input, sets the number of extracted characters (gcount) in the input stream.
 
:* If no exception was thrown during input, sets the number of extracted characters (gcount) in the input stream.
−
* In any event, whether terminating by exception or returning, the sentry's destructor is called before leaving this function.
+
@3@ In any event, whether terminating by exception or returning, the sentry's destructor is called before leaving this function.
  
 
===Standard library===
 
===Standard library===
−
 
+
The following standard library functions are {{named req|UnformattedInputFunction}}s.
−
The following standard library functions are {{concept|UnformattedInputFunction}}s.
+
  
 
* {{lc|std::getline}}, except that it does not modify gcount.
 
* {{lc|std::getline}}, except that it does not modify gcount.
Line 38: Line 37:
 
* {{lc|std::ws}}, except that it does not modify gcount
 
* {{lc|std::ws}}, except that it does not modify gcount
  
−
[[de:cpp/concept/UnformattedInputFunction]]
+
===Defect reports===
−
[[es:cpp/concept/UnformattedInputFunction]]
+
{{dr list begin}}
−
[[fr:cpp/concept/UnformattedInputFunction]]
+
{{dr list item|wg=lwg|dr=61|std=C++98|before=it was unclear whether throwing an exception because of<br>setting {{tt|eofbit}} and/or {{tt|failbit}} will result in setting {{tt|badbit}}|after=exceptions thrown from {{l2tt|cpp/io/basic_ios/clear}}<br>are not caught or rethrown}}
−
[[it:cpp/concept/UnformattedInputFunction]]
+
{{dr list item|wg=lwg|dr=160|std=C++98|before=the process of determining whether the exception caught<br>is rethrown mentioned a non-existing function {{tt|exception()}}|after=corrected to {{ltt|cpp/io/basic_ios/exceptions|exceptions()}}}}
−
[[ja:cpp/concept/UnformattedInputFunction]]
+
{{dr list item|wg=lwg|dr=243|std=C++98|before=the behavior when {{tt|sentry::operator bool()}} returns {{c|false}}<br>or the sentry object fails to be constructed was not specified|after=specified}}
−
[[pt:cpp/concept/UnformattedInputFunction]]
+
{{dr list end}}
−
[[ru:cpp/concept/UnformattedInputFunction]]
+
 
−
[[zh:cpp/concept/UnformattedInputFunction]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 23:21, 17 October 2022

 
C++
 
C++ named requirements
 

[edit] 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.
  • 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.

[edit] Standard library

The following standard library functions are UnformattedInputFunctions.

[edit] 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
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/named_req/UnformattedInputFunction&oldid=144416"