libstdc++
basic_ios.h
Go to the documentation of this file.
1 // Iostreams base classes -*- C++ -*-
2 
3 // Copyright (C) 1997-2025 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10 
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15 
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19 
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24 
25 /** @file bits/basic_ios.h
26  * This is an internal header file, included by other library headers.
27  * Do not attempt to use it directly. @headername{ios}
28  */
29 
30 #ifndef _BASIC_IOS_H
31 #define _BASIC_IOS_H 1
32 
33 #ifdef _GLIBCXX_SYSHDR
34 #pragma GCC system_header
35 #endif
36 
37 #include <bits/localefwd.h>
38 #include <bits/locale_classes.h>
39 #include <bits/locale_facets.h>
41 #include <bits/move.h>
42 
43 namespace std _GLIBCXX_VISIBILITY(default)
44 {
45 _GLIBCXX_BEGIN_NAMESPACE_VERSION
46 
47  template<typename _Facet>
48  inline const _Facet&
49  __check_facet(const _Facet* __f)
50  {
51  if (!__f)
52  __throw_bad_cast();
53  return *__f;
54  }
55 
56  /**
57  * @brief Template class basic_ios, virtual base class for all
58  * stream classes.
59  * @ingroup io
60  *
61  * @tparam _CharT Type of character stream.
62  * @tparam _Traits Traits for character type, defaults to
63  * char_traits<_CharT>.
64  *
65  * Most of the member functions called dispatched on stream objects
66  * (e.g., @c std::cout.foo(bar);) are consolidated in this class.
67  */
68  template<typename _CharT, typename _Traits>
69  class basic_ios : public ios_base
70  {
71 #if __cplusplus >= 202002L
72  static_assert(is_same_v<_CharT, typename _Traits::char_type>);
73 #endif
74 
75  public:
76  ///@{
77  /**
78  * These are standard types. They permit a standardized way of
79  * referring to names of (or names dependent on) the template
80  * parameters, which are specific to the implementation.
81  */
82  typedef _CharT char_type;
83  typedef typename _Traits::int_type int_type;
84  typedef typename _Traits::pos_type pos_type;
85  typedef typename _Traits::off_type off_type;
86  typedef _Traits traits_type;
87  ///@}
88 
89  ///@{
90  /**
91  * These are non-standard types.
92  */
98  ///@}
99 
100  // Data members:
101  protected:
103  mutable char_type _M_fill;
104  mutable bool _M_fill_init;
105  basic_streambuf<_CharT, _Traits>* _M_streambuf;
106 
107  // Cached use_facet<ctype>, which is based on the current locale info.
108  const __ctype_type* _M_ctype;
109  // For ostream.
110  const __num_put_type* _M_num_put;
111  // For istream.
112  const __num_get_type* _M_num_get;
113 
114  public:
115  ///@{
116  /**
117  * @brief The quick-and-easy status check.
118  *
119  * This allows you to write constructs such as
120  * <code>if (!a_stream) ...</code> and <code>while (a_stream) ...</code>
121  */
122 #if __cplusplus >= 201103L
123  _GLIBCXX_NODISCARD
124  explicit operator bool() const
125  { return !this->fail(); }
126 #else
127  operator void*() const
128  { return this->fail() ? 0 : const_cast<basic_ios*>(this); }
129 #endif
130 
131  _GLIBCXX_NODISCARD
132  bool
133  operator!() const
134  { return this->fail(); }
135  ///@}
136 
137  /**
138  * @brief Returns the error state of the stream buffer.
139  * @return A bit pattern (well, isn't everything?)
140  *
141  * See std::ios_base::iostate for the possible bit values. Most
142  * users will call one of the interpreting wrappers, e.g., good().
143  */
144  _GLIBCXX_NODISCARD
145  iostate
146  rdstate() const
147  { return _M_streambuf_state; }
148 
149  /**
150  * @brief [Re]sets the error state.
151  * @param __state The new state flag(s) to set.
152  *
153  * See std::ios_base::iostate for the possible bit values. Most
154  * users will not need to pass an argument.
155  */
156  void
157  clear(iostate __state = goodbit);
158 
159  /**
160  * @brief Sets additional flags in the error state.
161  * @param __state The additional state flag(s) to set.
162  *
163  * See std::ios_base::iostate for the possible bit values.
164  */
165  void
166  setstate(iostate __state)
167  { this->clear(this->rdstate() | __state); }
168 
169  // Flips the internal state on for the proper state bits, then
170  // rethrows the propagated exception if bit also set in
171  // exceptions(). Must only be called within a catch handler.
172  void
173  _M_setstate(iostate __state)
174  {
175  // 27.6.1.2.1 Common requirements.
176  // Turn this on without causing an ios::failure to be thrown.
177  _M_streambuf_state |= __state;
178  if (this->exceptions() & __state)
179  { __throw_exception_again; }
180  }
181 
182  /**
183  * @brief Fast error checking.
184  * @return True if no error flags are set.
185  *
186  * A wrapper around rdstate.
187  */
188  _GLIBCXX_NODISCARD
189  bool
190  good() const
191  { return this->rdstate() == 0; }
192 
193  /**
194  * @brief Fast error checking.
195  * @return True if the eofbit is set.
196  *
197  * Note that other iostate flags may also be set.
198  */
199  _GLIBCXX_NODISCARD
200  bool
201  eof() const
202  { return (this->rdstate() & eofbit) != 0; }
203 
204  /**
205  * @brief Fast error checking.
206  * @return True if either the badbit or the failbit is set.
207  *
208  * Checking the badbit in fail() is historical practice.
209  * Note that other iostate flags may also be set.
210  */
211  _GLIBCXX_NODISCARD
212  bool
213  fail() const
214  { return (this->rdstate() & (badbit | failbit)) != 0; }
215 
216  /**
217  * @brief Fast error checking.
218  * @return True if the badbit is set.
219  *
220  * Note that other iostate flags may also be set.
221  */
222  _GLIBCXX_NODISCARD
223  bool
224  bad() const
225  { return (this->rdstate() & badbit) != 0; }
226 
227  /**
228  * @brief Throwing exceptions on errors.
229  * @return The current exceptions mask.
230  *
231  * This changes nothing in the stream. See the one-argument version
232  * of exceptions(iostate) for the meaning of the return value.
233  */
234  _GLIBCXX_NODISCARD
235  iostate
236  exceptions() const
237  { return _M_exception; }
238 
239  /**
240  * @brief Throwing exceptions on errors.
241  * @param __except The new exceptions mask.
242  *
243  * By default, error flags are set silently. You can set an
244  * exceptions mask for each stream; if a bit in the mask becomes set
245  * in the error flags, then an exception of type
246  * std::ios_base::failure is thrown.
247  *
248  * If the error flag is already set when the exceptions mask is
249  * added, the exception is immediately thrown. Try running the
250  * following under GCC 3.1 or later:
251  * @code
252  * #include <iostream>
253  * #include <fstream>
254  * #include <exception>
255  *
256  * int main()
257  * {
258  * std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
259  *
260  * std::ifstream f ("/etc/motd");
261  *
262  * std::cerr << "Setting badbit\n";
263  * f.setstate (std::ios_base::badbit);
264  *
265  * std::cerr << "Setting exception mask\n";
266  * f.exceptions (std::ios_base::badbit);
267  * }
268  * @endcode
269  */
270  void
271  exceptions(iostate __except)
272  {
273  _M_exception = __except;
274  this->clear(_M_streambuf_state);
275  }
276 
277  // Constructor/destructor:
278  /**
279  * @brief Constructor performs initialization.
280  *
281  * The parameter is passed by derived streams.
282  */
283  explicit
285  : ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0),
286  _M_ctype(0), _M_num_put(0), _M_num_get(0)
287  { this->init(__sb); }
288 
289  /**
290  * @brief Empty.
291  *
292  * The destructor does nothing. More specifically, it does not
293  * destroy the streambuf held by rdbuf().
294  */
295  virtual
297 
298  // Members:
299  /**
300  * @brief Fetches the current @e tied stream.
301  * @return A pointer to the tied stream, or NULL if the stream is
302  * not tied.
303  *
304  * A stream may be @e tied (or synchronized) to a second output
305  * stream. When this stream performs any I/O, the tied stream is
306  * first flushed. For example, @c std::cin is tied to @c std::cout.
307  */
308  _GLIBCXX_NODISCARD
310  tie() const
311  { return _M_tie; }
312 
313  /**
314  * @brief Ties this stream to an output stream.
315  * @param __tiestr The output stream.
316  * @return The previously tied output stream, or NULL if the stream
317  * was not tied.
318  *
319  * This sets up a new tie; see tie() for more.
320  */
323  {
324  basic_ostream<_CharT, _Traits>* __old = _M_tie;
325  _M_tie = __tiestr;
326  return __old;
327  }
328 
329  /**
330  * @brief Accessing the underlying buffer.
331  * @return The current stream buffer.
332  *
333  * This does not change the state of the stream.
334  */
335  _GLIBCXX_NODISCARD
337  rdbuf() const
338  { return _M_streambuf; }
339 
340  /**
341  * @brief Changing the underlying buffer.
342  * @param __sb The new stream buffer.
343  * @return The previous stream buffer.
344  *
345  * Associates a new buffer with the current stream, and clears the
346  * error state.
347  *
348  * Due to historical accidents which the LWG refuses to correct, the
349  * I/O library suffers from a design error: this function is hidden
350  * in derived classes by overrides of the zero-argument @c rdbuf(),
351  * which is non-virtual for hysterical raisins. As a result, you
352  * must use explicit qualifications to access this function via any
353  * derived class. For example:
354  *
355  * @code
356  * std::fstream foo; // or some other derived type
357  * std::streambuf* p = .....;
358  *
359  * foo.ios::rdbuf(p); // ios == basic_ios<char>
360  * @endcode
361  */
364 
365  /**
366  * @brief Copies fields of __rhs into this.
367  * @param __rhs The source values for the copies.
368  * @return Reference to this object.
369  *
370  * All fields of __rhs are copied into this object except that rdbuf()
371  * and rdstate() remain unchanged. All values in the pword and iword
372  * arrays are copied. Before copying, each callback is invoked with
373  * erase_event. After copying, each (new) callback is invoked with
374  * copyfmt_event. The final step is to copy exceptions().
375  */
376  basic_ios&
377  copyfmt(const basic_ios& __rhs);
378 
379  /**
380  * @brief Retrieves the @a empty character.
381  * @return The current fill character.
382  *
383  * It defaults to a space (' ') in the current locale.
384  */
385  _GLIBCXX_NODISCARD
386  char_type
387  fill() const
388  {
389  if (__builtin_expect(!_M_fill_init, false))
390  return this->widen(' ');
391  return _M_fill;
392  }
393 
394  /**
395  * @brief Sets a new @a empty character.
396  * @param __ch The new character.
397  * @return The previous fill character.
398  *
399  * The fill character is used to fill out space when P+ characters
400  * have been requested (e.g., via setw), Q characters are actually
401  * used, and Q<P. It defaults to a space (' ') in the current locale.
402  */
403  char_type
405  {
406  char_type __old = _M_fill;
407  _M_fill = __ch;
408  _M_fill_init = true;
409  return __old;
410  }
411 
412  // Locales:
413  /**
414  * @brief Moves to a new locale.
415  * @param __loc The new locale.
416  * @return The previous locale.
417  *
418  * Calls @c ios_base::imbue(loc), and if a stream buffer is associated
419  * with this stream, calls that buffer's @c pubimbue(loc).
420  *
421  * Additional l10n notes are at
422  * https://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
423  */
424  locale
425  imbue(const locale& __loc);
426 
427  /**
428  * @brief Squeezes characters.
429  * @param __c The character to narrow.
430  * @param __dfault The character to narrow.
431  * @return The narrowed character.
432  *
433  * Maps a character of @c char_type to a character of @c char,
434  * if possible.
435  *
436  * Returns the result of
437  * @code
438  * std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault)
439  * @endcode
440  *
441  * Additional l10n notes are at
442  * https://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
443  */
444  char
445  narrow(char_type __c, char __dfault) const
446  { return __check_facet(_M_ctype).narrow(__c, __dfault); }
447 
448  /**
449  * @brief Widens characters.
450  * @param __c The character to widen.
451  * @return The widened character.
452  *
453  * Maps a character of @c char to a character of @c char_type.
454  *
455  * Returns the result of
456  * @code
457  * std::use_facet<ctype<char_type> >(getloc()).widen(c)
458  * @endcode
459  *
460  * Additional l10n notes are at
461  * https://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
462  */
463  char_type
464  widen(char __c) const
465  { return __check_facet(_M_ctype).widen(__c); }
466 
467  protected:
468  // 27.4.5.1 basic_ios constructors
469  /**
470  * @brief Empty.
471  *
472  * The default constructor does nothing and is not normally
473  * accessible to users.
474  */
476  : ios_base(), _M_tie(0), _M_fill(char_type()), _M_fill_init(false),
477  _M_streambuf(0), _M_ctype(0), _M_num_put(0), _M_num_get(0)
478  { }
479 
480  /**
481  * @brief All setup is performed here.
482  *
483  * This is called from the public constructor. It is not virtual and
484  * cannot be redefined.
485  */
486  void
488 
489 #if __cplusplus >= 201103L
490  basic_ios(const basic_ios&) = delete;
491  basic_ios& operator=(const basic_ios&) = delete;
492 
493  void
494  move(basic_ios& __rhs)
495  {
496  ios_base::_M_move(__rhs);
497  _M_cache_locale(_M_ios_locale);
498  this->tie(__rhs.tie(nullptr));
499  _M_fill = __rhs._M_fill;
500  _M_fill_init = __rhs._M_fill_init;
501  _M_streambuf = nullptr;
502  }
503 
504  void
505  move(basic_ios&& __rhs)
506  { this->move(__rhs); }
507 
508  void
509  swap(basic_ios& __rhs) noexcept
510  {
511  ios_base::_M_swap(__rhs);
512  _M_cache_locale(_M_ios_locale);
513  __rhs._M_cache_locale(__rhs._M_ios_locale);
514  std::swap(_M_tie, __rhs._M_tie);
515  std::swap(_M_fill, __rhs._M_fill);
516  std::swap(_M_fill_init, __rhs._M_fill_init);
517  }
518 
519  void
520  set_rdbuf(basic_streambuf<_CharT, _Traits>* __sb)
521  { _M_streambuf = __sb; }
522 #endif
523 
524  void
525  _M_cache_locale(const locale& __loc);
526  };
527 
528 _GLIBCXX_END_NAMESPACE_VERSION
529 } // namespace
530 
531 #include <bits/basic_ios.tcc>
532 
533 #endif /* _BASIC_IOS_H */
ISO C++ entities toplevel namespace is std.
Template class basic_ios, virtual base class for all stream classes.
Definition: basic_ios.h:70
void clear(iostate __state=goodbit)
[Re]sets the error state.
Definition: basic_ios.tcc:46
bool eof() const
Fast error checking.
Definition: basic_ios.h:201
locale imbue(const locale &__loc)
Moves to a new locale.
Definition: basic_ios.tcc:119
ctype< _CharT > __ctype_type
Definition: basic_ios.h:93
basic_ostream< _CharT, _Traits > * tie() const
Fetches the current tied stream.
Definition: basic_ios.h:310
_Traits::pos_type pos_type
Definition: basic_ios.h:84
basic_streambuf< _CharT, _Traits > * rdbuf() const
Accessing the underlying buffer.
Definition: basic_ios.h:337
iostate exceptions() const
Throwing exceptions on errors.
Definition: basic_ios.h:236
_Traits traits_type
Definition: basic_ios.h:86
void setstate(iostate __state)
Sets additional flags in the error state.
Definition: basic_ios.h:166
basic_ios()
Empty.
Definition: basic_ios.h:475
bool operator!() const
The quick-and-easy status check.
Definition: basic_ios.h:133
basic_ios & copyfmt(const basic_ios &__rhs)
Copies fields of __rhs into this.
Definition: basic_ios.tcc:68
char_type fill(char_type __ch)
Sets a new empty character.
Definition: basic_ios.h:404
iostate rdstate() const
Returns the error state of the stream buffer.
Definition: basic_ios.h:146
void init(basic_streambuf< _CharT, _Traits > *__sb)
All setup is performed here.
Definition: basic_ios.tcc:131
bool good() const
Fast error checking.
Definition: basic_ios.h:190
char_type widen(char __c) const
Widens characters.
Definition: basic_ios.h:464
char_type fill() const
Retrieves the empty character.
Definition: basic_ios.h:387
char narrow(char_type __c, char __dfault) const
Squeezes characters.
Definition: basic_ios.h:445
virtual ~basic_ios()
Empty.
Definition: basic_ios.h:296
_Traits::off_type off_type
Definition: basic_ios.h:85
bool fail() const
Fast error checking.
Definition: basic_ios.h:213
_CharT char_type
Definition: basic_ios.h:72
_Traits::int_type int_type
Definition: basic_ios.h:83
basic_ostream< _CharT, _Traits > * tie(basic_ostream< _CharT, _Traits > *__tiestr)
Ties this stream to an output stream.
Definition: basic_ios.h:322
num_put< _CharT, ostreambuf_iterator< _CharT, _Traits > > __num_put_type
Definition: basic_ios.h:95
num_get< _CharT, istreambuf_iterator< _CharT, _Traits > > __num_get_type
Definition: basic_ios.h:97
bool bad() const
Fast error checking.
Definition: basic_ios.h:224
basic_ios(basic_streambuf< _CharT, _Traits > *__sb)
Constructor performs initialization.
Definition: basic_ios.h:284
void exceptions(iostate __except)
Throwing exceptions on errors.
Definition: basic_ios.h:271
The actual work of input and output (interface).
Definition: streambuf:127
Template class basic_ostream.
Definition: ostream.h:67
The base of the I/O class hierarchy.
Definition: ios_base.h:266
_Ios_Iostate iostate
This is a bitmask type.
Definition: ios_base.h:453
static const iostate eofbit
Indicates that an input operation reached the end of an input sequence.
Definition: ios_base.h:460
static const iostate goodbit
Indicates all is well.
Definition: ios_base.h:468
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:457
static const iostate failbit
Indicates that an input operation failed to read the expected characters, or that an output operation...
Definition: ios_base.h:465
Container class for localization functionality.
Primary class template ctype facet.
Primary class template num_get.
Primary class template num_put.