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
40 namespace 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