1// Iostreams base classes -*- C++ -*-
2
3// Copyright (C) 1997-2020 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
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    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      // Flip the internal state on for the proper state bits, then
161      // rethrows the propagated exception if bit also set in
162      // exceptions().
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 */
519