JTC1/SC22/WG21 N1219

Doc no:   J16/99-0043
          WG21 N1219
Date:     22 October 1999
Project:  Programming Language C++
Reply to: Judy Ward    <judith.ward@compaq.com>
          Matt Austern <austern@sgi.com>

               PROPOSED RESOLUTION TO LIBRARY ISSUE 60

I. Statement of the problem

There are four sections in clause 27 whose titles suggest that they
contain formatted input functions, unformatted input functions,
formatted output functions, and unformatted output functions.  Some of
the functions in those sections, but not all, explicitly state that
they match what one would expect from the title.  Unfortunately, in
some cases it is clearly nonsensical for the functions in those
sections to meet the requirements suggested by the title.  It is not
always clear which functions are supposed to meet those requirements
and which are not.  Existing implementations are inconsistent.

This paper attempts to categorize every function in those four
sections.  It proposes wording changes so that every function contains
language that unambiguously specifies whether or not it meets the
requirements suggested by the sections' titles.


II. Categorization of formatted input section (27.6.1.2)

The arithmetic extractors (27.6.1.2.2) are formatted input functions.
Wording to say so is needed.

The following extractors are formatted input functions.  No changes
are needed; the standard already says they're formatted input
functions.
    operator>>(basic_istream&, charT*)
    operator>>(istream&, unsigned char*)
    operator>>(istream&, signed char*)
    operator>>(basic_istream&, charT&)
    operator>>(istream&, unsigned char&)
    operator>>(istream&, signed char&)

The following extractors are not formatted input functions.  Wording
to say so is needed.
    operator>>(basic_istream& (*)(basic_istream&));
    operator>>(basic_istream& (*)(basic_ios&));
    operator>>(basic_istream& (*)(ios_base&));

The following extractor is a formatted input function.  Wording to 
say so is needed.
    operator>>(basic_streambuf*);


III. Categorization of unformatted input section (27.6.1.3)

The following are unformatted input functions.  Wording to say so is
needed.
    get (six versions).  
    getline (two versions).
    ignore.  
    peek.  
    read.  
    readsome 
    putback
    unget

The following behave almost as unformatted input functions, except
that they don't affect gcount().  Wording is needed.
    sync
    tellg
    seekg (two versions)

The following is not an unformatted input function.  Wording is
needed.
    gcount. Wording needed.


IV. Categorization of formatted output section (27.6.2.5)

All the arithmetic inserters (27.6.2.5.2) are formatted output
functions.   Wording to say so is needed.

operator<<(basic_streambuf*), (27.6.2.5.3) is a formatted output
function.  Wording to say so is needed.

All of the character inserters (27.6.2.5.4) are formatted output
functions.  No changes are needed; wording to say so already exists.

