no copyright!basic_ios.3

The template class basic_ios

Synopsis

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

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

    operator void*() 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 state);

    basic_ostream<cT, traits>* tie() const;
    basic_ostream<cT, traits>* tie(basic_ostream<cT, traits>* other);
    basic_streambuf<cT, traits>* rdbuf() const;
    basic_streambuf<cT, traits>* rdbuf(basic_streambuf<cT, traits>* sb);
    basic_ios<cT, traits>& copyfmt(basic_ios<cT, traits> const& other);
    char_type fill() const;
    char_type fill(char_type c);

    locale    imbue(locale const& loc);
    char      narrow(char_type c, char dfault) const;
    char_type widen(char c) const;

  protected:
    basic_ios();
    void init(basic_streambuf<cT, traits>* sb);
  };

  typedef basic_ios<char>    ios;
  typedef basic_ios<wchar_t> wios;
}
    

Description

The template class basic_ios provides all functionality used both by input and output streams. In addition to the formatting flags maintained by the base class ios_base this is mainly the stream state and the stream buffer used. The template class basic_ios is a virtual base class of the two template classes basic_istream and basic_ostream.

Stream State and Exceptions

The template class basic_ios maintains the stream's state in terms of state flags which indicate whether previous stream operations were successful. A user can explicitly request that on certain state changes, an exception is thrown. By default, all exceptions are caught, resulting in setting of the flag ios_base::badbit.

The current state of the stream can be accessed with several functions:

Expression Semantics
if (stream) The conversion operator to void* returns a non-null pointer if and only if neither ios_base::failbit nor ios_base::badbit is set. Of course, this conversion is also applied in other contexts than the if-statement where a Boolean value is needed.
!stream The negation operator returns true if the stream encountered some error, that is if ios_base::failbit or ios_base::badbit is set.
stream.bad() The function bad() returns true if the ios_base::badbit is set for the stream.
stream.eof() The function eof() returns true if the ios_base::eofbit is set for the stream.
stream.fail() The function fail() returns true if either the ios_base::failbit or the ios_base::badbit is set for the stream.
stream.good() The function good() returns true if no error flag is set, that is if the state is ios_base::goodbit.
stream.rdstate() The function rdstate() returns all state flags at once bitwise or-ing the flags to form a single value of the bitmask type ios_base::iostate.
stream.clear(state) The function clear() sets the stream state to be state except when there is no stream buffer, in which case the flag ios_base::badbit remains set even if it is not set in state. Calling this function might trigger an exception (see below)
stream.clear() This call actually calls the same function as the previous expression but it makes use of the default argument ios_base::goodbit.
stream.setstate(flags) The function setstate() adds the flags set in flags to the current state of the stream. This might also result in calling of an exception (see below).

Using the function exception() it is possible to set up an exception mask which specifies when exceptions are thrown as the result of setting the stream's state: Whenever the stream state is set, an exception is thrown is, if at least one state bit is set in the new state which was also set in the last call to exception(). Note, that an exception is also thrown, if the stream state is set but the state does not really change. This is even the case, if a state flag is cleared or a flag is set, which is not set in the exception mask, as long as one of the state flags in the new state is also set in the exception mask.

Tied basic_ostreams

In some situations it is useful if two streams cooperate closely to make sure that output appears in the correct order. For example, it is useful to make sure that a message about expected input is written before an input stream waits for user input. To aid the programmer in doing things like this, a basic_ostream can be tied to a basic_ios object. The tied basic_ostream is then automatically flushed prior to input operations. This feature is used e.g. by cin and cout to ascertian that all output written to cout is written to the screen (or wherever cout actually writes to) before it is attempted to read from cin. Of course, this is only guaranteed to work with input operations defined by the C++ Standard Library. However, if the guidelines for user defined input operators are followed, this also works for user defined input operators.

Stream Buffers

