libstdc++-v3/include/bits/basic_ios.h

   1 // Iostreams base classes -*- C++ -*-
   2
   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.
  10
  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.
  15
  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.
  20
  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.
  29
  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.
  33  */
  34
  35 #ifndef _CPP_BITS_BASICIOS_H
  36 #define _CPP_BITS_BASICIOS_H 1
  37
  38 #pragma GCC system_header
  39
  40 #include <bits/streambuf_iterator.h>
  41 #include <bits/locale_facets.h>
  42
  43 namespace std
  44 {
  45   // 27.4.5  Template class basic_ios
  46   /**
  47    *  @brief  Virtual base class for all stream classes.
  48    *
  49    *  Most of the member functions called dispatched on stream objects
  50    *  (e.g., @c std::cout.foo(bar);) are consolidated in this class.
  51   */
  52   template<typename _CharT, typename _Traits>
  53     class basic_ios : public ios_base
  54     {
  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.
  61       */
  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       //@}
  68
  69       //@{
  70       /**
  71        *  @if maint
  72        *  These are non-standard types.
  73        *  @endif
  74       */
  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       //@}
  81
  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;
  88
  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;
  95
  96     public:
  97       //@{
  98       /**
  99        *  @brief  The quick-and-easy status check.
 100        *
 101        *  This allows you to write constructs such as
 102        *  "if (!a_stream) ..." and "while (a_stream) ..."
 103       */
 104       operator void*() const
 105       { return this->fail() ? 0 : const_cast<basic_ios*>(this); }
 106
 107       bool
 108       operator!() const
 109       { return this->fail(); }
 110       //@}
 111
 112       /**
 113        *  @brief  Returns the error state of the stream buffer.
 114        *  @return  A bit pattern (well, isn't everything?)
 115        *
 116        *  See std::ios_base::iostate for the possible bit values.  Most
 117        *  users will call one of the interpreting wrappers, e.g., good().
 118       */
 119       iostate
 120       rdstate() const
 121       { return _M_streambuf_state; }
 122
 123       /**
 124        *  @brief  [Re]sets the error state.
 125        *  @param  state  The new state flag(s) to set.
 126        *
 127        *  See std::ios_base::iostate for the possible bit values.  Most
 128        *  users will not need to pass an argument.
 129       */
 130       void
 131       clear(iostate __state = goodbit);
 132
 133       /**
 134        *  @brief  Sets additional flags in the error state.
 135        *  @param  state  The additional state flag(s) to set.
 136        *
 137        *  See std::ios_base::iostate for the possible bit values.
 138       */
 139       void
 140       setstate(iostate __state)
 141       { this->clear(this->rdstate() | __state); }
 142
 143       /**
 144        *  @brief  Fast error checking.
 145        *  @return  True if no error flags are set.
 146        *
 147        *  A wrapper around rdstate.
 148       */
 149       bool
 150       good() const
 151       { return this->rdstate() == 0; }
 152
 153       /**
 154        *  @brief  Fast error checking.
 155        *  @return  True if the eofbit is set.
 156        *
 157        *  Note that other iostate flags may also be set.
 158       */
 159       bool
 160       eof() const
 161       { return (this->rdstate() & eofbit) != 0; }
 162
 163       /**
 164        *  @brief  Fast error checking.
 165        *  @return  True if either the badbit or the failbit is set.
 166        *
 167        *  Checking the badbit in fail() is historical practice.
 168        *  Note that other iostate flags may also be set.
 169       */
 170       bool
 171       fail() const
 172       { return (this->rdstate() & (badbit | failbit)) != 0; }
 173
 174       /**
 175        *  @brief  Fast error checking.
 176        *  @return  True if the badbit is set.
 177        *
 178        *  Note that other iostate flags may also be set.
 179       */
 180       bool
 181       bad() const
 182       { return (this->rdstate() & badbit) != 0; }
 183
 184       /**
 185        *  @brief  Throwing exceptions on errors.
 186        *  @return  The current exceptions mask.
 187        *
 188        *  This changes nothing in the stream.  See the one-argument version
 189        *  of exceptions(iostate) for the meaning of the return value.
 190       */
 191       iostate
 192       exceptions() const
 193       { return _M_exception; }
 194
 195       /**
 196        *  @brief  Throwing exceptions on errors.
 197        *  @param  except  The new exceptions mask.
 198        *
 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.
 203        *
 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>
 211        *
 212        *  int main()
 213        *  {
 214        *      std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
 215        *
 216        *      std::ifstream f ("/etc/motd");
 217        *
 218        *      std::cerr << "Setting badbit\n";
 219        *      f.setstate (std::ios_base::badbit);
 220        *
 221        *      std::cerr << "Setting exception mask\n";
 222        *      f.exceptions (std::ios_base::badbit);
 223        *  }
 224        *  @endcode
 225       */
 226       void
 227       exceptions(iostate __except)
 228       {
 229         _M_exception = __except;
 230         this->clear(_M_streambuf_state);
 231       }
 232
 233       // Constructor/destructor:
 234       /**
 235        *  @brief  Constructor performs initialization.
 236        *
 237        *  The parameter is passed by derived streams.
 238       */
 239       explicit
 240       basic_ios(basic_streambuf<_CharT, _Traits>* __sb) : ios_base()
 241       { this->init(__sb); }
 242
 243       /**
 244        *  @brief  Empty.
 245        *
 246        *  The destructor does nothing.  More specifically, it does not
 247        *  destroy the streambuf held by rdbuf().
 248       */
 249       virtual
 250       ~basic_ios() { }
 251
 252       // Members:
 253       /**
 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.
 257        *
 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.
 261       */
 262       basic_ostream<_CharT, _Traits>*
 263       tie() const
 264       { return _M_tie; }
 265
 266       /**
 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.
 271        *
 272        *  This sets up a new tie; see tie() for more.
 273       */
 274       basic_ostream<_CharT, _Traits>*
 275       tie(basic_ostream<_CharT, _Traits>* __tiestr)
 276       {
 277         basic_ostream<_CharT, _Traits>* __old = _M_tie;
 278         _M_tie = __tiestr;
 279         return __old;
 280       }
 281
 282       /**
 283        *  @brief  Accessing the underlying buffer.
 284        *  @return  The current stream buffer.
 285        *
 286        *  This does not change the state of the stream.
 287       */
 288       basic_streambuf<_CharT, _Traits>*
 289       rdbuf() const
 290       { return _M_streambuf; }
 291
 292       /**
 293        *  @brief  Changing the underlying buffer.
 294        *  @param  sb  The new stream buffer.
 295        *  @return  The previous stream buffer.
 296        *
 297        *  Associates a new buffer with the current stream, and clears the
 298        *  error state.
 299        *
 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.
 306       */
 307       basic_streambuf<_CharT, _Traits>*
 308       rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
 309
 310       /**
 311        *  @doctodo
 312       */
 313       basic_ios&
 314       copyfmt(const basic_ios& __rhs);
 315
 316       /**
 317        *  @brief  Retreives the "empty" character.
 318        *  @return  The current fill character.
 319        *
 320        *  It defaults to a space (' ') in the current locale.
 321       */
 322       char_type
 323       fill() const
 324       {
 325         if (!_M_fill_init)
 326           {
 327             _M_fill = this->widen(' ');
 328             _M_fill_init = true;
 329           }
 330         return _M_fill;
 331       }
 332
 333       /**
 334        *  @brief  Sets a new "empty" character.
 335        *  @param  ch  The new character.
 336        *  @return  The previous fill character.
 337        *
 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.
 341       */
 342       char_type
 343       fill(char_type __ch)
 344       {
 345         char_type __old = this->fill();
 346         _M_fill = __ch;
 347         return __old;
 348       }
 349
 350       // Locales:
 351       /**
 352        *  @brief  Moves to a new locale.
 353        *  @param  loc  The new locale.
 354        *  @return  The previous locale.
 355        *
 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).
 358        *
 359        *  Additional l10n notes are at
 360        *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
 361       */
 362       locale
 363       imbue(const locale& __loc);
 364
 365       /**
 366        *  @brief  Squeezes characters.
 367        *  @param  c  The character to narrow.
 368        *  @param  dfault  The character to narrow.
 369        *  @return  The narrowed character.
 370        *
 371        *  Maps a character of @c char_type to a character of @c char,
 372        *  if possible.
 373        *
 374        *  Returns the result of
 375        *  @code
 376        *    std::use_facet< ctype<char_type> >(getloc()).narrow(c,dfault)
 377        *  @endcode
 378        *
 379        *  Additional l10n notes are at
 380        *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
 381       */
 382       char
 383       narrow(char_type __c, char __dfault) const;
 384
 385       /**
 386        *  @brief  Widens characters.
 387        *  @param  c  The character to widen.
 388        *  @return  The widened character.
 389        *
 390        *  Maps a character of @c char to a character of @c char_type.
 391        *
 392        *  Returns the result of
 393        *  @code
 394        *    std::use_facet< ctype<char_type> >(getloc()).widen(c)
 395        *  @endcode
 396        *
 397        *  Additional l10n notes are at
 398        *  http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
 399       */
 400       char_type
 401       widen(char __c) const;
 402
 403     protected:
 404       // 27.4.5.1  basic_ios constructors
 405       /**
 406        *  @brief  Empty.
 407        *
 408        *  The default constructor does nothing and is not normally
 409        *  accessible to users.
 410       */
 411       basic_ios() : ios_base()
 412       { }
 413
 414       /**
 415        *  @brief  All setup is performed here.
 416        *
 417        *  This is called from the public constructor.  It is not virtual and
 418        *  cannot be redefined.
 419       */
 420       void
 421       init(basic_streambuf<_CharT, _Traits>* __sb);
 422
 423       bool
 424       _M_check_facet(const locale::facet* __f) const
 425       {
 426         if (!__f)
 427           __throw_bad_cast();
 428         return true;
 429       }
 430
 431       void
 432       _M_cache_facets(const locale& __loc);
 433     };
 434 } // namespace std
 435
 436 #ifdef _GLIBCPP_NO_TEMPLATE_EXPORT
 437 # define export
 438 #include <bits/basic_ios.tcc>
 439 #endif
 440
 441 #endif /* _CPP_BITS_BASICIOS_H */