]>
git.ipfire.org Git - thirdparty/gcc.git/blob - libstdc++-v3/include/bits/basic_ios.h
1 // Iostreams base classes -*- C++ -*-
3 // Copyright (C) 1997, 1998, 1999, 2001, 2002, 2003
4 // Free Software Foundation, Inc.
6 // This file is part of the GNU ISO C++ Library. This library is free
7 // software; you can redistribute it and/or modify it under the
8 // terms of the GNU General Public License as published by the
9 // Free Software Foundation; either version 2, or (at your option)
12 // This library is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 // GNU General Public License for more details.
17 // You should have received a copy of the GNU General Public License along
18 // with this library; see the file COPYING. If not, write to the Free
19 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
22 // As a special exception, you may use this file as part of a free software
23 // library without restriction. Specifically, if other files instantiate
24 // templates or use macros or inline functions from this file, or you compile
25 // this file and link it with other files to produce an executable, this
26 // file does not by itself cause the resulting executable to be covered by
27 // the GNU General Public License. This exception does not however
28 // invalidate any other reasons why the executable file might be covered by
29 // the GNU General Public License.
32 * This is an internal header file, included by other library headers.
33 * You should not attempt to use it directly.
36 #ifndef _CPP_BITS_BASICIOS_H
37 #define _CPP_BITS_BASICIOS_H 1
39 #pragma GCC system_header
41 #include <bits/streambuf_iterator.h>
42 #include <bits/localefwd.h>
43 #include <bits/locale_classes.h>
44 #include <bits/locale_facets.h>
48 // 27.4.5 Template class basic_ios
50 * @brief Virtual base class for all stream classes.
52 * Most of the member functions called dispatched on stream objects
53 * (e.g., @c std::cout.foo(bar);) are consolidated in this class.
55 template<typename _CharT
, typename _Traits
>
56 class basic_ios
: public ios_base
61 * These are standard types. They permit a standardized way of
62 * referring to names of (or names dependant on) the template
63 * parameters, which are specific to the implementation.
65 typedef _CharT char_type
;
66 typedef typename
_Traits::int_type int_type
;
67 typedef typename
_Traits::pos_type pos_type
;
68 typedef typename
_Traits::off_type off_type
;
69 typedef _Traits traits_type
;
75 * These are non-standard types.
78 typedef ctype
<_CharT
> __ctype_type
;
79 typedef ostreambuf_iterator
<_CharT
, _Traits
> __ostreambuf_iter
;
80 typedef num_put
<_CharT
, __ostreambuf_iter
> __numput_type
;
81 typedef istreambuf_iterator
<_CharT
, _Traits
> __istreambuf_iter
;
82 typedef num_get
<_CharT
, __istreambuf_iter
> __numget_type
;
87 basic_ostream
<_CharT
, _Traits
>* _M_tie
;
88 mutable char_type _M_fill
;
89 mutable bool _M_fill_init
;
90 basic_streambuf
<_CharT
, _Traits
>* _M_streambuf
;
92 // Cached use_facet<ctype>, which is based on the current locale info.
93 const __ctype_type
* _M_ctype
;
95 const __numput_type
* _M_num_put
;
97 const __numget_type
* _M_num_get
;
102 * @brief The quick-and-easy status check.
104 * This allows you to write constructs such as
105 * "if (!a_stream) ..." and "while (a_stream) ..."
107 operator void*() const
108 { return this->fail() ? 0 : const_cast<basic_ios
*>(this); }
112 { return this->fail(); }
116 * @brief Returns the error state of the stream buffer.
117 * @return A bit pattern (well, isn't everything?)
119 * See std::ios_base::iostate for the possible bit values. Most
120 * users will call one of the interpreting wrappers, e.g., good().
124 { return _M_streambuf_state
; }
127 * @brief [Re]sets the error state.
128 * @param state The new state flag(s) to set.
130 * See std::ios_base::iostate for the possible bit values. Most
131 * users will not need to pass an argument.
134 clear(iostate __state
= goodbit
);
137 * @brief Sets additional flags in the error state.
138 * @param state The additional state flag(s) to set.
140 * See std::ios_base::iostate for the possible bit values.
143 setstate(iostate __state
)
144 { this->clear(this->rdstate() | __state
); }
147 * @brief Fast error checking.
148 * @return True if no error flags are set.
150 * A wrapper around rdstate.
154 { return this->rdstate() == 0; }
157 * @brief Fast error checking.
158 * @return True if the eofbit is set.
160 * Note that other iostate flags may also be set.
164 { return (this->rdstate() & eofbit
) != 0; }
167 * @brief Fast error checking.
168 * @return True if either the badbit or the failbit is set.
170 * Checking the badbit in fail() is historical practice.
171 * Note that other iostate flags may also be set.
175 { return (this->rdstate() & (badbit
| failbit
)) != 0; }
178 * @brief Fast error checking.
179 * @return True if the badbit is set.
181 * Note that other iostate flags may also be set.
185 { return (this->rdstate() & badbit
) != 0; }
188 * @brief Throwing exceptions on errors.
189 * @return The current exceptions mask.
191 * This changes nothing in the stream. See the one-argument version
192 * of exceptions(iostate) for the meaning of the return value.
196 { return _M_exception
; }
199 * @brief Throwing exceptions on errors.
200 * @param except The new exceptions mask.
202 * By default, error flags are set silently. You can set an
203 * exceptions mask for each stream; if a bit in the mask becomes set
204 * in the error flags, then an exception of type
205 * std::ios_base::failure is thrown.
207 * If the error flage is already set when the exceptions mask is
208 * added, the exception is immediately thrown. Try running the
209 * following under GCC 3.1 or later:
211 * #include <iostream>
213 * #include <exception>
217 * std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
219 * std::ifstream f ("/etc/motd");
221 * std::cerr << "Setting badbit\n";
222 * f.setstate (std::ios_base::badbit);
224 * std::cerr << "Setting exception mask\n";
225 * f.exceptions (std::ios_base::badbit);
230 exceptions(iostate __except
)
232 _M_exception
= __except
;
233 this->clear(_M_streambuf_state
);
236 // Constructor/destructor:
238 * @brief Constructor performs initialization.
240 * The parameter is passed by derived streams.
243 basic_ios(basic_streambuf
<_CharT
, _Traits
>* __sb
)
244 : ios_base(), _M_ctype(0), _M_num_put(0), _M_num_get(0)
245 { this->init(__sb
); }
250 * The destructor does nothing. More specifically, it does not
251 * destroy the streambuf held by rdbuf().
258 * @brief Fetches the current @e tied stream.
259 * @return A pointer to the tied stream, or NULL if the stream is
262 * A stream may be @e tied (or synchronized) to a second output
263 * stream. When this stream performs any I/O, the tied stream is
264 * first flushed. For example, @c std::cin is tied to @c std::cout.
266 basic_ostream
<_CharT
, _Traits
>*
271 * @brief Ties this stream to an output stream.
272 * @param tiestr The output stream.
273 * @return The previously tied output stream, or NULL if the stream
276 * This sets up a new tie; see tie() for more.
278 basic_ostream
<_CharT
, _Traits
>*
279 tie(basic_ostream
<_CharT
, _Traits
>* __tiestr
)
281 basic_ostream
<_CharT
, _Traits
>* __old
= _M_tie
;
287 * @brief Accessing the underlying buffer.
288 * @return The current stream buffer.
290 * This does not change the state of the stream.
292 basic_streambuf
<_CharT
, _Traits
>*
294 { return _M_streambuf
; }
297 * @brief Changing the underlying buffer.
298 * @param sb The new stream buffer.
299 * @return The previous stream buffer.
301 * Associates a new buffer with the current stream, and clears the
304 * Due to historical accidents which the LWG refuses to correct, the
305 * I/O library suffers from a design error: this function is hidden
306 * in derived classes by overrides of the zero-argument @c rdbuf(),
307 * which is non-virtual for hysterical raisins. As a result, you
308 * must use explicit qualifications to access this function via any
309 * derived class. For example:
312 * std::fstream foo; // or some other derived type
313 * std::streambuf* p = .....;
315 * foo.ios::rdbuf(p); // ios == basic_ios<char>
318 basic_streambuf
<_CharT
, _Traits
>*
319 rdbuf(basic_streambuf
<_CharT
, _Traits
>* __sb
);
325 copyfmt(const basic_ios
& __rhs
);
328 * @brief Retreives the "empty" character.
329 * @return The current fill character.
331 * It defaults to a space (' ') in the current locale.
338 _M_fill
= this->widen(' ');
345 * @brief Sets a new "empty" character.
346 * @param ch The new character.
347 * @return The previous fill character.
349 * The fill character is used to fill out space when P+ characters
350 * have been requested (e.g., via setw), Q characters are actually
351 * used, and Q<P. It defaults to a space (' ') in the current locale.
356 char_type __old
= this->fill();
363 * @brief Moves to a new locale.
364 * @param loc The new locale.
365 * @return The previous locale.
367 * Calls @c ios_base::imbue(loc), and if a stream buffer is associated
368 * with this stream, calls that buffer's @c pubimbue(loc).
370 * Additional l10n notes are at
371 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
374 imbue(const locale
& __loc
);
377 * @brief Squeezes characters.
378 * @param c The character to narrow.
379 * @param dfault The character to narrow.
380 * @return The narrowed character.
382 * Maps a character of @c char_type to a character of @c char,
385 * Returns the result of
387 * std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault)
390 * Additional l10n notes are at
391 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
394 narrow(char_type __c
, char __dfault
) const;
397 * @brief Widens characters.
398 * @param c The character to widen.
399 * @return The widened character.
401 * Maps a character of @c char to a character of @c char_type.
403 * Returns the result of
405 * std::use_facet<ctype<char_type> >(getloc()).widen(c)
408 * Additional l10n notes are at
409 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
412 widen(char __c
) const;
415 // 27.4.5.1 basic_ios constructors
419 * The default constructor does nothing and is not normally
420 * accessible to users.
422 basic_ios() : ios_base(), _M_ctype(0), _M_num_put(0), _M_num_get(0)
426 * @brief All setup is performed here.
428 * This is called from the public constructor. It is not virtual and
429 * cannot be redefined.
432 init(basic_streambuf
<_CharT
, _Traits
>* __sb
);
435 _M_cache_locale(const locale
& __loc
);
437 // Internal state setter that won't throw, only set the state bits.
438 // Used to guarantee we don't throw when setting badbit.
440 _M_setstate(iostate __state
) { _M_streambuf_state
|= __state
; }
444 #ifdef _GLIBCPP_NO_TEMPLATE_EXPORT
446 #include <bits/basic_ios.tcc>
449 #endif /* _CPP_BITS_BASICIOS_H */