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