basic_ios.h
Go to the documentation of this file.
// Iostreams base classes -*- C++ -*-
// Copyright (C) 1997-2025 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
#ifdef _GLIBCXX_SYSHDR
#pragma GCC system_header
#endif
#include <bits/localefwd.h>
#include <bits/locale_classes.h>
#include <bits/locale_facets.h>
#include <bits/streambuf_iterator.h>
#include <bits/move.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
{
#if __cplusplus >= 202002L
static_assert(is_same_v<_CharT, typename _Traits::char_type>);
#endif
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>
*/
#if __cplusplus >= 201103L
_GLIBCXX_NODISCARD
explicit operator bool() const
{ return !this->fail(); }
#else
operator void*() const
{ return this->fail() ? 0 : const_cast<basic_ios*>(this); }
#endif
_GLIBCXX_NODISCARD
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().
*/
_GLIBCXX_NODISCARD
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); }
// Flips the internal state on for the proper state bits, then
// rethrows the propagated exception if bit also set in
// exceptions(). Must only be called within a catch handler.
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.
*/
_GLIBCXX_NODISCARD
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.
*/
_GLIBCXX_NODISCARD
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.
*/
_GLIBCXX_NODISCARD
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.
*/
_GLIBCXX_NODISCARD
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.
*/
_GLIBCXX_NODISCARD
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.
*/
_GLIBCXX_NODISCARD
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.
*/
_GLIBCXX_NODISCARD
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.
*/
_GLIBCXX_NODISCARD
char_type
fill() const
{
if (__builtin_expect(!_M_fill_init, false))
return this->widen(' ');
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 = _M_fill;
_M_fill = __ch;
_M_fill_init = true;
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
* https://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
* https://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
* https://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);
#if __cplusplus >= 201103L
basic_ios(const basic_ios&) = delete;
basic_ios& operator=(const basic_ios&) = delete;
void
move(basic_ios& __rhs)
{
ios_base::_M_move(__rhs);
_M_cache_locale(_M_ios_locale);
this->tie(__rhs.tie(nullptr));
_M_fill = __rhs._M_fill;
_M_fill_init = __rhs._M_fill_init;
_M_streambuf = nullptr;
}
void
move(basic_ios&& __rhs)
{ this->move(__rhs); }
void
swap(basic_ios& __rhs) noexcept
{
ios_base::_M_swap(__rhs);
_M_cache_locale(_M_ios_locale);
__rhs._M_cache_locale(__rhs._M_ios_locale);
std::swap(_M_tie, __rhs._M_tie);
std::swap(_M_fill, __rhs._M_fill);
std::swap(_M_fill_init, __rhs._M_fill_init);
}
void
set_rdbuf(basic_streambuf<_CharT, _Traits>* __sb)
{ _M_streambuf = __sb; }
#endif
void
_M_cache_locale(const locale& __loc);
};
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace
#include <bits/basic_ios.tcc>
#endif /* _BASIC_IOS_H */
streambuf_iterator.h
move.h
localefwd.h
basic_ios.tcc
locale_facets.h
locale_classes.h
std::move
constexpr std::remove_reference< _Tp >::type && move(_Tp &&__t) noexcept
Convert a value to an rvalue.
Definition move.h:138
std
ISO C++ entities toplevel namespace is std.
std::basic_ios
Template class basic_ios, virtual base class for all stream classes.
Definition basic_ios.h:70
std::basic_ios::clear
void clear(iostate __state=goodbit)
[Re]sets the error state.
Definition basic_ios.tcc:46
std::basic_ios::eof
bool eof() const
Fast error checking.
Definition basic_ios.h:201
std::basic_ios::imbue
locale imbue(const locale &__loc)
Moves to a new locale.
Definition basic_ios.tcc:119
std::basic_ios::rdbuf
basic_streambuf< _CharT, _Traits > * rdbuf(basic_streambuf< _CharT, _Traits > *__sb)
Changing the underlying buffer.
Definition basic_ios.tcc:58
std::basic_ios< char_type, traits_type >::__ctype_type
ctype< char_type > __ctype_type
Definition basic_ios.h:93
std::basic_ios< char_type, traits_type >::pos_type
traits_type::pos_type pos_type
Definition basic_ios.h:84
std::basic_ios::tie
basic_ostream< _CharT, _Traits > * tie() const
Fetches the current tied stream.
Definition basic_ios.h:310
std::basic_ios::exceptions
iostate exceptions() const
Throwing exceptions on errors.
Definition basic_ios.h:236
std::basic_ios< char_type, traits_type >::traits_type
traits_type traits_type
Definition basic_ios.h:86
std::basic_ios::setstate
void setstate(iostate __state)
Sets additional flags in the error state.
Definition basic_ios.h:166
std::basic_ios::basic_ios
basic_ios()
Empty.
Definition basic_ios.h:475
std::basic_ios::operator!
bool operator!() const
The quick-and-easy status check.
Definition basic_ios.h:133
std::basic_ios::copyfmt
basic_ios & copyfmt(const basic_ios &__rhs)
Copies fields of __rhs into this.
Definition basic_ios.tcc:68
std::basic_ios::fill
char_type fill(char_type __ch)
Sets a new empty character.
Definition basic_ios.h:404
std::basic_ios::rdstate
iostate rdstate() const
Returns the error state of the stream buffer.
Definition basic_ios.h:146
std::basic_ios::init
void init(basic_streambuf< _CharT, _Traits > *__sb)
All setup is performed here.
Definition basic_ios.tcc:131
std::basic_ios::good
bool good() const
Fast error checking.
Definition basic_ios.h:190
std::basic_ios::widen
char_type widen(char __c) const
Widens characters.
Definition basic_ios.h:464
std::basic_ios::fill
char_type fill() const
Retrieves the empty character.
Definition basic_ios.h:387
std::basic_ios::narrow
char narrow(char_type __c, char __dfault) const
Squeezes characters.
Definition basic_ios.h:445
std::basic_ios::~basic_ios
virtual ~basic_ios()
Empty.
Definition basic_ios.h:296
std::basic_ios< char_type, traits_type >::off_type
traits_type::off_type off_type
Definition basic_ios.h:85
std::basic_ios::fail
bool fail() const
Fast error checking.
Definition basic_ios.h:213
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:322
std::basic_ios::rdbuf
basic_streambuf< _CharT, _Traits > * rdbuf() const
Accessing the underlying buffer.
Definition basic_ios.h:337
std::basic_ios< char_type, traits_type >::char_type
char_type char_type
Definition basic_ios.h:82
std::basic_ios< char_type, traits_type >::int_type
traits_type::int_type int_type
Definition basic_ios.h:83
std::basic_ios< char_type, traits_type >::__num_put_type
num_put< char_type, ostreambuf_iterator< char_type, traits_type > > __num_put_type
Definition basic_ios.h:95
std::basic_ios< char_type, traits_type >::__num_get_type
num_get< char_type, istreambuf_iterator< char_type, traits_type > > __num_get_type
Definition basic_ios.h:97
std::basic_ios::bad
bool bad() const
Fast error checking.
Definition basic_ios.h:224
std::basic_ios::basic_ios
basic_ios(basic_streambuf< _CharT, _Traits > *__sb)
Constructor performs initialization.
Definition basic_ios.h:284
std::basic_ios::exceptions
void exceptions(iostate __except)
Throwing exceptions on errors.
Definition basic_ios.h:271
std::basic_streambuf
The actual work of input and output (interface).
Definition streambuf:127
std::basic_ostream
Template class basic_ostream.
Definition ostream.h:67
std::basic_ios< char_type, traits_type >::iostate
_Ios_Iostate iostate
Definition ios_base.h:453
std::basic_ios< char_type, traits_type >::eofbit
static const iostate eofbit
Definition ios_base.h:460
std::basic_ios< char_type, traits_type >::goodbit
static const iostate goodbit
Definition ios_base.h:468
std::basic_ios< char_type, traits_type >::badbit
static const iostate badbit
Definition ios_base.h:457
std::basic_ios< char_type, traits_type >::failbit
static const iostate failbit
Definition ios_base.h:465
std::locale
Container class for localization functionality.
Definition locale_classes.h:69
std::ctype
Primary class template ctype facet.
Definition locale_facets.h:618
std::num_get
Primary class template num_get.
Definition locale_facets.h:1963
std::num_put
Primary class template num_put.
Definition locale_facets.h:2327