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

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