libstdc++: basic_ios.h Source File

libstdc++

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