197403Sobrien// Iostreams base classes -*- C++ -*- 297403Sobrien 3169691Skan// Copyright (C) 1997, 1998, 1999, 2001, 2002, 2003, 2004, 2005 4117397Skan// Free Software Foundation, Inc. 597403Sobrien// 697403Sobrien// This file is part of the GNU ISO C++ Library. This library is free 797403Sobrien// software; you can redistribute it and/or modify it under the 897403Sobrien// terms of the GNU General Public License as published by the 997403Sobrien// Free Software Foundation; either version 2, or (at your option) 1097403Sobrien// any later version. 1197403Sobrien 1297403Sobrien// This library is distributed in the hope that it will be useful, 1397403Sobrien// but WITHOUT ANY WARRANTY; without even the implied warranty of 1497403Sobrien// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 1597403Sobrien// GNU General Public License for more details. 1697403Sobrien 1797403Sobrien// You should have received a copy of the GNU General Public License along 1897403Sobrien// with this library; see the file COPYING. If not, write to the Free 19169691Skan// Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 2097403Sobrien// USA. 2197403Sobrien 2297403Sobrien// As a special exception, you may use this file as part of a free software 2397403Sobrien// library without restriction. Specifically, if other files instantiate 2497403Sobrien// templates or use macros or inline functions from this file, or you compile 2597403Sobrien// this file and link it with other files to produce an executable, this 2697403Sobrien// file does not by itself cause the resulting executable to be covered by 2797403Sobrien// the GNU General Public License. This exception does not however 2897403Sobrien// invalidate any other reasons why the executable file might be covered by 2997403Sobrien// the GNU General Public License. 3097403Sobrien 3197403Sobrien/** @file basic_ios.h 3297403Sobrien * This is an internal header file, included by other library headers. 3397403Sobrien * You should not attempt to use it directly. 3497403Sobrien */ 3597403Sobrien 36132720Skan#ifndef _BASIC_IOS_H 37132720Skan#define _BASIC_IOS_H 1 3897403Sobrien 3997403Sobrien#pragma GCC system_header 4097403Sobrien 4197403Sobrien#include <bits/streambuf_iterator.h> 42117397Skan#include <bits/localefwd.h> 43117397Skan#include <bits/locale_classes.h> 4497403Sobrien#include <bits/locale_facets.h> 4597403Sobrien 46169691Skan_GLIBCXX_BEGIN_NAMESPACE(std) 47169691Skan 4897403Sobrien // 27.4.5 Template class basic_ios 49117397Skan /** 50117397Skan * @brief Virtual base class for all stream classes. 51117397Skan * 52117397Skan * Most of the member functions called dispatched on stream objects 53117397Skan * (e.g., @c std::cout.foo(bar);) are consolidated in this class. 54117397Skan */ 5597403Sobrien template<typename _CharT, typename _Traits> 5697403Sobrien class basic_ios : public ios_base 5797403Sobrien { 5897403Sobrien public: 59117397Skan //@{ 60117397Skan /** 61117397Skan * These are standard types. They permit a standardized way of 62117397Skan * referring to names of (or names dependant on) the template 63117397Skan * parameters, which are specific to the implementation. 64117397Skan */ 65117397Skan typedef _CharT char_type; 66117397Skan typedef typename _Traits::int_type int_type; 67117397Skan typedef typename _Traits::pos_type pos_type; 68117397Skan typedef typename _Traits::off_type off_type; 69117397Skan typedef _Traits traits_type; 70117397Skan //@} 7197403Sobrien 72117397Skan //@{ 73117397Skan /** 74117397Skan * @if maint 75117397Skan * These are non-standard types. 76117397Skan * @endif 77117397Skan */ 78117397Skan typedef ctype<_CharT> __ctype_type; 79132720Skan typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> > 80132720Skan __num_put_type; 81132720Skan typedef num_get<_CharT, istreambuf_iterator<_CharT, _Traits> > 82132720Skan __num_get_type; 83117397Skan //@} 84117397Skan 8597403Sobrien // Data members: 8697403Sobrien protected: 87117397Skan basic_ostream<_CharT, _Traits>* _M_tie; 88117397Skan mutable char_type _M_fill; 89117397Skan mutable bool _M_fill_init; 90117397Skan basic_streambuf<_CharT, _Traits>* _M_streambuf; 9197403Sobrien 9297403Sobrien // Cached use_facet<ctype>, which is based on the current locale info. 93132720Skan const __ctype_type* _M_ctype; 94132720Skan // For ostream. 95132720Skan const __num_put_type* _M_num_put; 96132720Skan // For istream. 97132720Skan const __num_get_type* _M_num_get; 9897403Sobrien 9997403Sobrien public: 100117397Skan //@{ 101117397Skan /** 102117397Skan * @brief The quick-and-easy status check. 103117397Skan * 104117397Skan * This allows you to write constructs such as 105117397Skan * "if (!a_stream) ..." and "while (a_stream) ..." 106117397Skan */ 107132720Skan operator void*() const 10897403Sobrien { return this->fail() ? 0 : const_cast<basic_ios*>(this); } 10997403Sobrien 110132720Skan bool 111132720Skan operator!() const 11297403Sobrien { return this->fail(); } 113117397Skan //@} 11497403Sobrien 115117397Skan /** 116117397Skan * @brief Returns the error state of the stream buffer. 117117397Skan * @return A bit pattern (well, isn't everything?) 118117397Skan * 119117397Skan * See std::ios_base::iostate for the possible bit values. Most 120117397Skan * users will call one of the interpreting wrappers, e.g., good(). 121117397Skan */ 122132720Skan iostate 123132720Skan rdstate() const 12497403Sobrien { return _M_streambuf_state; } 12597403Sobrien 126117397Skan /** 127117397Skan * @brief [Re]sets the error state. 128117397Skan * @param state The new state flag(s) to set. 129117397Skan * 130117397Skan * See std::ios_base::iostate for the possible bit values. Most 131117397Skan * users will not need to pass an argument. 132117397Skan */ 133132720Skan void 13497403Sobrien clear(iostate __state = goodbit); 13597403Sobrien 136117397Skan /** 137117397Skan * @brief Sets additional flags in the error state. 138117397Skan * @param state The additional state flag(s) to set. 139117397Skan * 140117397Skan * See std::ios_base::iostate for the possible bit values. 141117397Skan */ 142132720Skan void 143132720Skan setstate(iostate __state) 14497403Sobrien { this->clear(this->rdstate() | __state); } 14597403Sobrien 146132720Skan // Flip the internal state on for the proper state bits, then re 147132720Skan // throws the propagated exception if bit also set in 148132720Skan // exceptions(). 149132720Skan void 150132720Skan _M_setstate(iostate __state) 151132720Skan { 152132720Skan // 27.6.1.2.1 Common requirements. 153132720Skan // Turn this on without causing an ios::failure to be thrown. 154132720Skan _M_streambuf_state |= __state; 155132720Skan if (this->exceptions() & __state) 156132720Skan __throw_exception_again; 157132720Skan } 158132720Skan 159117397Skan /** 160117397Skan * @brief Fast error checking. 161117397Skan * @return True if no error flags are set. 162117397Skan * 163117397Skan * A wrapper around rdstate. 164117397Skan */ 165132720Skan bool 166132720Skan good() const 16797403Sobrien { return this->rdstate() == 0; } 16897403Sobrien 169117397Skan /** 170117397Skan * @brief Fast error checking. 171117397Skan * @return True if the eofbit is set. 172117397Skan * 173117397Skan * Note that other iostate flags may also be set. 174117397Skan */ 175132720Skan bool 176132720Skan eof() const 17797403Sobrien { return (this->rdstate() & eofbit) != 0; } 17897403Sobrien 179117397Skan /** 180117397Skan * @brief Fast error checking. 181117397Skan * @return True if either the badbit or the failbit is set. 182117397Skan * 183117397Skan * Checking the badbit in fail() is historical practice. 184117397Skan * Note that other iostate flags may also be set. 185117397Skan */ 186132720Skan bool 187132720Skan fail() const 18897403Sobrien { return (this->rdstate() & (badbit | failbit)) != 0; } 18997403Sobrien 190117397Skan /** 191117397Skan * @brief Fast error checking. 192117397Skan * @return True if the badbit is set. 193117397Skan * 194117397Skan * Note that other iostate flags may also be set. 195117397Skan */ 196132720Skan bool 197132720Skan bad() const 19897403Sobrien { return (this->rdstate() & badbit) != 0; } 19997403Sobrien 200117397Skan /** 201117397Skan * @brief Throwing exceptions on errors. 202117397Skan * @return The current exceptions mask. 203117397Skan * 204117397Skan * This changes nothing in the stream. See the one-argument version 205117397Skan * of exceptions(iostate) for the meaning of the return value. 206117397Skan */ 207132720Skan iostate 208132720Skan exceptions() const 20997403Sobrien { return _M_exception; } 21097403Sobrien 211117397Skan /** 212117397Skan * @brief Throwing exceptions on errors. 213117397Skan * @param except The new exceptions mask. 214117397Skan * 215117397Skan * By default, error flags are set silently. You can set an 216117397Skan * exceptions mask for each stream; if a bit in the mask becomes set 217117397Skan * in the error flags, then an exception of type 218117397Skan * std::ios_base::failure is thrown. 219117397Skan * 220117397Skan * If the error flage is already set when the exceptions mask is 221117397Skan * added, the exception is immediately thrown. Try running the 222117397Skan * following under GCC 3.1 or later: 223117397Skan * @code 224117397Skan * #include <iostream> 225117397Skan * #include <fstream> 226117397Skan * #include <exception> 227132720Skan * 228117397Skan * int main() 229117397Skan * { 230117397Skan * std::set_terminate (__gnu_cxx::__verbose_terminate_handler); 231132720Skan * 232117397Skan * std::ifstream f ("/etc/motd"); 233132720Skan * 234117397Skan * std::cerr << "Setting badbit\n"; 235117397Skan * f.setstate (std::ios_base::badbit); 236132720Skan * 237117397Skan * std::cerr << "Setting exception mask\n"; 238117397Skan * f.exceptions (std::ios_base::badbit); 239117397Skan * } 240117397Skan * @endcode 241117397Skan */ 242132720Skan void 243132720Skan exceptions(iostate __except) 244132720Skan { 245132720Skan _M_exception = __except; 246132720Skan this->clear(_M_streambuf_state); 24797403Sobrien } 24897403Sobrien 24997403Sobrien // Constructor/destructor: 250117397Skan /** 251117397Skan * @brief Constructor performs initialization. 252117397Skan * 253117397Skan * The parameter is passed by derived streams. 254117397Skan */ 255132720Skan explicit 256132720Skan basic_ios(basic_streambuf<_CharT, _Traits>* __sb) 257132720Skan : ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0), 258132720Skan _M_ctype(0), _M_num_put(0), _M_num_get(0) 25997403Sobrien { this->init(__sb); } 26097403Sobrien 261117397Skan /** 262117397Skan * @brief Empty. 263117397Skan * 264117397Skan * The destructor does nothing. More specifically, it does not 265117397Skan * destroy the streambuf held by rdbuf(). 266117397Skan */ 267132720Skan virtual 26897403Sobrien ~basic_ios() { } 269132720Skan 27097403Sobrien // Members: 271117397Skan /** 272117397Skan * @brief Fetches the current @e tied stream. 273117397Skan * @return A pointer to the tied stream, or NULL if the stream is 274117397Skan * not tied. 275117397Skan * 276117397Skan * A stream may be @e tied (or synchronized) to a second output 277117397Skan * stream. When this stream performs any I/O, the tied stream is 278117397Skan * first flushed. For example, @c std::cin is tied to @c std::cout. 279117397Skan */ 28097403Sobrien basic_ostream<_CharT, _Traits>* 281132720Skan tie() const 28297403Sobrien { return _M_tie; } 28397403Sobrien 284117397Skan /** 285117397Skan * @brief Ties this stream to an output stream. 286117397Skan * @param tiestr The output stream. 287117397Skan * @return The previously tied output stream, or NULL if the stream 288117397Skan * was not tied. 289117397Skan * 290117397Skan * This sets up a new tie; see tie() for more. 291117397Skan */ 29297403Sobrien basic_ostream<_CharT, _Traits>* 29397403Sobrien tie(basic_ostream<_CharT, _Traits>* __tiestr) 29497403Sobrien { 295117397Skan basic_ostream<_CharT, _Traits>* __old = _M_tie; 296117397Skan _M_tie = __tiestr; 297117397Skan return __old; 29897403Sobrien } 29997403Sobrien 300117397Skan /** 301117397Skan * @brief Accessing the underlying buffer. 302117397Skan * @return The current stream buffer. 303117397Skan * 304117397Skan * This does not change the state of the stream. 305117397Skan */ 30697403Sobrien basic_streambuf<_CharT, _Traits>* 307132720Skan rdbuf() const 30897403Sobrien { return _M_streambuf; } 30997403Sobrien 310117397Skan /** 311117397Skan * @brief Changing the underlying buffer. 312117397Skan * @param sb The new stream buffer. 313117397Skan * @return The previous stream buffer. 314117397Skan * 315117397Skan * Associates a new buffer with the current stream, and clears the 316117397Skan * error state. 317117397Skan * 318117397Skan * Due to historical accidents which the LWG refuses to correct, the 319117397Skan * I/O library suffers from a design error: this function is hidden 320117397Skan * in derived classes by overrides of the zero-argument @c rdbuf(), 321117397Skan * which is non-virtual for hysterical raisins. As a result, you 322117397Skan * must use explicit qualifications to access this function via any 323132720Skan * derived class. For example: 324132720Skan * 325132720Skan * @code 326132720Skan * std::fstream foo; // or some other derived type 327132720Skan * std::streambuf* p = .....; 328132720Skan * 329132720Skan * foo.ios::rdbuf(p); // ios == basic_ios<char> 330132720Skan * @endcode 331117397Skan */ 332132720Skan basic_streambuf<_CharT, _Traits>* 33397403Sobrien rdbuf(basic_streambuf<_CharT, _Traits>* __sb); 33497403Sobrien 335117397Skan /** 336132720Skan * @brief Copies fields of __rhs into this. 337132720Skan * @param __rhs The source values for the copies. 338132720Skan * @return Reference to this object. 339132720Skan * 340132720Skan * All fields of __rhs are copied into this object except that rdbuf() 341132720Skan * and rdstate() remain unchanged. All values in the pword and iword 342132720Skan * arrays are copied. Before copying, each callback is invoked with 343132720Skan * erase_event. After copying, each (new) callback is invoked with 344132720Skan * copyfmt_event. The final step is to copy exceptions(). 345117397Skan */ 34697403Sobrien basic_ios& 34797403Sobrien copyfmt(const basic_ios& __rhs); 34897403Sobrien 349117397Skan /** 350117397Skan * @brief Retreives the "empty" character. 351117397Skan * @return The current fill character. 352117397Skan * 353117397Skan * It defaults to a space (' ') in the current locale. 354117397Skan */ 355132720Skan char_type 356132720Skan fill() const 35797403Sobrien { 35897403Sobrien if (!_M_fill_init) 35997403Sobrien { 36097403Sobrien _M_fill = this->widen(' '); 36197403Sobrien _M_fill_init = true; 36297403Sobrien } 363132720Skan return _M_fill; 36497403Sobrien } 36597403Sobrien 366117397Skan /** 367117397Skan * @brief Sets a new "empty" character. 368117397Skan * @param ch The new character. 369117397Skan * @return The previous fill character. 370117397Skan * 371117397Skan * The fill character is used to fill out space when P+ characters 372117397Skan * have been requested (e.g., via setw), Q characters are actually 373117397Skan * used, and Q<P. It defaults to a space (' ') in the current locale. 374117397Skan */ 375132720Skan char_type 37697403Sobrien fill(char_type __ch) 37797403Sobrien { 37897403Sobrien char_type __old = this->fill(); 37997403Sobrien _M_fill = __ch; 38097403Sobrien return __old; 38197403Sobrien } 38297403Sobrien 38397403Sobrien // Locales: 384117397Skan /** 385117397Skan * @brief Moves to a new locale. 386117397Skan * @param loc The new locale. 387117397Skan * @return The previous locale. 388117397Skan * 389117397Skan * Calls @c ios_base::imbue(loc), and if a stream buffer is associated 390117397Skan * with this stream, calls that buffer's @c pubimbue(loc). 391117397Skan * 392117397Skan * Additional l10n notes are at 393117397Skan * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 394117397Skan */ 395132720Skan locale 39697403Sobrien imbue(const locale& __loc); 39797403Sobrien 398117397Skan /** 399117397Skan * @brief Squeezes characters. 400117397Skan * @param c The character to narrow. 401117397Skan * @param dfault The character to narrow. 402117397Skan * @return The narrowed character. 403117397Skan * 404117397Skan * Maps a character of @c char_type to a character of @c char, 405117397Skan * if possible. 406117397Skan * 407117397Skan * Returns the result of 408117397Skan * @code 409132720Skan * std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault) 410117397Skan * @endcode 411117397Skan * 412117397Skan * Additional l10n notes are at 413117397Skan * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 414117397Skan */ 415132720Skan char 41697403Sobrien narrow(char_type __c, char __dfault) const; 41797403Sobrien 418117397Skan /** 419117397Skan * @brief Widens characters. 420117397Skan * @param c The character to widen. 421117397Skan * @return The widened character. 422117397Skan * 423117397Skan * Maps a character of @c char to a character of @c char_type. 424117397Skan * 425117397Skan * Returns the result of 426117397Skan * @code 427132720Skan * std::use_facet<ctype<char_type> >(getloc()).widen(c) 428117397Skan * @endcode 429117397Skan * 430117397Skan * Additional l10n notes are at 431117397Skan * http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html 432117397Skan */ 433132720Skan char_type 43497403Sobrien widen(char __c) const; 435132720Skan 43697403Sobrien protected: 43797403Sobrien // 27.4.5.1 basic_ios constructors 438117397Skan /** 439117397Skan * @brief Empty. 440117397Skan * 441117397Skan * The default constructor does nothing and is not normally 442117397Skan * accessible to users. 443117397Skan */ 444132720Skan basic_ios() 445132720Skan : ios_base(), _M_tie(0), _M_fill(char_type()), _M_fill_init(false), 446132720Skan _M_streambuf(0), _M_ctype(0), _M_num_put(0), _M_num_get(0) 44797403Sobrien { } 44897403Sobrien 449117397Skan /** 450117397Skan * @brief All setup is performed here. 451117397Skan * 452117397Skan * This is called from the public constructor. It is not virtual and 453132720Skan * cannot be redefined. 454117397Skan */ 455132720Skan void 45697403Sobrien init(basic_streambuf<_CharT, _Traits>* __sb); 45797403Sobrien 45897403Sobrien void 459117397Skan _M_cache_locale(const locale& __loc); 46097403Sobrien }; 46197403Sobrien 462169691Skan_GLIBCXX_END_NAMESPACE 463169691Skan 464132720Skan#ifndef _GLIBCXX_EXPORT_TEMPLATE 46597403Sobrien#include <bits/basic_ios.tcc> 46697403Sobrien#endif 46797403Sobrien 468132720Skan#endif /* _BASIC_IOS_H */ 469