The following are not formatted output functions.  Wording to say so
is needed.
    operator<<(basic_ostream& (*)(basic_ostream&))
    operator<<(basic_ios& (*)(basic_ios&))
    operator<<(ios_base& (*)(ios_base&)


V. Categorization of unformatted output section (27.6.2.6)

The following are unformatted output functions.  Wording to say so is
needed.
    put.  
    write.

The following is not an unformatted output function.  Wording to say
so is needed.
    flush.  


VI. Wording.

In 27.6.1.2.2 [lib.istream.formatted.arithmetic], paragraph 1.
Change the beginning of the second sentence from "The conversion
occurs" to "These extractors behave as formatted input functions (as
described in 27.6.1.2.1).  After a sentry object is constructed,
the conversion occurs"

In 27.6.1.2.3, [lib.istream::extractors], before paragraph 1.
Add an effects clause.  "Effects: None.  This extractor does
not behave as a formatted input function (as described in
27.6.1.2.1).

In 27.6.1.2.3, [lib.istream::extractors], paragraph 2.  Change the
effects clause to "Effects: Calls pf(*this).  This extractor does not
behave as a formatted input function (as described in 27.6.1.2.1).

In 27.6.1.2.3, [lib.istream::extractors], paragraph 4.  Change the
effects clause to "Effects: Calls pf(*this).  This extractor does not
behave as a formatted input function (as described in 27.6.1.2.1).

In 27.6.1.2.3, [lib.istream::extractors], paragraph 12.  Change the
first two sentences from "If sb is null, calls setstate(failbit),
which may throw ios_base::failure (27.4.4.3).  Extracts characters
from *this..." to "Behaves as a formatted input function (as described
in 27.6.1.2.1).  If sb is null, calls setstate(failbit), which may
throw ios_base::failure (27.4.4.3).  After a sentry object is
constructed, extracts characters from *this...".

In 27.6.1.3, [lib.istream.unformatted], before paragraph 2.  Add an
effects clause.  "Effects: none. This member function does not behave
as an unformatted input function (as described in 27.6.1.3, paragraph 1)."

In 27.6.1.3, [lib.istream.unformatted], paragraph 3.  Change the
beginning of the first sentence of the effects clause from "Extracts a
character" to "Behaves as an unformatted input function (as described
in 27.6.1.3, paragraph 1).  After constructing a sentry object, extracts a
character"

In 27.6.1.3, [lib.istream.unformatted], paragraph 5.  Change the
beginning of the first sentence of the effects clause from "Extracts a
character" to "Behaves as an unformatted input function (as described
in 27.6.1.3, paragraph 1).  After constructing a sentry object, extracts a
character"

In 27.6.1.3, [lib.istream.unformatted], paragraph 5.  Change the
beginning of the first sentence of the effects clause from "Extracts
characters" to "Behaves as an unformatted input function (as described
in 27.6.1.3, paragraph 1).  After constructing a sentry object, extracts
characters"

[No change needed in paragraph 10, because it refers to paragraph 7.]

In 27.6.1.3, [lib.istream.unformatted], paragraph 12.  Change the
beginning of the first sentence of the effects clause from "Extracts
characters" to "Behaves as an unformatted input function (as described
in 27.6.1.3, paragraph 1).  After constructing a sentry object, extracts
characters"

[No change needed in paragraph 15.]

In 27.6.1.3, [lib.istream.unformatted], paragraph 17.  Change the
beginning of the first sentence of the effects clause from "Extracts
characters" to "Behaves as an unformatted input function (as described
in 27.6.1.3, paragraph 1).  After constructing a sentry object, extracts
characters"

[No change needed in paragraph 23.]

In 27.6.1.3, [lib.istream.unformatted], paragraph 24.  Change the
beginning of the first sentence of the effects clause from "Extracts
characters" to "Behaves as an unformatted input function (as described
in 27.6.1.3, paragraph 1).  After constructing a sentry object, extracts
characters"

In 27.6.1.3, [lib.istream.unformatted], before paragraph 27.  Add an
Effects clause: "Effects: Behaves as an unformatted input function (as
described in 27.6.1.3, paragraph 1).  After constructing a sentry
object, reads but does not extract the current input character."

In 27.6.1.3, [lib.istream.unformatted], paragraph 28.  Change the
first sentence of the Effects clause from "If !good() calls" to
Behaves as an unformatted input function (as described in 27.6.1.3,
paragraph 1).  After constructing a sentry object, if !good() calls"

In 27.6.1.3, [lib.istream.unformatted], paragraph 30.  Change the
first sentence of the Effects clause from "If !good() calls" to
"Behaves as an unformatted input function (as described in 27.6.1.3,
paragraph 1).  After constructing a sentry object, if !good() calls"

In 27.6.1.3, [lib.istream.unformatted], paragraph 32.  Change the
first sentence of the Effects clause from "If !good() calls..." to
"Behaves as an unformatted input function (as described in 27.6.1.3,
paragraph 1).  After constructing a sentry object, if !good()
calls..."  Add a new sentence to the end of the Effects clause:
"[Note: this function extracts no characters, so the value returned
by the next call to gcount() is 0.]"

