1 // Iostreams base classes -*- C++ -*-
3 // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
4 // 2006, 2007, 2008, 2009
5 // Free Software Foundation, Inc.
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 2, or (at your option)
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.
18 // You should have received a copy of the GNU General Public License along
19 // with this library; see the file COPYING. If not, write to the Free
20 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
23 // As a special exception, you may use this file as part of a free software
24 // library without restriction. Specifically, if other files instantiate
25 // templates or use macros or inline functions from this file, or you compile
26 // this file and link it with other files to produce an executable, this
27 // file does not by itself cause the resulting executable to be covered by
28 // the GNU General Public License. This exception does not however
29 // invalidate any other reasons why the executable file might be covered by
30 // the GNU General Public License.
33 * This is an internal header file, included by other library headers.
34 * You should not attempt to use it directly.
38 #define _BASIC_IOS_H 1
40 #pragma GCC system_header
42 #include <bits/localefwd.h>
43 #include <bits/locale_classes.h>
44 #include <bits/locale_facets.h>
45 #include <bits/streambuf_iterator.h>
47 _GLIBCXX_BEGIN_NAMESPACE(std
)
49 template<typename _Facet
>
51 __check_facet(const _Facet
* __f
)
58 // 27.4.5 Template class basic_ios
60 * @brief Virtual base class for all stream classes.
63 * Most of the member functions called dispatched on stream objects
64 * (e.g., @c std::cout.foo(bar);) are consolidated in this class.
66 template<typename _CharT
, typename _Traits
>
67 class basic_ios
: public ios_base
72 * These are standard types. They permit a standardized way of
73 * referring to names of (or names dependant on) the template
74 * parameters, which are specific to the implementation.
76 typedef _CharT char_type
;
77 typedef typename
_Traits::int_type int_type
;
78 typedef typename
_Traits::pos_type pos_type
;
79 typedef typename
_Traits::off_type off_type
;
80 typedef _Traits traits_type
;
85 * These are non-standard types.
87 typedef ctype
<_CharT
> __ctype_type
;
88 typedef num_put
<_CharT
, ostreambuf_iterator
<_CharT
, _Traits
> >
90 typedef num_get
<_CharT
, istreambuf_iterator
<_CharT
, _Traits
> >
96 basic_ostream
<_CharT
, _Traits
>* _M_tie
;
97 mutable char_type _M_fill
;
98 mutable bool _M_fill_init
;
99 basic_streambuf
<_CharT
, _Traits
>* _M_streambuf
;
101 // Cached use_facet<ctype>, which is based on the current locale info.
102 const __ctype_type
* _M_ctype
;
104 const __num_put_type
* _M_num_put
;
106 const __num_get_type
* _M_num_get
;
111 * @brief The quick-and-easy status check.
113 * This allows you to write constructs such as
114 * "if (!a_stream) ..." and "while (a_stream) ..."
116 operator void*() const
117 { return this->fail() ? 0 : const_cast<basic_ios
*>(this); }
121 { return this->fail(); }
125 * @brief Returns the error state of the stream buffer.
126 * @return A bit pattern (well, isn't everything?)
128 * See std::ios_base::iostate for the possible bit values. Most
129 * users will call one of the interpreting wrappers, e.g., good().
133 { return _M_streambuf_state
; }
136 * @brief [Re]sets the error state.
137 * @param state The new state flag(s) to set.
139 * See std::ios_base::iostate for the possible bit values. Most
140 * users will not need to pass an argument.
143 clear(iostate __state
= goodbit
);
146 * @brief Sets additional flags in the error state.
147 * @param state The additional state flag(s) to set.
149 * See std::ios_base::iostate for the possible bit values.
152 setstate(iostate __state
)
153 { this->clear(this->rdstate() | __state
); }
155 // Flip the internal state on for the proper state bits, then re
156 // throws the propagated exception if bit also set in
159 _M_setstate(iostate __state
)
161 // 27.6.1.2.1 Common requirements.
162 // Turn this on without causing an ios::failure to be thrown.
163 _M_streambuf_state
|= __state
;
164 if (this->exceptions() & __state
)
165 __throw_exception_again
;
169 * @brief Fast error checking.
170 * @return True if no error flags are set.
172 * A wrapper around rdstate.
176 { return this->rdstate() == 0; }
179 * @brief Fast error checking.
180 * @return True if the eofbit is set.
182 * Note that other iostate flags may also be set.
186 { return (this->rdstate() & eofbit
) != 0; }
189 * @brief Fast error checking.
190 * @return True if either the badbit or the failbit is set.
192 * Checking the badbit in fail() is historical practice.
193 * Note that other iostate flags may also be set.
197 { return (this->rdstate() & (badbit
| failbit
)) != 0; }
200 * @brief Fast error checking.
201 * @return True if the badbit is set.
203 * Note that other iostate flags may also be set.
207 { return (this->rdstate() & badbit
) != 0; }
210 * @brief Throwing exceptions on errors.
211 * @return The current exceptions mask.
213 * This changes nothing in the stream. See the one-argument version
214 * of exceptions(iostate) for the meaning of the return value.
218 { return _M_exception
; }
221 * @brief Throwing exceptions on errors.
222 * @param except The new exceptions mask.
224 * By default, error flags are set silently. You can set an
225 * exceptions mask for each stream; if a bit in the mask becomes set
226 * in the error flags, then an exception of type
227 * std::ios_base::failure is thrown.
229 * If the error flag is already set when the exceptions mask is
230 * added, the exception is immediately thrown. Try running the
231 * following under GCC 3.1 or later:
233 * #include <iostream>
235 * #include <exception>
239 * std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
241 * std::ifstream f ("/etc/motd");
243 * std::cerr << "Setting badbit\n";
244 * f.setstate (std::ios_base::badbit);
246 * std::cerr << "Setting exception mask\n";
247 * f.exceptions (std::ios_base::badbit);
252 exceptions(iostate __except
)
254 _M_exception
= __except
;
255 this->clear(_M_streambuf_state
);
258 // Constructor/destructor:
260 * @brief Constructor performs initialization.
262 * The parameter is passed by derived streams.
265 basic_ios(basic_streambuf
<_CharT
, _Traits
>* __sb
)
266 : ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0),
267 _M_ctype(0), _M_num_put(0), _M_num_get(0)
268 { this->init(__sb
); }
273 * The destructor does nothing. More specifically, it does not
274 * destroy the streambuf held by rdbuf().
281 * @brief Fetches the current @e tied stream.
282 * @return A pointer to the tied stream, or NULL if the stream is
285 * A stream may be @e tied (or synchronized) to a second output
286 * stream. When this stream performs any I/O, the tied stream is
287 * first flushed. For example, @c std::cin is tied to @c std::cout.
289 basic_ostream
<_CharT
, _Traits
>*
294 * @brief Ties this stream to an output stream.
295 * @param tiestr The output stream.
296 * @return The previously tied output stream, or NULL if the stream
299 * This sets up a new tie; see tie() for more.
301 basic_ostream
<_CharT
, _Traits
>*
302 tie(basic_ostream
<_CharT
, _Traits
>* __tiestr
)
304 basic_ostream
<_CharT
, _Traits
>* __old
= _M_tie
;
310 * @brief Accessing the underlying buffer.
311 * @return The current stream buffer.
313 * This does not change the state of the stream.
315 basic_streambuf
<_CharT
, _Traits
>*
317 { return _M_streambuf
; }
320 * @brief Changing the underlying buffer.
321 * @param sb The new stream buffer.
322 * @return The previous stream buffer.
324 * Associates a new buffer with the current stream, and clears the
327 * Due to historical accidents which the LWG refuses to correct, the
328 * I/O library suffers from a design error: this function is hidden
329 * in derived classes by overrides of the zero-argument @c rdbuf(),
330 * which is non-virtual for hysterical raisins. As a result, you
331 * must use explicit qualifications to access this function via any
332 * derived class. For example:
335 * std::fstream foo; // or some other derived type
336 * std::streambuf* p = .....;
338 * foo.ios::rdbuf(p); // ios == basic_ios<char>
341 basic_streambuf
<_CharT
, _Traits
>*
342 rdbuf(basic_streambuf
<_CharT
, _Traits
>* __sb
);
345 * @brief Copies fields of __rhs into this.
346 * @param __rhs The source values for the copies.
347 * @return Reference to this object.
349 * All fields of __rhs are copied into this object except that rdbuf()
350 * and rdstate() remain unchanged. All values in the pword and iword
351 * arrays are copied. Before copying, each callback is invoked with
352 * erase_event. After copying, each (new) callback is invoked with
353 * copyfmt_event. The final step is to copy exceptions().
356 copyfmt(const basic_ios
& __rhs
);
359 * @brief Retrieves the "empty" character.
360 * @return The current fill character.
362 * It defaults to a space (' ') in the current locale.
369 _M_fill
= this->widen(' ');
376 * @brief Sets a new "empty" character.
377 * @param ch The new character.
378 * @return The previous fill character.
380 * The fill character is used to fill out space when P+ characters
381 * have been requested (e.g., via setw), Q characters are actually
382 * used, and Q<P. It defaults to a space (' ') in the current locale.
387 char_type __old
= this->fill();
394 * @brief Moves to a new locale.
395 * @param loc The new locale.
396 * @return The previous locale.
398 * Calls @c ios_base::imbue(loc), and if a stream buffer is associated
399 * with this stream, calls that buffer's @c pubimbue(loc).
401 * Additional l10n notes are at
402 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
405 imbue(const locale
& __loc
);
408 * @brief Squeezes characters.
409 * @param c The character to narrow.
410 * @param dfault The character to narrow.
411 * @return The narrowed character.
413 * Maps a character of @c char_type to a character of @c char,
416 * Returns the result of
418 * std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault)
421 * Additional l10n notes are at
422 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
425 narrow(char_type __c
, char __dfault
) const
426 { return __check_facet(_M_ctype
).narrow(__c
, __dfault
); }
429 * @brief Widens characters.
430 * @param c The character to widen.
431 * @return The widened character.
433 * Maps a character of @c char to a character of @c char_type.
435 * Returns the result of
437 * std::use_facet<ctype<char_type> >(getloc()).widen(c)
440 * Additional l10n notes are at
441 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
444 widen(char __c
) const
445 { return __check_facet(_M_ctype
).widen(__c
); }
448 // 27.4.5.1 basic_ios constructors
452 * The default constructor does nothing and is not normally
453 * accessible to users.
456 : ios_base(), _M_tie(0), _M_fill(char_type()), _M_fill_init(false),
457 _M_streambuf(0), _M_ctype(0), _M_num_put(0), _M_num_get(0)
461 * @brief All setup is performed here.
463 * This is called from the public constructor. It is not virtual and
464 * cannot be redefined.
467 init(basic_streambuf
<_CharT
, _Traits
>* __sb
);
470 _M_cache_locale(const locale
& __loc
);
473 _GLIBCXX_END_NAMESPACE
475 #ifndef _GLIBCXX_EXPORT_TEMPLATE
476 #include <bits/basic_ios.tcc>
479 #endif /* _BASIC_IOS_H */