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