The template class basic_ios maintains a pointer to a stream buffer which is used by the derived stream classes to read or write characters. Normally, this pointer is set up during construction and remains unchanged. The pointer to the stream buffer is then read by the stream classes whenever they need to access the stream buffer. A new stream buffer can be installed using the method rdbuf().

The class basic_ios only maintains the stream buffer except that the method imbue() also calls imbue() on the stream buffer if it is non-null. If you only want to change the locale for the stream object but not for the stream buffer you can use ios_base::imbue() instead.

std::basic_ios Members

basic_ios<cT, traits>::basic_ios()

Effect
This constructor constructs the object but does not initialize any of the values! Before the object can be used, it is necessary to call the member function init() which initializes all values. The function init() should be called in the constructor of the derived class which invoked this constructor.
Post Condition
There is no post condition guaranteed by this function! Before you can do anything with this object, you have to call init().

basic_ios<cT, traits>::basic_ios(basic_streambuf<cT, traits>* sb)

Effect
The object is constructed and then initial values are assigned to the members by calling init(sb).
Post Condition
All members are set up according to the specification of init().

basic_ios<cT, traits>::init(basic_streambuf<cT, traits>* sb)

Effect
The function init() does the actual initialization of the basic_ios objects. The initialization code is factored out into a function because it is the same for several constructors. The the Post Conditions section for the actual values set up.
Post Condition
After calling this function as stream.init(sb), the class is set up according to the following table:

Expression Value
stream.rdbuf() sb
stream.tie() 0
stream.rdstate() ios_base::goodbit if sb != 0, ios_base::badbit otherwise
stream.exceptions() ios_base::goodbit
stream.flags() ios_base::skipws | ios_base::dec
stream.width() 0
stream.precision() 6
stream.fill() stream.widen(' ')
stream.getloc() A copy of locale()

basic_ios<cT, traits>::~basic_ios()

Effect
The destructor only calls the base class destructor but does nothing else. In particular, it does not delete the stream buffer.

basic_ios<cT, traits>::operator void*() const

Effect
Using this conversion operator stream objects can be used in contexts where a Boolean value is necessary: This operator returns a non-null pointer only fail() returns false.
Return
This operator returns a null pointer if fail() returns true. Otherwise, a non-null pointer is returned.

basic_ios<cT, traits>::operator !() const

Effect
This operator can be used to have a short notation for a test on whether there was a failure for this stream.
Return
This operator returns fail().

basic_ios<cT, traits>::rdstate() const

Effect
This function is used to read the complete stream state at once, that is, all error flags.
Return
rdstate() returns all error flags currently set.

basic_ios<cT, traits>::clear(ios_base::iostate state)

Effect
This function sets the stream state to the flags passed in state, unless no stream buffer is installed, in which case ios_base::badbit is set in addition to the flags in state (of course, if ios_base::badbit is already set in state this makes no difference). It is called "clear" because when called with no arguments, state defaults to ios_base::goodbit, clearing all error flags unless there is no stream buffer installed.

After setting the stream state, this function throws an exception of type ios_base::failure if a state flag is set in the stream's state which is also set in the exception mask.

Post Condition
rdstate() == (rdbuf() == 0)? (state | ios_base::badbit): state
Note
An exception is thrown independent from the previous stream state: If, after the stream's state is set, any of the state flags is set in both both the stream's state and in the exception mask, the exception is thrown. Thus, it is possible that an exception is thrown, although effectively one more more error flags are cleared.

basic_ios<cT, traits>::setstate(ios_base::iostate state)

Effect
This function adds the flags set in state to the flags already set in the stream state. The flags are set as if clear(state | rdstate()) is called. This means, that this function will throw an exception if any of the flags set in the exception mask is set in the stream's state at the end of this function.
Post Condition
All flags set in state are set in addition to the flags set prior to this call in rdstate().

basic_ios<cT, traits>::bad() const

