basic_ios.h
Go to the documentation of this file.
// Iostreams base classes -*- C++ -*-
// Copyright (C) 1997-2014 Free Software Foundation, Inc.
//
// This file is part of the GNU ISO C++ Library. This library is free
// software; you can redistribute it and/or modify it under the
// terms of the GNU General Public License as published by the
// Free Software Foundation; either version 3, or (at your option)
// any later version.
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// Under Section 7 of GPL version 3, you are granted additional
// permissions described in the GCC Runtime Library Exception, version
// 3.1, as published by the Free Software Foundation.
// You should have received a copy of the GNU General Public License and
// a copy of the GCC Runtime Library Exception along with this program;
// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
// <http://www.gnu.org/licenses/>.
/** @file bits/basic_ios.h
* This is an internal header file, included by other library headers.
* Do not attempt to use it directly. @headername{ios}
*/
#ifndef _BASIC_IOS_H
#define _BASIC_IOS_H 1
#pragma GCC system_header
#include <bits/localefwd.h>
#include <bits/locale_classes.h>
#include <bits/locale_facets.h>
#include <bits/streambuf_iterator.h>
namespace std _GLIBCXX_VISIBILITY(default)
{
_GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _Facet>
inline const _Facet&
__check_facet(const _Facet* __f)
{
if (!__f)
__throw_bad_cast();
return *__f;
}
/**
* @brief Template class basic_ios, virtual base class for all
* stream classes.
* @ingroup io
*
* @tparam _CharT Type of character stream.
* @tparam _Traits Traits for character type, defaults to
* char_traits<_CharT>.
*
* Most of the member functions called dispatched on stream objects
* (e.g., @c std::cout.foo(bar);) are consolidated in this class.
*/
template<typename _CharT, typename _Traits>
class basic_ios : public ios_base
{
public:
//@{
/**
* These are standard types. They permit a standardized way of
* referring to names of (or names dependent on) the template
* parameters, which are specific to the implementation.
*/
typedef _CharT 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;
//@}
//@{
/**
* These are non-standard types.
*/
typedef ctype<_CharT> __ctype_type;
typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> >
__num_put_type;
typedef num_get<_CharT, istreambuf_iterator<_CharT, _Traits> >
__num_get_type;
//@}
// Data members:
protected:
basic_ostream<_CharT, _Traits>* _M_tie;
mutable char_type _M_fill;
mutable bool _M_fill_init;
basic_streambuf<_CharT, _Traits>* _M_streambuf;
// Cached use_facet<ctype>, which is based on the current locale info.
const __ctype_type* _M_ctype;
// For ostream.
const __num_put_type* _M_num_put;
// For istream.
const __num_get_type* _M_num_get;
public:
//@{
/**
* @brief The quick-and-easy status check.
*
* This allows you to write constructs such as
* <code>if (!a_stream) ...</code> and <code>while (a_stream) ...</code>
*/
operator void*() const
{ return this->fail() ? 0 : const_cast< basic_ios*>(this); }
bool
operator!() const
{ return this->fail(); }
//@}
/**
* @brief Returns the error state of the stream buffer.
* @return A bit pattern (well, isn't everything?)
*
* See std::ios_base::iostate for the possible bit values. Most
* users will call one of the interpreting wrappers, e.g., good().
*/
iostate
rdstate() const
{ return _M_streambuf_state; }
/**
* @brief [Re]sets the error state.
* @param __state The new state flag(s) to set.
*
* See std::ios_base::iostate for the possible bit values. Most
* users will not need to pass an argument.
*/
void
clear(iostate __state = goodbit);
/**
* @brief Sets additional flags in the error state.
* @param __state The additional state flag(s) to set.
*
* See std::ios_base::iostate for the possible bit values.
*/
void
setstate(iostate __state)
{ this->clear(this->rdstate() | __state); }
// Flip the internal state on for the proper state bits, then re
// throws the propagated exception if bit also set in
// exceptions().
void
_M_setstate(iostate __state)
{
// 27.6.1.2.1 Common requirements.
// Turn this on without causing an ios::failure to be thrown.
_M_streambuf_state |= __state;
if (this->exceptions() & __state)
__throw_exception_again;
}
/**
* @brief Fast error checking.
* @return True if no error flags are set.
*
* A wrapper around rdstate.
*/
bool
good() const
{ return this->rdstate() == 0; }
/**
* @brief Fast error checking.
* @return True if the eofbit is set.
*
* Note that other iostate flags may also be set.
*/
bool
eof() const
{ return (this->rdstate() & eofbit) != 0; }
/**
* @brief Fast error checking.
* @return True if either the badbit or the failbit is set.
*
* Checking the badbit in fail() is historical practice.
* Note that other iostate flags may also be set.
*/
bool
fail() const
{ return (this->rdstate() & (badbit | failbit)) != 0; }
/**
* @brief Fast error checking.
* @return True if the badbit is set.
*
* Note that other iostate flags may also be set.
*/
bool
bad() const
{ return (this->rdstate() & badbit) != 0; }
/**
* @brief Throwing exceptions on errors.
* @return The current exceptions mask.
*
* This changes nothing in the stream. See the one-argument version
* of exceptions(iostate) for the meaning of the return value.
*/
iostate
exceptions() const
{ return _M_exception; }
/**
* @brief Throwing exceptions on errors.
* @param __except The new exceptions mask.
*
* By default, error flags are set silently. You can set an
* exceptions mask for each stream; if a bit in the mask becomes set
* in the error flags, then an exception of type
* std::ios_base::failure is thrown.
*
* If the error flag is already set when the exceptions mask is
* added, the exception is immediately thrown. Try running the
* following under GCC 3.1 or later:
* @code
* #include <iostream>
* #include <fstream>
* #include <exception>
*
* int main()
* {
* std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
*
* std::ifstream f ("/etc/motd");
*
* std::cerr << "Setting badbit\n";
* f.setstate (std::ios_base::badbit);
*
* std::cerr << "Setting exception mask\n";
* f.exceptions (std::ios_base::badbit);
* }
* @endcode
*/
void
exceptions(iostate __except)
{
_M_exception = __except;
this->clear(_M_streambuf_state);
}
// Constructor/destructor:
/**
* @brief Constructor performs initialization.
*
* The parameter is passed by derived streams.
*/
explicit
basic_ios(basic_streambuf<_CharT, _Traits>* __sb)
: ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0),
_M_ctype(0), _M_num_put(0), _M_num_get(0)
{ this->init(__sb); }
/**
* @brief Empty.
*
* The destructor does nothing. More specifically, it does not
* destroy the streambuf held by rdbuf().
*/
virtual
~basic_ios() { }
// Members:
/**
* @brief Fetches the current @e tied stream.
* @return A pointer to the tied stream, or NULL if the stream is
* not tied.
*
* A stream may be @e tied (or synchronized) to a second output
* stream. When this stream performs any I/O, the tied stream is
* first flushed. For example, @c std::cin is tied to @c std::cout.
*/
basic_ostream<_CharT, _Traits>*
tie() const
{ return _M_tie; }
/**
* @brief Ties this stream to an output stream.
* @param __tiestr The output stream.
* @return The previously tied output stream, or NULL if the stream
* was not tied.
*
* This sets up a new tie; see tie() for more.
*/
basic_ostream<_CharT, _Traits>*
tie(basic_ostream<_CharT, _Traits>* __tiestr)
{
basic_ostream<_CharT, _Traits>* __old = _M_tie;
_M_tie = __tiestr;
return __old;
}
/**
* @brief Accessing the underlying buffer.
* @return The current stream buffer.
*
* This does not change the state of the stream.
*/
basic_streambuf<_CharT, _Traits>*
rdbuf() const
{ return _M_streambuf; }
/**
* @brief Changing the underlying buffer.
* @param __sb The new stream buffer.
* @return The previous stream buffer.
*
* Associates a new buffer with the current stream, and clears the
* error state.
*
* Due to historical accidents which the LWG refuses to correct, the
* I/O library suffers from a design error: this function is hidden
* in derived classes by overrides of the zero-argument @c rdbuf(),
* which is non-virtual for hysterical raisins. As a result, you
* must use explicit qualifications to access this function via any
* derived class. For example:
*
* @code
* std::fstream foo; // or some other derived type
* std::streambuf* p = .....;
*
* foo.ios::rdbuf(p); // ios == basic_ios<char>
* @endcode
*/
basic_streambuf<_CharT, _Traits>*
rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
/**
* @brief Copies fields of __rhs into this.
* @param __rhs The source values for the copies.
* @return Reference to this object.
*
* All fields of __rhs are copied into this object except that rdbuf()
* and rdstate() remain unchanged. All values in the pword and iword
* arrays are copied. Before copying, each callback is invoked with
* erase_event. After copying, each (new) callback is invoked with
* copyfmt_event. The final step is to copy exceptions().
*/
basic_ios&
copyfmt(const basic_ios& __rhs);
/**
* @brief Retrieves the @a empty character.
* @return The current fill character.
*
* It defaults to a space (' ') in the current locale.
*/
char_type
fill() const
{
if (!_M_fill_init)
{
_M_fill = this->widen(' ');
_M_fill_init = true;
}
return _M_fill;
}
/**
* @brief Sets a new @a empty character.
* @param __ch The new character.
* @return The previous fill character.
*
* The fill character is used to fill out space when P+ characters
* have been requested (e.g., via setw), Q characters are actually
* used, and Q<P. It defaults to a space (' ') in the current locale.
*/
char_type
fill(char_type __ch)
{
char_type __old = this->fill();
_M_fill = __ch;
return __old;
}
// Locales:
/**
* @brief Moves to a new locale.
* @param __loc The new locale.
* @return The previous locale.
*
* Calls @c ios_base::imbue(loc), and if a stream buffer is associated
* with this stream, calls that buffer's @c pubimbue(loc).
*
* Additional l10n notes are at
* http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
*/
locale
imbue(const locale& __loc);
/**
* @brief Squeezes characters.
* @param __c The character to narrow.
* @param __dfault The character to narrow.
* @return The narrowed character.
*
* Maps a character of @c char_type to a character of @c char,
* if possible.
*
* Returns the result of
* @code
* std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault)
* @endcode
*
* Additional l10n notes are at
* http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
*/
char
narrow(char_type __c, char __dfault) const
{ return __check_facet(_M_ctype).narrow(__c, __dfault); }
/**
* @brief Widens characters.
* @param __c The character to widen.
* @return The widened character.
*
* Maps a character of @c char to a character of @c char_type.
*
* Returns the result of
* @code
* std::use_facet<ctype<char_type> >(getloc()).widen(c)
* @endcode
*
* Additional l10n notes are at
* http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
*/
char_type
widen(char __c) const
{ return __check_facet(_M_ctype).widen(__c); }
protected:
// 27.4.5.1 basic_ios constructors
/**
* @brief Empty.
*
* The default constructor does nothing and is not normally
* accessible to users.
*/
basic_ios()
: ios_base(), _M_tie(0), _M_fill(char_type()), _M_fill_init(false),
_M_streambuf(0), _M_ctype(0), _M_num_put(0), _M_num_get(0)
{ }
/**
* @brief All setup is performed here.
*
* This is called from the public constructor. It is not virtual and
* cannot be redefined.
*/
void
init(basic_streambuf<_CharT, _Traits>* __sb);
void
_M_cache_locale(const locale& __loc);
};
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace
#include <bits/basic_ios.tcc>
#endif /* _BASIC_IOS_H */
locale_facets.h
std::basic_ios::__num_put_type
num_put< _CharT, ostreambuf_iterator< _CharT, _Traits > > __num_put_type
Definition: basic_ios.h:88
std::basic_ios::int_type
_Traits::int_type int_type
Definition: basic_ios.h:76
std::basic_ios::traits_type
_Traits traits_type
Definition: basic_ios.h:79
std::basic_ios::operator!
bool operator!() const
The quick-and-easy status check.
Definition: basic_ios.h:119
std::basic_ios::basic_ios
basic_ios(basic_streambuf< _CharT, _Traits > *__sb)
Constructor performs initialization.
Definition: basic_ios.h:264
std::basic_ios::fill
char_type fill(char_type __ch)
Sets a new empty character.
Definition: basic_ios.h:384
std::ios_base::iostate
_Ios_Iostate iostate
This is a bitmask type.
Definition: ios_base.h:330
std::basic_ios::rdstate
iostate rdstate() const
Returns the error state of the stream buffer.
Definition: basic_ios.h:131
std::basic_ios::char_type
_CharT char_type
Definition: basic_ios.h:75
std::ios_base::badbit
static const iostate badbit
Indicates a loss of integrity in an input or output sequence (such as an irrecoverable read error fro...
Definition: ios_base.h:334
std::basic_ios::off_type
_Traits::off_type off_type
Definition: basic_ios.h:78
std::basic_ios::pos_type
_Traits::pos_type pos_type
Definition: basic_ios.h:77
std::basic_ios::good
bool good() const
Fast error checking.
Definition: basic_ios.h:174
std::basic_ios::fail
bool fail() const
Fast error checking.
Definition: basic_ios.h:195
std::basic_ios::clear
void clear(iostate __state=goodbit)
[Re]sets the error state.
Definition: basic_ios.tcc:41
std::basic_ios::eof
bool eof() const
Fast error checking.
Definition: basic_ios.h:184
std::basic_ios::__num_get_type
num_get< _CharT, istreambuf_iterator< _CharT, _Traits > > __num_get_type
Definition: basic_ios.h:90
std::basic_ios::copyfmt
basic_ios & copyfmt(const basic_ios &__rhs)
Copies fields of __rhs into this.
Definition: basic_ios.tcc:63
std::basic_ios::init
void init(basic_streambuf< _CharT, _Traits > *__sb)
All setup is performed here.
Definition: basic_ios.tcc:126
std::basic_ios::basic_ios
basic_ios()
Empty.
Definition: basic_ios.h:454
localefwd.h
std::ios_base
The base of the I/O class hierarchy.This class defines everything that can be defined about I/O that ...
Definition: ios_base.h:199
std::locale
Container class for localization functionality.The locale class is first a class wrapper for C librar...
Definition: locale_classes.h:62
std::basic_ios::setstate
void setstate(iostate __state)
Sets additional flags in the error state.
Definition: basic_ios.h:151
std::ios_base::eofbit
static const iostate eofbit
Indicates that an input operation reached the end of an input sequence.
Definition: ios_base.h:337
basic_ios.tcc
std::basic_ios::~basic_ios
virtual ~basic_ios()
Empty.
Definition: basic_ios.h:276
locale_classes.h
streambuf_iterator.h
std::basic_ios
Template class basic_ios, virtual base class for all stream classes.
Definition: iosfwd:77
std::basic_ios::exceptions
void exceptions(iostate __except)
Throwing exceptions on errors.
Definition: basic_ios.h:251
std::basic_ios::exceptions
iostate exceptions() const
Throwing exceptions on errors.
Definition: basic_ios.h:216
std::basic_ios::rdbuf
basic_streambuf< _CharT, _Traits > * rdbuf() const
Accessing the underlying buffer.
Definition: basic_ios.h:315
std::basic_ostream
Template class basic_ostream.
Definition: iosfwd:86
std::num_put
Primary class template num_put.This facet encapsulates the code to convert a number to a string...
Definition: locale_facets.h:2254
std::basic_ios::widen
char_type widen(char __c) const
Widens characters.
Definition: basic_ios.h:443
std::ios_base::goodbit
static const iostate goodbit
Indicates all is well.
Definition: ios_base.h:345
std::ctype
Primary class template ctype facet.This template class defines classification and conversion function...
Definition: locale_facets.h:605
std::basic_ios::imbue
locale imbue(const locale &__loc)
Moves to a new locale.
Definition: basic_ios.tcc:114
std::ios_base::failbit
static const iostate failbit
Indicates that an input operation failed to read the expected characters, or that an output operation...
Definition: ios_base.h:342
std::basic_ios::__ctype_type
ctype< _CharT > __ctype_type
Definition: basic_ios.h:86
std::basic_ios::bad
bool bad() const
Fast error checking.
Definition: basic_ios.h:205
std::ctype< char >
The ctype<char> specialization.This class defines classification and conversion functions for the cha...
Definition: locale_facets.h:674
std::basic_ios::tie
basic_ostream< _CharT, _Traits > * tie(basic_ostream< _CharT, _Traits > *__tiestr)
Ties this stream to an output stream.
Definition: basic_ios.h:301
std::basic_ios::narrow
char narrow(char_type __c, char __dfault) const
Squeezes characters.
Definition: basic_ios.h:424
std::basic_ios::fill
char_type fill() const
Retrieves the empty character.
Definition: basic_ios.h:364
std::basic_ios::tie
basic_ostream< _CharT, _Traits > * tie() const
Fetches the current tied stream.
Definition: basic_ios.h:289
std::basic_streambuf
The actual work of input and output (interface).
Definition: iosfwd:80
std::num_get
Primary class template num_get.This facet encapsulates the code to parse and return a number from a s...
Definition: locale_facets.h:1915