TODO: Note change in clause 27 docs.
[official-gcc.git] / libstdc++-v3 / include / bits / basic_ios.h
blobb6ef89ba8b0938641cf978bf2c8582e5f924b32a
1 // Iostreams base classes -*- C++ -*-
3 // Copyright (C) 1997, 1998, 1999, 2001, 2002 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 2, or (at your option)
9 // any later version.
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.
16 // You should have received a copy of the GNU General Public License along
17 // with this library; see the file COPYING. If not, write to the Free
18 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
19 // USA.
21 // As a special exception, you may use this file as part of a free software
22 // library without restriction. Specifically, if other files instantiate
23 // templates or use macros or inline functions from this file, or you compile
24 // this file and link it with other files to produce an executable, this
25 // file does not by itself cause the resulting executable to be covered by
26 // the GNU General Public License. This exception does not however
27 // invalidate any other reasons why the executable file might be covered by
28 // the GNU General Public License.
30 /** @file basic_ios.h
31 * This is an internal header file, included by other library headers.
32 * You should not attempt to use it directly.
35 #ifndef _CPP_BITS_BASICIOS_H
36 #define _CPP_BITS_BASICIOS_H 1
38 #pragma GCC system_header
40 #include <bits/streambuf_iterator.h>
41 #include <bits/locale_facets.h>
43 namespace std
45 // 27.4.5 Template class basic_ios
46 /**
47 * @brief Virtual base class for all stream classes.
49 * Most of the member functions called dispatched on stream objects
50 * (e.g., @c std::cout.foo(bar);) are consolidated in this class.
52 template<typename _CharT, typename _Traits>
53 class basic_ios : public ios_base
55 public:
56 //@{
57 /**
58 * These are standard types. They permit a standardized way of
59 * referring to names of (or names dependant on) the template
60 * parameters, which are specific to the implementation.
62 typedef _CharT char_type;
63 typedef typename _Traits::int_type int_type;
64 typedef typename _Traits::pos_type pos_type;
65 typedef typename _Traits::off_type off_type;
66 typedef _Traits traits_type;
67 //@}
69 //@{
70 /**
71 * @if maint
72 * These are non-standard types.
73 * @endif
75 typedef ctype<_CharT> __ctype_type;
76 typedef ostreambuf_iterator<_CharT, _Traits> __ostreambuf_iter;
77 typedef num_put<_CharT, __ostreambuf_iter> __numput_type;
78 typedef istreambuf_iterator<_CharT, _Traits> __istreambuf_iter;
79 typedef num_get<_CharT, __istreambuf_iter> __numget_type;
80 //@}
82 // Data members:
83 protected:
84 basic_ostream<_CharT, _Traits>* _M_tie;
85 mutable char_type _M_fill;
86 mutable bool _M_fill_init;
87 basic_streambuf<_CharT, _Traits>* _M_streambuf;
89 // Cached use_facet<ctype>, which is based on the current locale info.
90 const __ctype_type* _M_fctype;
91 // From ostream.
92 const __numput_type* _M_fnumput;
93 // From istream.
94 const __numget_type* _M_fnumget;
96 public:
97 //@{
98 /**
99 * @brief The quick-and-easy status check.
101 * This allows you to write constructs such as
102 * "if (!a_stream) ..." and "while (a_stream) ..."
104 operator void*() const
105 { return this->fail() ? 0 : const_cast<basic_ios*>(this); }
107 bool
108 operator!() const
109 { return this->fail(); }
110 //@}
113 * @brief Returns the error state of the stream buffer.
114 * @return A bit pattern (well, isn't everything?)
116 * See std::ios_base::iostate for the possible bit values. Most
117 * users will call one of the interpreting wrappers, e.g., good().
119 iostate
120 rdstate() const
121 { return _M_streambuf_state; }
124 * @brief [Re]sets the error state.
125 * @param state The new state flag(s) to set.
127 * See std::ios_base::iostate for the possible bit values. Most
128 * users will not need to pass an argument.
130 void
131 clear(iostate __state = goodbit);
134 * @brief Sets additional flags in the error state.
135 * @param state The additional state flag(s) to set.
137 * See std::ios_base::iostate for the possible bit values.
139 void
140 setstate(iostate __state)
141 { this->clear(this->rdstate() | __state); }
144 * @brief Fast error checking.
145 * @return True if no error flags are set.
147 * A wrapper around rdstate.
149 bool
150 good() const
151 { return this->rdstate() == 0; }
154 * @brief Fast error checking.
155 * @return True if the eofbit is set.
157 * Note that other iostate flags may also be set.
159 bool
160 eof() const
161 { return (this->rdstate() & eofbit) != 0; }
164 * @brief Fast error checking.
165 * @return True if either the badbit or the failbit is set.
167 * Checking the badbit in fail() is historical practice.
168 * Note that other iostate flags may also be set.
170 bool
171 fail() const
172 { return (this->rdstate() & (badbit | failbit)) != 0; }
175 * @brief Fast error checking.
176 * @return True if the badbit is set.
178 * Note that other iostate flags may also be set.
180 bool
181 bad() const
182 { return (this->rdstate() & badbit) != 0; }
185 * @brief Throwing exceptions on errors.
186 * @return The current exceptions mask.
188 * This changes nothing in the stream. See the one-argument version
189 * of exceptions(iostate) for the meaning of the return value.
191 iostate
192 exceptions() const
193 { return _M_exception; }
196 * @brief Throwing exceptions on errors.
197 * @param except The new exceptions mask.
199 * By default, error flags are set silently. You can set an
200 * exceptions mask for each stream; if a bit in the mask becomes set
201 * in the error flags, then an exception of type
202 * std::ios_base::failure is thrown.
204 * If the error flage is already set when the exceptions mask is
205 * added, the exception is immediately thrown. Try running the
206 * following under GCC 3.1 or later:
207 * @code
208 * #include <iostream>
209 * #include <fstream>
210 * #include <exception>
212 * int main()
214 * std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
216 * std::ifstream f ("/etc/motd");
218 * std::cerr << "Setting badbit\n";
219 * f.setstate (std::ios_base::badbit);
221 * std::cerr << "Setting exception mask\n";
222 * f.exceptions (std::ios_base::badbit);
224 * @endcode
226 void
227 exceptions(iostate __except)
229 _M_exception = __except;
230 this->clear(_M_streambuf_state);
233 // Constructor/destructor:
235 * @brief Constructor performs initialization.
237 * The parameter is passed by derived streams.
239 explicit
240 basic_ios(basic_streambuf<_CharT, _Traits>* __sb) : ios_base()
241 { this->init(__sb); }
244 * @brief Empty.
246 * The destructor does nothing. More specifically, it does not
247 * destroy the streambuf held by rdbuf().
249 virtual
250 ~basic_ios() { }
252 // Members:
254 * @brief Fetches the current @e tied stream.
255 * @return A pointer to the tied stream, or NULL if the stream is
256 * not tied.
258 * A stream may be @e tied (or synchronized) to a second output
259 * stream. When this stream performs any I/O, the tied stream is
260 * first flushed. For example, @c std::cin is tied to @c std::cout.
262 basic_ostream<_CharT, _Traits>*
263 tie() const
264 { return _M_tie; }
267 * @brief Ties this stream to an output stream.
268 * @param tiestr The output stream.
269 * @return The previously tied output stream, or NULL if the stream
270 * was not tied.
272 * This sets up a new tie; see tie() for more.
274 basic_ostream<_CharT, _Traits>*
275 tie(basic_ostream<_CharT, _Traits>* __tiestr)
277 basic_ostream<_CharT, _Traits>* __old = _M_tie;
278 _M_tie = __tiestr;
279 return __old;
283 * @brief Accessing the underlying buffer.
284 * @return The current stream buffer.
286 * This does not change the state of the stream.
288 basic_streambuf<_CharT, _Traits>*
289 rdbuf() const
290 { return _M_streambuf; }
293 * @brief Changing the underlying buffer.
294 * @param sb The new stream buffer.
295 * @return The previous stream buffer.
297 * Associates a new buffer with the current stream, and clears the
298 * error state.
300 * Due to historical accidents which the LWG refuses to correct, the
301 * I/O library suffers from a design error: this function is hidden
302 * in derived classes by overrides of the zero-argument @c rdbuf(),
303 * which is non-virtual for hysterical raisins. As a result, you
304 * must use explicit qualifications to access this function via any
305 * derived class.
307 basic_streambuf<_CharT, _Traits>*
308 rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
311 * @doctodo
313 basic_ios&
314 copyfmt(const basic_ios& __rhs);
317 * @brief Retreives the "empty" character.
318 * @return The current fill character.
320 * It defaults to a space (' ') in the current locale.
322 char_type
323 fill() const
325 if (!_M_fill_init)
327 _M_fill = this->widen(' ');
328 _M_fill_init = true;
330 return _M_fill;
334 * @brief Sets a new "empty" character.
335 * @param ch The new character.
336 * @return The previous fill character.
338 * The fill character is used to fill out space when P+ characters
339 * have been requested (e.g., via setw), Q characters are actually
340 * used, and Q<P. It defaults to a space (' ') in the current locale.
342 char_type
343 fill(char_type __ch)
345 char_type __old = this->fill();
346 _M_fill = __ch;
347 return __old;
350 // Locales:
352 * @brief Moves to a new locale.
353 * @param loc The new locale.
354 * @return The previous locale.
356 * Calls @c ios_base::imbue(loc), and if a stream buffer is associated
357 * with this stream, calls that buffer's @c pubimbue(loc).
359 * Additional l10n notes are at
360 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
362 locale
363 imbue(const locale& __loc);
366 * @brief Squeezes characters.
367 * @param c The character to narrow.
368 * @param dfault The character to narrow.
369 * @return The narrowed character.
371 * Maps a character of @c char_type to a character of @c char,
372 * if possible.
374 * Returns the result of
375 * @code
376 * std::use_facet< ctype<char_type> >(getloc()).narrow(c,dfault)
377 * @endcode
379 * Additional l10n notes are at
380 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
382 char
383 narrow(char_type __c, char __dfault) const;
386 * @brief Widens characters.
387 * @param c The character to widen.
388 * @return The widened character.
390 * Maps a character of @c char to a character of @c char_type.
392 * Returns the result of
393 * @code
394 * std::use_facet< ctype<char_type> >(getloc()).widen(c)
395 * @endcode
397 * Additional l10n notes are at
398 * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
400 char_type
401 widen(char __c) const;
403 protected:
404 // 27.4.5.1 basic_ios constructors
406 * @brief Empty.
408 * The default constructor does nothing and is not normally
409 * accessible to users.
411 basic_ios() : ios_base()
415 * @brief All setup is performed here.
417 * This is called from the public constructor. It is not virtual and
418 * cannot be redefined.
420 void
421 init(basic_streambuf<_CharT, _Traits>* __sb);
423 bool
424 _M_check_facet(const locale::facet* __f) const
426 if (!__f)
427 __throw_bad_cast();
428 return true;
431 void
432 _M_cache_facets(const locale& __loc);
434 } // namespace std
436 #ifdef _GLIBCPP_NO_TEMPLATE_EXPORT
437 # define export
438 #include <bits/basic_ios.tcc>
439 #endif
441 #endif /* _CPP_BITS_BASICIOS_H */