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