1 | // Iostreams base classes -*- C++ -*- |
2 | |
3 | // Copyright (C) 1997-2014 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 | |