30 Input/output library [input.output]

30.5 Iostreams base classes [iostreams.base]

30.5.5 Class template basic_ios [ios]

30.5.5.1 Overview [ios.overview]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_ios : public ios_base {
  public:
    using char_type   = charT;
    using int_type    = typename traits::int_type;
    using pos_type    = typename traits::pos_type;
    using off_type    = typename traits::off_type;
    using traits_type = traits;

    // [iostate.flags], flags functions
    explicit operator bool() const;
    bool operator!() const;
    iostate rdstate() const;
    void clear(iostate state = goodbit);
    void setstate(iostate state);
    bool good() const;
    bool eof()  const;
    bool fail() const;
    bool bad()  const;

    iostate exceptions() const;
    void exceptions(iostate except);

    // [basic.ios.cons], constructor/destructor
    explicit basic_ios(basic_streambuf<charT, traits>* sb);
    virtual ~basic_ios();

    // [basic.ios.members], members
    basic_ostream<charT, traits>* tie() const;
    basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);

    basic_streambuf<charT, traits>* rdbuf() const;
    basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);

    basic_ios& copyfmt(const basic_ios& rhs);

    char_type fill() const;
    char_type fill(char_type ch);

    locale imbue(const locale& loc);

    char      narrow(char_type c, char dfault) const;
    char_type widen(char c) const;

    basic_ios(const basic_ios&) = delete;
    basic_ios& operator=(const basic_ios&) = delete;

  protected:
    basic_ios();
    void init(basic_streambuf<charT, traits>* sb);
    void move(basic_ios& rhs);
    void move(basic_ios&& rhs);
    void swap(basic_ios& rhs) noexcept;
    void set_rdbuf(basic_streambuf<charT, traits>* sb);

  };
}

30.5.5.2 basic_ios constructors [basic.ios.cons]

explicit basic_ios(basic_streambuf<charT, traits>* sb);

Effects: Constructs an object of class basic_ios, assigning initial values to its member objects by calling init(sb).

basic_ios();

Effects: Constructs an object of class basic_ios ([ios.base.cons]) leaving its member objects uninitialized.

The object shall be initialized by calling basic_ios::init before its first use or before it is destroyed, whichever comes first; otherwise the behavior is undefined.

~basic_ios();

Remarks: The destructor does not destroy rdbuf().

void init(basic_streambuf<charT, traits>* sb);

Postconditions: The postconditions of this function are indicated in Table 108 .

Table 108 — basic_ios::init() effects

Element	Value
rdbuf()	sb
tie()	0
rdstate()	goodbit if sb is not a null pointer, otherwise badbit.
exceptions()	goodbit
flags()	skipws \| dec
width()	0
precision()	6
fill()	widen(' ')
getloc()	a copy of the value returned by locale()
iarray	a null pointer
parray	a null pointer

30.5.5.3 Member functions [basic.ios.members]

basic_ostream<charT, traits>* tie() const;

Returns: An output sequence that is tied to (synchronized with) the sequence controlled by the stream buffer.

basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);

Requires: If tiestr is not null, tiestr must not be reachable by traversing the linked list of tied stream objects starting from tiestr->tie().

Postconditions: tiestr == tie().

Returns: The previous value of tie().

basic_streambuf<charT, traits>* rdbuf() const;

Returns: A pointer to the streambuf associated with the stream.

basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);

Postconditions: sb == rdbuf().

Effects: Calls clear().

Returns: The previous value of rdbuf().

locale imbue(const locale& loc);

Effects: Calls ios_base::imbue(loc) ([ios.base.locales]) and if rdbuf() != 0 then rdbuf()->pubimbue(loc) ([streambuf.locales]).

Returns: The prior value of ios_base::imbue().

char narrow(char_type c, char dfault) const;

Returns: use_facet<ctype<char_type>>(getloc()).narrow(c, dfault)

char_type widen(char c) const;

