1 : // Iostreams base classes -*- C++ -*-
2 :
3 : // Copyright (C) 1997, 1998, 1999, 2001, 2002, 2003, 2004
4 : // Free Software Foundation, Inc.
5 : //
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)
10 : // any later version.
11 :
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.
16 :
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,
20 : // USA.
21 :
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.
30 :
31 : /** @file basic_ios.h
32 : * This is an internal header file, included by other library headers.
33 : * You should not attempt to use it directly.
34 : */
35 :
36 : #ifndef _BASIC_IOS_H
37 : #define _BASIC_IOS_H 1
38 :
39 : #pragma GCC system_header
40 :
41 : #include <bits/streambuf_iterator.h>
42 : #include <bits/localefwd.h>
43 : #include <bits/locale_classes.h>
44 : #include <bits/locale_facets.h>
45 :
46 : namespace std
47 : {
48 : // 27.4.5 Template class basic_ios
49 : /**
50 : * @brief Virtual base class for all stream classes.
51 : *
52 : * Most of the member functions called dispatched on stream objects
53 : * (e.g., @c std::cout.foo(bar);) are consolidated in this class.
54 : */
55 : template<typename _CharT, typename _Traits>
56 : class basic_ios : public ios_base
57 : {
58 : public:
59 : //@{
60 : /**
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.
64 : */
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;
70 : //@}
71 :
72 : //@{
73 : /**
74 : * @if maint
75 : * These are non-standard types.
76 : * @endif
77 : */
78 : typedef ctype<_CharT> __ctype_type;
79 : typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> >
80 : __num_put_type;
81 : typedef num_get<_CharT, istreambuf_iterator<_CharT, _Traits> >
82 : __num_get_type;
83 : //@}
84 :
85 : // Data members:
86 : protected:
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;
91 :
92 : // Cached use_facet<ctype>, which is based on the current locale info.
93 : const __ctype_type* _M_ctype;
94 : // For ostream.
95 : const __num_put_type* _M_num_put;
96 : // For istream.
97 : const __num_get_type* _M_num_get;
98 :
99 : public:
100 : //@{
101 : /**
102 : * @brief The quick-and-easy status check.
103 : *
104 : * This allows you to write constructs such as
105 : * "if (!a_stream) ..." and "while (a_stream) ..."
106 : */
107 : operator void*() const
108 : { return this->fail() ? 0 : const_cast<basic_ios*>(this); }
109 :
110 : bool
111 : operator!() const
112 : { return this->fail(); }
113 : //@}
114 :
115 : /**
116 : * @brief Returns the error state of the stream buffer.
117 : * @return A bit pattern (well, isn't everything?)
118 : *
119 : * See std::ios_base::iostate for the possible bit values. Most
120 : * users will call one of the interpreting wrappers, e.g., good().
121 : */
122 : iostate
123 : rdstate() const
124 : { return _M_streambuf_state; }
125 :
126 : /**
127 : * @brief [Re]sets the error state.
128 : * @param state The new state flag(s) to set.
129 : *
130 : * See std::ios_base::iostate for the possible bit values. Most
131 : * users will not need to pass an argument.
132 : */
133 : void
134 : clear(iostate __state = goodbit);
135 :
136 : /**
137 : * @brief Sets additional flags in the error state.
138 : * @param state The additional state flag(s) to set.
139 : *
140 : * See std::ios_base::iostate for the possible bit values.
141 : */
142 : void
143 : setstate(iostate __state)
144 0 : { this->clear(this->rdstate() | __state); }
145 :
146 : // Flip the internal state on for the proper state bits, then re
147 : // throws the propagated exception if bit also set in
148 : // exceptions().
149 : void
150 : _M_setstate(iostate __state)
151 : {
152 : // 27.6.1.2.1 Common requirements.
153 : // Turn this on without causing an ios::failure to be thrown.
154 : _M_streambuf_state |= __state;
155 : if (this->exceptions() & __state)
156 : __throw_exception_again;
157 : }
158 :
159 : /**
160 : * @brief Fast error checking.
161 : * @return True if no error flags are set.
162 : *
163 : * A wrapper around rdstate.
164 : */
165 : bool
166 : good() const
167 : { return this->rdstate() == 0; }
168 :
169 : /**
170 : * @brief Fast error checking.
171 : * @return True if the eofbit is set.
172 : *
173 : * Note that other iostate flags may also be set.
174 : */
175 : bool
176 : eof() const
177 : { return (this->rdstate() & eofbit) != 0; }
178 :
179 : /**
180 : * @brief Fast error checking.
181 : * @return True if either the badbit or the failbit is set.
182 : *
183 : * Checking the badbit in fail() is historical practice.
184 : * Note that other iostate flags may also be set.
185 : */
186 : bool
187 : fail() const
188 : { return (this->rdstate() & (badbit | failbit)) != 0; }
189 :
190 : /**
191 : * @brief Fast error checking.
192 : * @return True if the badbit is set.
193 : *
194 : * Note that other iostate flags may also be set.
195 : */
196 : bool
197 : bad() const
198 : { return (this->rdstate() & badbit) != 0; }
199 :
200 : /**
201 : * @brief Throwing exceptions on errors.
202 : * @return The current exceptions mask.
203 : *
204 : * This changes nothing in the stream. See the one-argument version
205 : * of exceptions(iostate) for the meaning of the return value.
206 : */
207 : iostate
208 : exceptions() const
209 : { return _M_exception; }
210 :
211 : /**
212 : * @brief Throwing exceptions on errors.
213 : * @param except The new exceptions mask.
214 : *
215 : * By default, error flags are set silently. You can set an
216 : * exceptions mask for each stream; if a bit in the mask becomes set
217 : * in the error flags, then an exception of type
218 : * std::ios_base::failure is thrown.
219 : *
220 : * If the error flage is already set when the exceptions mask is
221 : * added, the exception is immediately thrown. Try running the
222 : * following under GCC 3.1 or later:
223 : * @code
224 : * #include <iostream>
225 : * #include <fstream>
226 : * #include <exception>
227 : *
228 : * int main()
229 : * {
230 : * std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
231 : *
232 : * std::ifstream f ("/etc/motd");
233 : *
234 : * std::cerr << "Setting badbit\n";
235 : * f.setstate (std::ios_base::badbit);
236 : *
237 : * std::cerr << "Setting exception mask\n";
238 : * f.exceptions (std::ios_base::badbit);
239 : * }
240 : * @endcode
241 : */
242 : void
243 : exceptions(iostate __except)
244 : {
245 : _M_exception = __except;
246 : this->clear(_M_streambuf_state);
247 : }
248 :
249 : // Constructor/destructor:
250 : /**
251 : * @brief Constructor performs initialization.
252 : *
253 : * The parameter is passed by derived streams.
254 : */
255 : explicit
256 : basic_ios(basic_streambuf<_CharT, _Traits>* __sb)
257 : : ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0),
258 : _M_ctype(0), _M_num_put(0), _M_num_get(0)
259 : { this->init(__sb); }
260 :
261 : /**
262 : * @brief Empty.
263 : *
264 : * The destructor does nothing. More specifically, it does not
265 : * destroy the streambuf held by rdbuf().
266 : */
267 : virtual
268 37 : ~basic_ios() { }
269 :
270 : // Members:
271 : /**
272 : * @brief Fetches the current @e tied stream.
273 : * @return A pointer to the tied stream, or NULL if the stream is
274 : * not tied.
275 : *
276 : * A stream may be @e tied (or synchronized) to a second output
277 : * stream. When this stream performs any I/O, the tied stream is
278 : * first flushed. For example, @c std::cin is tied to @c std::cout.
279 : */
280 : basic_ostream<_CharT, _Traits>*
281 : tie() const
282 : { return _M_tie; }
283 :
284 : /**
285 : * @brief Ties this stream to an output stream.
286 : * @param tiestr The output stream.
287 : * @return The previously tied output stream, or NULL if the stream
288 : * was not tied.
289 : *
290 : * This sets up a new tie; see tie() for more.
291 : */
292 : basic_ostream<_CharT, _Traits>*
293 : tie(basic_ostream<_CharT, _Traits>* __tiestr)
294 : {
295 : basic_ostream<_CharT, _Traits>* __old = _M_tie;
296 : _M_tie = __tiestr;
297 : return __old;
298 : }
299 :
300 : /**
301 : * @brief Accessing the underlying buffer.
302 : * @return The current stream buffer.
303 : *
304 : * This does not change the state of the stream.
305 : */
306 : basic_streambuf<_CharT, _Traits>*
307 : rdbuf() const
308 : { return _M_streambuf; }
309 :
310 : /**
311 : * @brief Changing the underlying buffer.
312 : * @param sb The new stream buffer.
313 : * @return The previous stream buffer.
314 : *
315 : * Associates a new buffer with the current stream, and clears the
316 : * error state.
317 : *
318 : * Due to historical accidents which the LWG refuses to correct, the
319 : * I/O library suffers from a design error: this function is hidden
320 : * in derived classes by overrides of the zero-argument @c rdbuf(),
321 : * which is non-virtual for hysterical raisins. As a result, you
322 : * must use explicit qualifications to access this function via any
323 : * derived class. For example:
324 : *
325 : * @code
326 : * std::fstream foo; // or some other derived type
327 : * std::streambuf* p = .....;
328 : *
329 : * foo.ios::rdbuf(p); // ios == basic_ios<char>
330 : * @endcode
331 : */
332 : basic_streambuf<_CharT, _Traits>*
333 : rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
334 :
335 : /**
336 : * @brief Copies fields of __rhs into this.
337 : * @param __rhs The source values for the copies.
338 : * @return Reference to this object.
339 : *
340 : * All fields of __rhs are copied into this object except that rdbuf()
341 : * and rdstate() remain unchanged. All values in the pword and iword
342 : * arrays are copied. Before copying, each callback is invoked with
343 : * erase_event. After copying, each (new) callback is invoked with
344 : * copyfmt_event. The final step is to copy exceptions().
345 : */
346 : basic_ios&
347 : copyfmt(const basic_ios& __rhs);
348 :
349 : /**
350 : * @brief Retreives the "empty" character.
351 : * @return The current fill character.
352 : *
353 : * It defaults to a space (' ') in the current locale.
354 : */
355 : char_type
356 : fill() const
357 : {
358 : if (!_M_fill_init)
359 : {
360 : _M_fill = this->widen(' ');
361 : _M_fill_init = true;
362 : }
363 : return _M_fill;
364 : }
365 :
366 : /**
367 : * @brief Sets a new "empty" character.
368 : * @param ch The new character.
369 : * @return The previous fill character.
370 : *
371 : * The fill character is used to fill out space when P+ characters
372 : * have been requested (e.g., via setw), Q characters are actually
373 : * used, and Q<P. It defaults to a space (' ') in the current locale.
374 : */
375 : char_type
376 : fill(char_type __ch)
377 : {
378 : char_type __old = this->fill();
379 : _M_fill = __ch;
380 : return __old;
381 : }
382 :
383 : // Locales:
384 : /**
385 : * @brief Moves to a new locale.
386 : * @param loc The new locale.
387 : * @return The previous locale.
388 : *
389 : * Calls @c ios_base::imbue(loc), and if a stream buffer is associated
390 : * with this stream, calls that buffer's @c pubimbue(loc).
391 : *
392 : * Additional l10n notes are at
393 : * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
394 : */
395 : locale
396 : imbue(const locale& __loc);
397 :
398 : /**
399 : * @brief Squeezes characters.
400 : * @param c The character to narrow.
401 : * @param dfault The character to narrow.
402 : * @return The narrowed character.
403 : *
404 : * Maps a character of @c char_type to a character of @c char,
405 : * if possible.
406 : *
407 : * Returns the result of
408 : * @code
409 : * std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault)
410 : * @endcode
411 : *
412 : * Additional l10n notes are at
413 : * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
414 : */
415 : char
416 : narrow(char_type __c, char __dfault) const;
417 :
418 : /**
419 : * @brief Widens characters.
420 : * @param c The character to widen.
421 : * @return The widened character.
422 : *
423 : * Maps a character of @c char to a character of @c char_type.
424 : *
425 : * Returns the result of
426 : * @code
427 : * std::use_facet<ctype<char_type> >(getloc()).widen(c)
428 : * @endcode
429 : *
430 : * Additional l10n notes are at
431 : * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
432 : */
433 : char_type
434 : widen(char __c) const;
435 :
436 : protected:
437 : // 27.4.5.1 basic_ios constructors
438 : /**
439 : * @brief Empty.
440 : *
441 : * The default constructor does nothing and is not normally
442 : * accessible to users.
443 : */
444 : basic_ios()
445 : : ios_base(), _M_tie(0), _M_fill(char_type()), _M_fill_init(false),
446 233 : _M_streambuf(0), _M_ctype(0), _M_num_put(0), _M_num_get(0)
447 : { }
448 :
449 : /**
450 : * @brief All setup is performed here.
451 : *
452 : * This is called from the public constructor. It is not virtual and
453 : * cannot be redefined.
454 : */
455 : void
456 : init(basic_streambuf<_CharT, _Traits>* __sb);
457 :
458 : void
459 : _M_cache_locale(const locale& __loc);
460 : };
461 : } // namespace std
462 :
463 : #ifndef _GLIBCXX_EXPORT_TEMPLATE
464 : #include <bits/basic_ios.tcc>
465 : #endif
466 :
467 : #endif /* _BASIC_IOS_H */
|
