167754Smsmith// Iostreams base classes -*- C++ -*- 267754Smsmith 367754Smsmith// Copyright (C) 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005 467754Smsmith// Free Software Foundation, Inc. 567754Smsmith// 667754Smsmith// This file is part of the GNU ISO C++ Library. This library is free 767754Smsmith// software; you can redistribute it and/or modify it under the 8217365Sjkim// terms of the GNU General Public License as published by the 9229989Sjkim// Free Software Foundation; either version 2, or (at your option) 1070243Smsmith// any later version. 1167754Smsmith 12217365Sjkim// This library is distributed in the hope that it will be useful, 13217365Sjkim// but WITHOUT ANY WARRANTY; without even the implied warranty of 14217365Sjkim// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15217365Sjkim// GNU General Public License for more details. 16217365Sjkim 17217365Sjkim// You should have received a copy of the GNU General Public License along 18217365Sjkim// with this library; see the file COPYING. If not, write to the Free 19217365Sjkim// Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 20217365Sjkim// USA. 21217365Sjkim 22217365Sjkim// As a special exception, you may use this file as part of a free software 23217365Sjkim// library without restriction. Specifically, if other files instantiate 24217365Sjkim// templates or use macros or inline functions from this file, or you compile 25217365Sjkim// this file and link it with other files to produce an executable, this 2667754Smsmith// file does not by itself cause the resulting executable to be covered by 27217365Sjkim// the GNU General Public License. This exception does not however 28217365Sjkim// invalidate any other reasons why the executable file might be covered by 29217365Sjkim// the GNU General Public License. 3067754Smsmith 31217365Sjkim/** @file basic_ios.h 32217365Sjkim * This is an internal header file, included by other library headers. 33217365Sjkim * You should not attempt to use it directly. 34217365Sjkim */ 35217365Sjkim 36217365Sjkim#ifndef _BASIC_IOS_H 37217365Sjkim#define _BASIC_IOS_H 1 38217365Sjkim 39217365Sjkim#pragma GCC system_header 40217365Sjkim 41217365Sjkim#include <bits/streambuf_iterator.h> 42217365Sjkim#include <bits/localefwd.h> 43217365Sjkim#include <bits/locale_classes.h> 4467754Smsmith#include <bits/locale_facets.h> 4567754Smsmith 4667754Smsmith_GLIBCXX_BEGIN_NAMESPACE(std) 4767754Smsmith 48193341Sjkim // 27.4.5 Template class basic_ios 49193341Sjkim /** 50193341Sjkim * @brief Virtual base class for all stream classes. 5167754Smsmith * 5267754Smsmith * Most of the member functions called dispatched on stream objects 5377424Smsmith * (e.g., @c std::cout.foo(bar);) are consolidated in this class. 5491116Smsmith */ 5567754Smsmith template<typename _CharT, typename _Traits> 5667754Smsmith class basic_ios : public ios_base 5767754Smsmith { 5867754Smsmith public: 5967754Smsmith //@{ 6067754Smsmith /** 61151937Sjkim * These are standard types. They permit a standardized way of 6267754Smsmith * referring to names of (or names dependant on) the template 6367754Smsmith * parameters, which are specific to the implementation. 6467754Smsmith */ 6567754Smsmith typedef _CharT char_type; 6667754Smsmith typedef typename _Traits::int_type int_type; 6767754Smsmith typedef typename _Traits::pos_type pos_type; 6867754Smsmith typedef typename _Traits::off_type off_type; 6967754Smsmith typedef _Traits traits_type; 7067754Smsmith //@} 7167754Smsmith 7267754Smsmith //@{ 7367754Smsmith /** 7467754Smsmith * @if maint 7591116Smsmith * These are non-standard types. 7667754Smsmith * @endif 7767754Smsmith */ 7867754Smsmith typedef ctype<_CharT> __ctype_type; 7967754Smsmith typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> > 8067754Smsmith __num_put_type; 8167754Smsmith typedef num_get<_CharT, istreambuf_iterator<_CharT, _Traits> > 8267754Smsmith __num_get_type; 8367754Smsmith //@} 8467754Smsmith 8567754Smsmith // Data members: 8667754Smsmith protected: 8767754Smsmith basic_ostream<_CharT, _Traits>* _M_tie; 8867754Smsmith mutable char_type _M_fill; 8967754Smsmith mutable bool _M_fill_init; 9067754Smsmith basic_streambuf<_CharT, _Traits>* _M_streambuf; 9167754Smsmith 9267754Smsmith // Cached use_facet<ctype>, which is based on the current locale info. 9367754Smsmith const __ctype_type* _M_ctype; 9467754Smsmith // For ostream. 9591116Smsmith const __num_put_type* _M_num_put; 9691116Smsmith // For istream. 9791116Smsmith const __num_get_type* _M_num_get; 9891116Smsmith 9991116Smsmith public: 10067754Smsmith //@{ 10167754Smsmith /** 10267754Smsmith * @brief The quick-and-easy status check. 103200553Sjkim * 10467754Smsmith * This allows you to write constructs such as 10567754Smsmith * "if (!a_stream) ..." and "while (a_stream) ..." 10691116Smsmith */ 10767754Smsmith operator void*() const 10867754Smsmith { return this->fail() ? 0 : const_cast<basic_ios*>(this); } 10967754Smsmith 11067754Smsmith bool 11167754Smsmith operator!() const 11267754Smsmith { return this->fail(); } 11391116Smsmith //@} 11491116Smsmith 11567754Smsmith /** 11667754Smsmith * @brief Returns the error state of the stream buffer. 117167802Sjkim * @return A bit pattern (well, isn't everything?) 11867754Smsmith * 119167802Sjkim * See std::ios_base::iostate for the possible bit values. Most 12067754Smsmith * users will call one of the interpreting wrappers, e.g., good(). 12167754Smsmith */ 12267754Smsmith iostate 12367754Smsmith rdstate() const 12467754Smsmith { return _M_streambuf_state; } 12567754Smsmith 12667754Smsmith /** 12767754Smsmith * @brief [Re]sets the error state. 12867754Smsmith * @param state The new state flag(s) to set. 12967754Smsmith * 13067754Smsmith * See std::ios_base::iostate for the possible bit values. Most 13167754Smsmith * users will not need to pass an argument. 13267754Smsmith */ 13367754Smsmith void 13467754Smsmith clear(iostate __state = goodbit); 13567754Smsmith 13667754Smsmith /** 13767754Smsmith * @brief Sets additional flags in the error state. 13867754Smsmith * @param state The additional state flag(s) to set. 13967754Smsmith * 140193267Sjkim * See std::ios_base::iostate for the possible bit values. 14191116Smsmith */ 14267754Smsmith void 14367754Smsmith setstate(iostate __state) 14467754Smsmith { this->clear(this->rdstate() | __state); } 14567754Smsmith 14667754Smsmith // Flip the internal state on for the proper state bits, then re 14767754Smsmith // throws the propagated exception if bit also set in 14867754Smsmith // exceptions(). 14967754Smsmith void 15067754Smsmith _M_setstate(iostate __state) 15167754Smsmith { 15267754Smsmith // 27.6.1.2.1 Common requirements. 15367754Smsmith // Turn this on without causing an ios::failure to be thrown. 15467754Smsmith _M_streambuf_state |= __state; 15567754Smsmith if (this->exceptions() & __state) 15691116Smsmith __throw_exception_again; 15791116Smsmith } 15891116Smsmith 15991116Smsmith /** 16091116Smsmith * @brief Fast error checking. 16167754Smsmith * @return True if no error flags are set. 16267754Smsmith * 16367754Smsmith * A wrapper around rdstate. 164200553Sjkim */ 16567754Smsmith bool 16667754Smsmith good() const 16767754Smsmith { return this->rdstate() == 0; } 16867754Smsmith 16967754Smsmith /** 17067754Smsmith * @brief Fast error checking. 17167754Smsmith * @return True if the eofbit is set. 17267754Smsmith * 173209746Sjkim * Note that other iostate flags may also be set. 174200553Sjkim */ 17567754Smsmith bool 176114237Snjl eof() const 17767754Smsmith { return (this->rdstate() & eofbit) != 0; } 178193267Sjkim 17967754Smsmith /** 18067754Smsmith * @brief Fast error checking. 18167754Smsmith * @return True if either the badbit or the failbit is set. 18267754Smsmith * 18367754Smsmith * Checking the badbit in fail() is historical practice. 18467754Smsmith * Note that other iostate flags may also be set. 18567754Smsmith */ 18691116Smsmith bool 18767754Smsmith fail() const 18867754Smsmith { return (this->rdstate() & (badbit | failbit)) != 0; } 18967754Smsmith 190167802Sjkim /** 19167754Smsmith * @brief Fast error checking. 192167802Sjkim * @return True if the badbit is set. 19367754Smsmith * 19467754Smsmith * Note that other iostate flags may also be set. 195100966Siwasaki */ 19667754Smsmith bool 197100966Siwasaki bad() const 198100966Siwasaki { return (this->rdstate() & badbit) != 0; } 199100966Siwasaki 200100966Siwasaki /** 201100966Siwasaki * @brief Throwing exceptions on errors. 20267754Smsmith * @return The current exceptions mask. 203100966Siwasaki * 20467754Smsmith * This changes nothing in the stream. See the one-argument version 205241973Sjkim * of exceptions(iostate) for the meaning of the return value. 206241973Sjkim */ 207100966Siwasaki iostate 20867754Smsmith exceptions() const 20967754Smsmith { return _M_exception; } 21067754Smsmith 21167754Smsmith /** 212100966Siwasaki * @brief Throwing exceptions on errors. 21367754Smsmith * @param except The new exceptions mask. 214100966Siwasaki * 215100966Siwasaki * By default, error flags are set silently. You can set an 216100966Siwasaki * exceptions mask for each stream; if a bit in the mask becomes set 21767754Smsmith * in the error flags, then an exception of type 21867754Smsmith * std::ios_base::failure is thrown. 219100966Siwasaki * 220100966Siwasaki * If the error flage is already set when the exceptions mask is 221100966Siwasaki * added, the exception is immediately thrown. Try running the 22267754Smsmith * following under GCC 3.1 or later: 22367754Smsmith * @code 22467754Smsmith * #include <iostream> 22567754Smsmith * #include <fstream> 226107325Siwasaki * #include <exception> 22767754Smsmith * 228100966Siwasaki * int main() 22967754Smsmith * { 23067754Smsmith * std::set_terminate (__gnu_cxx::__verbose_terminate_handler); 23191116Smsmith * 23291116Smsmith * std::ifstream f ("/etc/motd"); 23391116Smsmith * 23491116Smsmith * std::cerr << "Setting badbit\n"; 23591116Smsmith * f.setstate (std::ios_base::badbit); 23691116Smsmith * 237100966Siwasaki * std::cerr << "Setting exception mask\n"; 23873561Smsmith * f.exceptions (std::ios_base::badbit); 239100966Siwasaki * } 24067754Smsmith * @endcode 241100966Siwasaki */ 24267754Smsmith void 243200553Sjkim exceptions(iostate __except) 244100966Siwasaki { 245100966Siwasaki _M_exception = __except; 246100966Siwasaki this->clear(_M_streambuf_state); 247100966Siwasaki } 248100966Siwasaki 24967754Smsmith // Constructor/destructor: 250100966Siwasaki /** 25167754Smsmith * @brief Constructor performs initialization. 252100966Siwasaki * 253100966Siwasaki * The parameter is passed by derived streams. 25467754Smsmith */ 255200553Sjkim explicit 256100966Siwasaki basic_ios(basic_streambuf<_CharT, _Traits>* __sb) 25767754Smsmith : ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0), 258100966Siwasaki _M_ctype(0), _M_num_put(0), _M_num_get(0) 259100966Siwasaki { this->init(__sb); } 26067754Smsmith 26167754Smsmith /** 26267754Smsmith * @brief Empty. 263100966Siwasaki * 26467754Smsmith * The destructor does nothing. More specifically, it does not 265193267Sjkim * destroy the streambuf held by rdbuf(). 26687031Smsmith */ 26787031Smsmith virtual 268100966Siwasaki ~basic_ios() { } 26987031Smsmith 27087031Smsmith // Members: 27187031Smsmith /** 272100966Siwasaki * @brief Fetches the current @e tied stream. 27387031Smsmith * @return A pointer to the tied stream, or NULL if the stream is 274200553Sjkim * not tied. 27587031Smsmith * 27687031Smsmith * A stream may be @e tied (or synchronized) to a second output 27787031Smsmith * stream. When this stream performs any I/O, the tied stream is 27887031Smsmith * first flushed. For example, @c std::cin is tied to @c std::cout. 27987031Smsmith */ 28091116Smsmith basic_ostream<_CharT, _Traits>* 28187031Smsmith tie() const 28287031Smsmith { return _M_tie; } 28387031Smsmith 284167802Sjkim /** 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 _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 462_GLIBCXX_END_NAMESPACE 463 464#ifndef _GLIBCXX_EXPORT_TEMPLATE 465#include <bits/basic_ios.tcc> 466#endif 467 468#endif /* _BASIC_IOS_H */ 469