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