|
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:
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.
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().
-
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().
-
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:
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.
-
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
(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
(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:
-
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.
-
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.
-
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.
-
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:
-
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)
|