contrib/gcc-4.1/libstdc++-v3/include/bits/basic_ios.h

   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, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
  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       { 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       ~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       _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 */