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