Returns: use_facet<ctype<char_type>>(getloc()).widen(c)

char_type fill() const;

Returns: The character used to pad (fill) an output conversion to the specified field width.

char_type fill(char_type fillch);

Postconditions: traits::eq(fillch, fill()).

Returns: The previous value of fill().

basic_ios& copyfmt(const basic_ios& rhs);

Effects: If (this == &rhs) does nothing.

Otherwise assigns to the member objects of *this the corresponding member objects of rhs as follows:

1.
calls each registered callback pair (fn, index) as (*fn)(erase_event, *this, index);
2.
assigns to the member objects of *this the corresponding member objects of rhs, except that
- (16.2.1)
  rdstate(), rdbuf(), and exceptions() are left unchanged;
- (16.2.2)
  the contents of arrays pointed at by pword and iword are copied, not the pointers themselves;296 and
- (16.2.3)
  if any newly stored pointer values in *this point at objects stored outside the object rhs and those objects are destroyed when rhs is destroyed, the newly stored pointer values are altered to point at newly constructed copies of the objects;
3.
calls each callback pair that was copied from rhs as (*fn)(copyfmt_event, *this, index);
4.
calls exceptions(rhs.exceptions()).

[ Note

The second pass through the callback pairs permits a copied pword value to be zeroed, or to have its referent deep copied or reference counted, or to have other special action taken.

— end note

]

Postconditions: The postconditions of this function are indicated in Table 109 .

Table 109 — basic_ios::copyfmt() effects

Element	Value
rdbuf()	unchanged
tie()	rhs.tie()
rdstate()	unchanged
exceptions()	rhs.exceptions()
flags()	rhs.flags()
width()	rhs.width()
precision()	rhs.precision()
fill()	rhs.fill()
getloc()	rhs.getloc()

Returns: *this.

void move(basic_ios& rhs);
void move(basic_ios&& rhs);

Postconditions: *this shall have the state that rhs had before the function call, except that rdbuf() shall return 0.

rhs shall be in a valid but unspecified state, except that rhs.rdbuf() shall return the same value as it returned before the function call, and rhs.tie() shall return 0.

void swap(basic_ios& rhs) noexcept;

Effects: The states of *this and rhs shall be exchanged, except that rdbuf() shall return the same value as it returned before the function call, and rhs.rdbuf() shall return the same value as it returned before the function call.

void set_rdbuf(basic_streambuf<charT, traits>* sb);

Requires: sb != nullptr.

Effects: Associates the basic_streambuf object pointed to by sb with this stream without calling clear().

Postconditions: rdbuf() == sb.

Throws: Nothing.

296)

This suggests an infinite amount of copying, but the implementation can keep track of the maximum element of the arrays that is nonzero.

30.5.5.4 basic_ios flags functions [iostate.flags]

explicit operator bool() const;

Returns: !fail().

bool operator!() const;

Returns: fail().

iostate rdstate() const;

Returns: The error state of the stream buffer.

void clear(iostate state = goodbit);

Postconditions: If rdbuf() != 0 then state == rdstate(); otherwise rdstate() == (state | ios_base::badbit).

Effects: If ((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0, returns.

Otherwise, the function throws an object of class basic_ios::failure ([ios::failure]), constructed with implementation-defined argument values.

void setstate(iostate state);

Effects: Calls clear(rdstate() | state) (which may throw basic_ios::failure ([ios::failure])).

bool good() const;

Returns: rdstate() == 0

bool eof() const;

Returns: true if eofbit is set in rdstate().

bool fail() const;

Returns: true if failbit or badbit is set in rdstate().297

bool bad() const;

Returns: true if badbit is set in rdstate().

iostate exceptions() const;

Returns: A mask that determines what elements set in rdstate() cause exceptions to be thrown.

void exceptions(iostate except);

Postconditions: except == exceptions().

Effects: Calls clear(rdstate()).

297)

Checking badbit also for fail() is historical practice.