Effect
This function tests whether the ios_base::badbit is set in the stream state. This flag is set when there is no stream buffer installed in the stream, when an exception was thrown by a function called from the stream (e.g. by a member of the stream buffer or by a member of a facet used for formatting), or when writing characters failed.
Return
This function returns true if the ios_base::badbit is set in the stream state, i.e. if (rdstate() & ios_base::badbit) != 0.

basic_ios<cT, traits>::eof() const

Effect
This function tests whether the ios_base::eofbit is set in the stream state. This flag is set by convention, when an input function failed to read a character. Thus, it is possible that this function returns false although the stream actually has reached the end of a file. For example, this is the case after reading the last line of file using basic_istream::getline(), if this line was terminated by a new line character. In this case, it is not attempted to read a character following the new line and thus the ios_base::eofbit is not set.
Return
This function returns true if the ios_base::eofbit is set in the stream state, i.e. if (rdstate() & ios_base::eofbit) != 0.

basic_ios<cT, traits>::fail() const

Effect
This function tests whether the ios_base::badbit or the ios_base::failbit is set in the stream state. See above for some reasons why the ios_base::badbit is set. The ios_base::failbit is set, e.g. when an input operation could not extract a value from the stream.
Return
This function returns true if the ios_base::badbit or the ios_base::failbit is set in the stream state, i.e. if (rdstate() & (ios_base::badbit | ios_base::failbit) != 0.

basic_ios<cT, traits>::good() const

Effect
This function is used to test whether no error flags is set in the stream state.
Return
good() returns true if no error flag is set in the stream state, that is if rdstate() == ios_base::goodbit.

basic_ios<cT, traits>::exceptions() const

Effect
This function provides read access to the exception mask currently installed for the stream.
Return
excepionts() returns the current exception mask.

basic_ios<cT, traits>::exceptions(ios_base::iostate state)

Effect
This function set the exception mask for the stream to be state: Whenever a flag set in the exception mask is set at the end of a change applied to the stream state, an exception is thrown. After the exception mask is set, this calls clear() with the current stream state as argument. Thus, if any of the flags set in state is already set in rdstate(), an exception will be thrown.
Post Condition
exceptions() == state
Note
It is not possible to have an exception thrown when the "flag" ios_base::goodbit is set because this value is defined to be zero.

basic_ios<cT, traits>::tie() const

Effect
The function tied provides access to an basic_ostream<cT, traits> tied to the basic_ios<cT, traits> object.
Return
This function returns a pointer to the basic_ostream<cT, traits> currently tied to this stream. If there is no such objcet a null pointer is returned.

basic_ios<cT, traits>::tie(basic_ostram<cT, traits>* other)

Effect
This function installs the basic_ostream<cT, traits> pointed to by other as the stream tied to this stream.
Post Condition
tie() == other
Return
The function returns a pointer to the basic_ostream<cT, traits> which was installed prior to this call or null pointer if there was no such object.
Note
This function does not delete the object which was previously tied to this stream.

basic_ios<cT, traits>::rdbuf() const

Effect
This function provides access to the stream buffer installed in in the stream. This function is called by all functions which need direct access to the stream buffer, e.g. to read or write characters.
Return
The function rdbuf() returns a pointer to the basic_streambuf which is currently installed as stream buffer in this stream. A null pointer is returned, if there is currently no stream buffer installed in this stream.

basic_ios<cT, traits>::rdbuf(basic_streambuf<cT, traits>* sb)

Effect
This function installs sb as new stream buffer in this stream object. After installing sb, the function clear() is called which will set ios_base::badbit if sb is a null pointer.
Post Condition
rdbuf() == sb
Return
The function returns a pointer to the basic_streambuf<cT, traits> installed prior to this call as stream buffer.
Note
Note, that this function does not delete the object which was previously installed in this stream.

basic_ios<cT, traits>::imbue(locale const& loc)

Effect
This function installs a new locale object in the stream. First, this function calls ios_base::imbue(loc). Then, it calls pubimbue(loc) on the currently installed stream buffer, if there is one installed.
Post Condition
ios_base::getloc() == loc
Return
The function returns a copy of the locale object which was installed in the stream prior to the call.
Note
The registered callbacks are called with the event ios_base::imbue_event at a time when the locale object is not yet changed in the stream buffer.

basic_ios<cT, traits>::narrow(cT c, char dfault) const

Effect
This is a convenience function used to convert a character from the stream's character type cT to the implementation's character type char. This function is e.g. used by functions doing some parsing: The parsing functions are expressed in terms of the implementation's character type char and characters from the stream's character type cT are converted before they are inspected by the the parsing functions.

This function does not really implement the conversion functionality: Instead, this functionality is implemented in the ctype<cT> facet installed in the imbued locale object.

Return
narrow() returns the result of
  std::use_facet<std::ctype<cT> >(stream.getloc()).narrow(c, dfault);
	  
(where stream is the object on which the method narrow() is called).
Note
The function basic_ios::narrow() encapsulates quite some machinery and should not be called too often. If you need to narrow characters for your parsing functions, you might consider caching the mapping of characters using ios_base's ios_base::iword()/ ios_base::pword() mechanism.

basic_ios<cT, traits>::widen(char c) const

Effect
This function is a convenience function used to convert a charcter from the implementation's character type char to the stream's character type cT, i.e. the function performs the reverse operation of narrow(): When formatted strings are to be produced, chars are used to create strings which are then converted using widen() to produce characters of a type suitable for the stream.

This function does not really implement the conversion functionality: Instead, this functionality is implemented in the ctype<cT> facet installed in the imbued locale object.

Return
widen() returns the result of
std::use_facet<std::ctype<cT> >(stream.getloc()).widen(c);
	  
(where stream is the object on which the method widen() is called).
Note
The function basic_ios::widen() encapsulates quite some machinery and should not be called too often. If you need widened characters for your formatting functions, you might consider caching the widened characters using ios_base's ios_base::iword()/ ios_base::pword() mechanism.

basic_ios<cT, traits>::fill() const

Effect
This function provides access to the character (of type cT) currently used if a fill character is needed for formatted output.
Return
fill() returns the character currently used as fill character.

basic_ios<cT, traits>::fill(cT c) const

Effect
This function installs the character c as character to be used if a fill character is needed for formatted output.
Post Condition
fill() == c
Return
The function returns the character which was used as fill character prior to this call.

basic_ios<cT, traits>::copyfmt(basic_ios<cT, traits>) const& other

Effect
This function copies all formatting flags, including the setting of the exception mask, from other to the stream. The only members which are not copied are the current stream state and the current stream buffer. Actually, this copying is not trivial:
  1. First, before anything is copied, all callbacks registered for the object are called with the event erase_event. This pass can be used to release any resource associated with the stream object.
  2. All settings from other are copied, except the current stream state, the current stream buffer, and the current exception mask. This includes the contents of the iword() and pword() arrays and the registered callbacks.
  3. The callbacks copied from other (the other are no longer registered; this is unfortunately not explicitly stated in the standard but the only reasonable semantic...) are called with the event copyfmt_event. This pass can be used to clear caches copied from other, to make deep copies of objects, or to do any other copying.
  4. Finally, the exception mask is copied from other. This operation will throw an exception if a bit is set both in rdstate() and other.exceptions().
Post Condition
Here is an overview on the state of the object:

Expression Value
rdbuf() This value stays unchanged.
rdstate() This value stays unchanged.
flags() other.flags()
precision() other.precision()
width() other.width()
getloc() other.getloc()
tie() other.tie()
fill() other.fill()
exceptions() other.exceptions()
iword(idx) other.iword(idx) for all values of idx
pword(idx) other.pword(idx) for all values of idx

Return
This function returns a pointer to the object on which it was called.

See Also

basic_istream(3), basic_ostream(3), basic_streambuf(3), ios_base(3), iostream-objects(3), locale(3)
Copyright © 1999 Dietmar Kühl, Claas Solutions (dietmar.kuehl@claas-solutions.de)