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