In 27.6.1.3, [lib.istream.unformatted], paragraph 34.  Change the
first sentence of the Effects clause from "If !good() calls" to
"Behaves as an unformatted input function (as described in 27.6.1.3,
paragraph 1).  After constructing a sentry object, if !good() calls".
Add a new sentence to the end of the Effects clause: "[Note: this
function extracts no characters, so the value returned by the next
call to gcount() is 0.]"

In 27.6.1.3, [lib.istream.unformatted], paragraph 36.  Change the
first sentence of the Effects clause from "If !rdbuf() is" to "Behaves
as an unformatted input function (as described in 27.6.1.3, paragraph
1), except that it does not count the number of characters extracted
and does not affect the value returned by subsequent calls to
gcount().  After constructing a sentry object, if rdbuf() is"

In 27.6.1.3, [lib.istream.unformatted], before paragraph 37.  Add an
Effects clause: "Effects: Behaves as an unformatted input function (as
described in 27.6.1.3, paragraph 1), except that it does not count the
number of characters extracted and does not affect the value returned
by subsequent calls to gcount()."  Change the first sentence of
paragraph 37 from "if fail()" to "after constructing a sentry object,
if fail()".

In 27.6.1.3, [lib.istream.unformatted], paragraph 38.  Change the
first sentence of the Effects clause from "If fail()" to "Behaves
as an unformatted input function (as described in 27.6.1.3, paragraph
1), except that it does not count the number of characters extracted
and does not affect the value returned by subsequent calls to
gcount().  After constructing a sentry object, if fail()

In 27.6.1.3, [lib.istream.unformatted], paragraph 40.  Change the
first sentence of the Effects clause from "If fail()" to "Behaves
as an unformatted input function (as described in 27.6.1.3, paragraph
1), except that it does not count the number of characters extracted
and does not affect the value returned by subsequent calls to
gcount().  After constructing a sentry object, if fail()

In 27.6.2.5.2 [lib.ostream.inserters.arithmetic], paragraph 1.  Change
the beginning of the third sentence from "The formatting conversion"
to "These extractors behave as formatted output functions (as
described in 27.6.2.5.1).  After the sentry object is constructed, the
conversion occurs".

In 27.6.2.5.3 [lib.ostream.inserters], before paragraph 1.  Add an
effects clause: "Effects: None. Does not behave as a formatted output
function (as described in 27.6.2.5.1).".

In 27.6.2.5.3 [lib.ostream.inserters], paragraph 2.  Change the
effects clause to "Effects: calls pf(*this).  This extractor does not
behave as a formatted output function (as described in 27.6.2.5.1).".

In 27.6.2.5.3 [lib.ostream.inserters], paragraph 4.  Change the
effects clause to "Effects: calls pf(*this).  This extractor does not
behave as a formatted output function (as described in 27.6.2.5.1).".

In 27.6.2.5.3 [lib.ostream.inserters], paragraph 6.  Change the first
sentence from "If sb" to "Behaves as a formatted output function (as
described in 27.6.2.5.1).  After the sentry object is constructed, if
sb".

In 27.6.2.6 [lib.ostream.unformatted], paragraph 2.  Change the first
sentence from "Inserts the character" to "Behaves as an unformatted
output function (as described in 27.6.2.6, paragraph 1).  After
constructing a sentry object, inserts the character".

In 27.6.2.6 [lib.ostream.unformatted], paragraph 5.  Change the first
sentence from "Obtains characters" to "Behaves as an unformatted
output function (as described in 27.6.2.6, paragraph 1).  After
constructing a sentry object, obtains characters".

In 27.6.2.6 [lib.ostream.unformatted], paragraph 7.  Add a new
sentence at the end of the paragraph: "Does not behave as an
unformatted output function (as described in 27.6.2.6, paragraph 1)."