Apache C++ Standard Library Reference Guide

## basic_ios

Library: Input/output

    basic_ios  ios_base

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Member Types
- Nonmember Types
- Public Constructor
- Protected Constructor
- Destructor
- Public Member Functions
- See Also
- Standards Conformance

### Local Index

#### Members

bad() basic_ios() char_type clear() copyfmt() eof() exceptions() | fail() fill() good() imbue() init() int_type narrow() | off_type operator!() pos_type rdbuf() rdstate() setstate() tie() | traits_type void*() widen() ~basic_ios()

#### Non-Members

ios | wios |

### Summary

A base class that includes the common character-dependent functionality and state required by all streams

### Synopsis

    #include <ios>

    namespace std {
      template<class charT, class traits = char_traits<charT> >
      class basic_ios;
    }

### Description

The class basic_ios is a base class that includes the common character-dependent functionality and data members required by all streams. It maintains state information that reflects the integrity of the stream and stream buffer. It also maintains the link between the stream classes and the stream buffer classes via the `rdbuf()` member functions. Classes derived from basic_ios specialize operations for input and output.

### Interface

    namespace std {
      template<class charT, class traits = char_traits<charT> >
      class basic_ios : public ios_base
      {
         public:

          typedef typename traits::char_type       char_type;
          typedef traits                           traits_type;
          typedef typename traits::int_type        int_type;
          typedef typename traits::off_type        off_type;
          typedef typename traits::pos_type        pos_type;

          operator void*() const;
          bool operator!() const;

          iostate rdstate() const;
          void clear(iostate = goodbit);
          void setstate(iostate state);
          bool good() const;
          bool eof() const;
          bool fail() const;
          bool bad() const;

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

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

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

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

          basic_ios& copyfmt(const basic_ios&);

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

          locale imbue(const locale&);

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

         protected:

          basic_ios();                                  // undefined
          void init(basic_streambuf<charT, traits>*);   // undefined
    };

### Member Types

    char_type

The type `char_type` is a synonym for type `traits::char_type`.

    int_type

The type`int_type` is a synonym of type `traits::in_type`.

    off_type

The type `off_type` is a synonym of type `traits::off_type`.

    pos_type

The type `pos_type` is a synonym of type `traits::pos_type`.

    traits_type

The type `traits_type` is a synonym for the template parameter `traits`.

### Nonmember Types

    ios

The type `ios` is a specialization of basic_ios on `char`:

`typedef basic_ios<char> ios;`

    wios

The type `wios` is a specialization of basic_ios on `wchar_t`:

`typedef basic_ios<wchar_t> wios;`

### Public Constructor

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

Constructs an object of class basic_ios, assigning initial values to its member objects by calling `init(sb)`. If `sb` is a null pointer, the stream is placed in error state by setting its `badbit`.

### Protected Constructor

    basic_ios();

Constructs an object of class basic_ios, leaving its member objects uninitialized. The object must be initialized by calling the `init` member function before using it.

### Destructor

    virtual ~basic_ios();

Destroys an object of class basic_ios.

### Public Member Functions

    bool
    bad() const;

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

    void
    clear(iostate state = goodbit);

If `(state & exceptions()) == 0`, returns. Otherwise, the function throws an object of class ios_base::failure. After the call, returns `state == rdstate()` if `rdbuf() !=0`; otherwise, `rdstate() == state|ios_base::badbit.`

    basic_ios&
    copyfmt(const basic_ios& rhs);

Assigns to the member objects of `*this` the corresponding member objects of `rhs`, except that:

- `rdstate()` and `rdbuf()` are left unchanged

- `exceptions()` is altered last by calling `exceptions(rhs.exceptions())`

Before copying any parts of `rhs`, calls each registered callback pair `(fn, index)` as `(*fn)(erase_event,*this, index)`. After all parts but `exceptions()` are replaced, calls each callback pair that was copied from `rhs` as `(*fn)(copy_event,*this, index)`.

#### Table 40: `copyfmt()` Postconditions

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()`

    bool
    eof() const;

Returns `true` if `eofbit` 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);

Sets the exception mask to `except`, then calls `clear(rdstate())`.

    bool
    fail() const;

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

    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);

Replaces the stream's fill character by `fillch` and returns its previous value.

    bool
    good() const;

Returns `rdstate() == goodbit`.

    locale
    imbue(const locale& loc);

Calls `ios_base::imbue (loc)`. If `rdbuf() != 0`, calls
`rdbuf()->pubimbue(loc)` and returns the previously saved value.

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

Performs initialization according to the following table:

#### Table 41: `init()` Postconditions

Element | Value
`rdbuf()` | `sb`
`tie()` | `0`
`rdstate()` | `sb ? goodbit : badbit`
`exceptions()` | `goodbit`
`flags()` | `skipws | dec`
`width()` | `0`
`precision()` | `6`
`fill()` | `widen(' ')`
`getloc()` | `locale::global()`

    char
    narrow(charT c, char dfault) const;

Returns:

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

    bool
    operator!() const;

Returns `fail()`.

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

Returns a pointer to the stream buffer associated with the stream.

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

Associates a stream buffer with the stream. All the input and output is directed to this stream buffer. If `sb` is a null pointer, the stream is placed in error state by setting `badbit`.

    iostate
    rdstate() const;

Returns the control state of the stream.

    void
    setstate(iostate state);

Calls `clear(rdstate() | state)`.

    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);

Saves the `tie()` value, then replaces it by `tiestr` and returns the value previously saved.

    operator
    void*() const;

Returns:

`fail() ? (void*)0 : (void*)1;`

    charT
    widen(char c) const;

Uses `use_facet< ctype<char_type> >(getloc()).widen(c)` to convert a narrow character to a wide character.

### See Also

ios_base, basic_istream, basic_ostream, basic_streambuf, char_traits

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 27.4.4