// Iostreams base classes -*- C++ -*-
-// Copyright (C) 1997, 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
+// Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+// 2006, 2007, 2008, 2009, 2010, 2011
+// Free Software Foundation, Inc.
//
// This file is part of the GNU ISO C++ Library. This library is free
// software; you can redistribute it and/or modify it under the
// terms of the GNU General Public License as published by the
-// Free Software Foundation; either version 2, or (at your option)
+// Free Software Foundation; either version 3, or (at your option)
// any later version.
// This library is distributed in the hope that it will be useful,
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
-// You should have received a copy of the GNU General Public License along
-// with this library; see the file COPYING. If not, write to the Free
-// Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
-// USA.
-
-// As a special exception, you may use this file as part of a free software
-// library without restriction. Specifically, if other files instantiate
-// templates or use macros or inline functions from this file, or you compile
-// this file and link it with other files to produce an executable, this
-// file does not by itself cause the resulting executable to be covered by
-// the GNU General Public License. This exception does not however
-// invalidate any other reasons why the executable file might be covered by
-// the GNU General Public License.
-
-/** @file basic_ios.h
+// Under Section 7 of GPL version 3, you are granted additional
+// permissions described in the GCC Runtime Library Exception, version
+// 3.1, as published by the Free Software Foundation.
+
+// You should have received a copy of the GNU General Public License and
+// a copy of the GCC Runtime Library Exception along with this program;
+// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
+// <http://www.gnu.org/licenses/>.
+
+/** @file bits/basic_ios.h
* This is an internal header file, included by other library headers.
- * You should not attempt to use it directly.
+ * Do not attempt to use it directly. @headername{ios}
*/
-#ifndef _CPP_BITS_BASICIOS_H
-#define _CPP_BITS_BASICIOS_H 1
+#ifndef _BASIC_IOS_H
+#define _BASIC_IOS_H 1
#pragma GCC system_header
-#include <bits/streambuf_iterator.h>
+#include <bits/localefwd.h>
+#include <bits/locale_classes.h>
#include <bits/locale_facets.h>
+#include <bits/streambuf_iterator.h>
-namespace std
+namespace std _GLIBCXX_VISIBILITY(default)
{
+_GLIBCXX_BEGIN_NAMESPACE_VERSION
+
+ template<typename _Facet>
+ inline const _Facet&
+ __check_facet(const _Facet* __f)
+ {
+ if (!__f)
+ __throw_bad_cast();
+ return *__f;
+ }
+
// 27.4.5 Template class basic_ios
+ /**
+ * @brief Virtual base class for all stream classes.
+ * @ingroup io
+ *
+ * Most of the member functions called dispatched on stream objects
+ * (e.g., @c std::cout.foo(bar);) are consolidated in this class.
+ */
template<typename _CharT, typename _Traits>
class basic_ios : public ios_base
{
public:
- // Types:
- typedef _CharT char_type;
- typedef typename _Traits::int_type int_type;
- typedef typename _Traits::pos_type pos_type;
- typedef typename _Traits::off_type off_type;
- typedef _Traits traits_type;
-
- // Non-standard Types:
- typedef ctype<_CharT> __ctype_type;
- typedef ostreambuf_iterator<_CharT, _Traits> __ostreambuf_iter;
- typedef num_put<_CharT, __ostreambuf_iter> __numput_type;
- typedef istreambuf_iterator<_CharT, _Traits> __istreambuf_iter;
- typedef num_get<_CharT, __istreambuf_iter> __numget_type;
-
+ //@{
+ /**
+ * These are standard types. They permit a standardized way of
+ * referring to names of (or names dependant on) the template
+ * parameters, which are specific to the implementation.
+ */
+ typedef _CharT char_type;
+ typedef typename _Traits::int_type int_type;
+ typedef typename _Traits::pos_type pos_type;
+ typedef typename _Traits::off_type off_type;
+ typedef _Traits traits_type;
+ //@}
+
+ //@{
+ /**
+ * These are non-standard types.
+ */
+ typedef ctype<_CharT> __ctype_type;
+ typedef num_put<_CharT, ostreambuf_iterator<_CharT, _Traits> >
+ __num_put_type;
+ typedef num_get<_CharT, istreambuf_iterator<_CharT, _Traits> >
+ __num_get_type;
+ //@}
+
// Data members:
protected:
- basic_ostream<_CharT, _Traits>* _M_tie;
- mutable char_type _M_fill;
- mutable bool _M_fill_init;
- iostate _M_exception;
-
- basic_streambuf<_CharT, _Traits>* _M_streambuf;
- iostate _M_streambuf_state;
+ basic_ostream<_CharT, _Traits>* _M_tie;
+ mutable char_type _M_fill;
+ mutable bool _M_fill_init;
+ basic_streambuf<_CharT, _Traits>* _M_streambuf;
// Cached use_facet<ctype>, which is based on the current locale info.
- const __ctype_type* _M_ios_fctype;
- // From ostream.
- const __numput_type* _M_fnumput;
- // From istream.
- const __numget_type* _M_fnumget;
+ const __ctype_type* _M_ctype;
+ // For ostream.
+ const __num_put_type* _M_num_put;
+ // For istream.
+ const __num_get_type* _M_num_get;
public:
- const __ctype_type*
- _M_get_fctype_ios(void)
- { return _M_ios_fctype; }
-
- operator void*() const
+ //@{
+ /**
+ * @brief The quick-and-easy status check.
+ *
+ * This allows you to write constructs such as
+ * <code>if (!a_stream) ...</code> and <code>while (a_stream) ...</code>
+ */
+ operator void*() const
{ return this->fail() ? 0 : const_cast<basic_ios*>(this); }
- bool
- operator!() const
+ bool
+ operator!() const
{ return this->fail(); }
-
- iostate
- rdstate() const
+ //@}
+
+ /**
+ * @brief Returns the error state of the stream buffer.
+ * @return A bit pattern (well, isn't everything?)
+ *
+ * See std::ios_base::iostate for the possible bit values. Most
+ * users will call one of the interpreting wrappers, e.g., good().
+ */
+ iostate
+ rdstate() const
{ return _M_streambuf_state; }
- void
+ /**
+ * @brief [Re]sets the error state.
+ * @param __state The new state flag(s) to set.
+ *
+ * See std::ios_base::iostate for the possible bit values. Most
+ * users will not need to pass an argument.
+ */
+ void
clear(iostate __state = goodbit);
- void
- setstate(iostate __state)
+ /**
+ * @brief Sets additional flags in the error state.
+ * @param __state The additional state flag(s) to set.
+ *
+ * See std::ios_base::iostate for the possible bit values.
+ */
+ void
+ setstate(iostate __state)
{ this->clear(this->rdstate() | __state); }
- bool
- good() const
+ // Flip the internal state on for the proper state bits, then re
+ // throws the propagated exception if bit also set in
+ // exceptions().
+ void
+ _M_setstate(iostate __state)
+ {
+ // 27.6.1.2.1 Common requirements.
+ // Turn this on without causing an ios::failure to be thrown.
+ _M_streambuf_state |= __state;
+ if (this->exceptions() & __state)
+ __throw_exception_again;
+ }
+
+ /**
+ * @brief Fast error checking.
+ * @return True if no error flags are set.
+ *
+ * A wrapper around rdstate.
+ */
+ bool
+ good() const
{ return this->rdstate() == 0; }
- bool
- eof() const
+ /**
+ * @brief Fast error checking.
+ * @return True if the eofbit is set.
+ *
+ * Note that other iostate flags may also be set.
+ */
+ bool
+ eof() const
{ return (this->rdstate() & eofbit) != 0; }
- bool
- fail() const
+ /**
+ * @brief Fast error checking.
+ * @return True if either the badbit or the failbit is set.
+ *
+ * Checking the badbit in fail() is historical practice.
+ * Note that other iostate flags may also be set.
+ */
+ bool
+ fail() const
{ return (this->rdstate() & (badbit | failbit)) != 0; }
- bool
- bad() const
+ /**
+ * @brief Fast error checking.
+ * @return True if the badbit is set.
+ *
+ * Note that other iostate flags may also be set.
+ */
+ bool
+ bad() const
{ return (this->rdstate() & badbit) != 0; }
- iostate
- exceptions() const
+ /**
+ * @brief Throwing exceptions on errors.
+ * @return The current exceptions mask.
+ *
+ * This changes nothing in the stream. See the one-argument version
+ * of exceptions(iostate) for the meaning of the return value.
+ */
+ iostate
+ exceptions() const
{ return _M_exception; }
- void
- exceptions(iostate __except)
- {
- _M_exception = __except;
- this->clear(_M_streambuf_state);
+ /**
+ * @brief Throwing exceptions on errors.
+ * @param __except The new exceptions mask.
+ *
+ * By default, error flags are set silently. You can set an
+ * exceptions mask for each stream; if a bit in the mask becomes set
+ * in the error flags, then an exception of type
+ * std::ios_base::failure is thrown.
+ *
+ * If the error flag is already set when the exceptions mask is
+ * added, the exception is immediately thrown. Try running the
+ * following under GCC 3.1 or later:
+ * @code
+ * #include <iostream>
+ * #include <fstream>
+ * #include <exception>
+ *
+ * int main()
+ * {
+ * std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
+ *
+ * std::ifstream f ("/etc/motd");
+ *
+ * std::cerr << "Setting badbit\n";
+ * f.setstate (std::ios_base::badbit);
+ *
+ * std::cerr << "Setting exception mask\n";
+ * f.exceptions (std::ios_base::badbit);
+ * }
+ * @endcode
+ */
+ void
+ exceptions(iostate __except)
+ {
+ _M_exception = __except;
+ this->clear(_M_streambuf_state);
}
// Constructor/destructor:
- explicit
- basic_ios(basic_streambuf<_CharT, _Traits>* __sb) : ios_base()
+ /**
+ * @brief Constructor performs initialization.
+ *
+ * The parameter is passed by derived streams.
+ */
+ explicit
+ basic_ios(basic_streambuf<_CharT, _Traits>* __sb)
+ : ios_base(), _M_tie(0), _M_fill(), _M_fill_init(false), _M_streambuf(0),
+ _M_ctype(0), _M_num_put(0), _M_num_get(0)
{ this->init(__sb); }
- virtual
+ /**
+ * @brief Empty.
+ *
+ * The destructor does nothing. More specifically, it does not
+ * destroy the streambuf held by rdbuf().
+ */
+ virtual
~basic_ios() { }
-
+
// Members:
+ /**
+ * @brief Fetches the current @e tied stream.
+ * @return A pointer to the tied stream, or NULL if the stream is
+ * not tied.
+ *
+ * A stream may be @e tied (or synchronized) to a second output
+ * stream. When this stream performs any I/O, the tied stream is
+ * first flushed. For example, @c std::cin is tied to @c std::cout.
+ */
basic_ostream<_CharT, _Traits>*
- tie() const
+ tie() const
{ return _M_tie; }
+ /**
+ * @brief Ties this stream to an output stream.
+ * @param __tiestr The output stream.
+ * @return The previously tied output stream, or NULL if the stream
+ * was not tied.
+ *
+ * This sets up a new tie; see tie() for more.
+ */
basic_ostream<_CharT, _Traits>*
tie(basic_ostream<_CharT, _Traits>* __tiestr)
{
- basic_ostream<_CharT, _Traits>* __old = _M_tie;
- _M_tie = __tiestr;
- return __old;
+ basic_ostream<_CharT, _Traits>* __old = _M_tie;
+ _M_tie = __tiestr;
+ return __old;
}
+ /**
+ * @brief Accessing the underlying buffer.
+ * @return The current stream buffer.
+ *
+ * This does not change the state of the stream.
+ */
basic_streambuf<_CharT, _Traits>*
- rdbuf() const
+ rdbuf() const
{ return _M_streambuf; }
- basic_streambuf<_CharT, _Traits>*
+ /**
+ * @brief Changing the underlying buffer.
+ * @param __sb The new stream buffer.
+ * @return The previous stream buffer.
+ *
+ * Associates a new buffer with the current stream, and clears the
+ * error state.
+ *
+ * Due to historical accidents which the LWG refuses to correct, the
+ * I/O library suffers from a design error: this function is hidden
+ * in derived classes by overrides of the zero-argument @c rdbuf(),
+ * which is non-virtual for hysterical raisins. As a result, you
+ * must use explicit qualifications to access this function via any
+ * derived class. For example:
+ *
+ * @code
+ * std::fstream foo; // or some other derived type
+ * std::streambuf* p = .....;
+ *
+ * foo.ios::rdbuf(p); // ios == basic_ios<char>
+ * @endcode
+ */
+ basic_streambuf<_CharT, _Traits>*
rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
+ /**
+ * @brief Copies fields of __rhs into this.
+ * @param __rhs The source values for the copies.
+ * @return Reference to this object.
+ *
+ * All fields of __rhs are copied into this object except that rdbuf()
+ * and rdstate() remain unchanged. All values in the pword and iword
+ * arrays are copied. Before copying, each callback is invoked with
+ * erase_event. After copying, each (new) callback is invoked with
+ * copyfmt_event. The final step is to copy exceptions().
+ */
basic_ios&
copyfmt(const basic_ios& __rhs);
- char_type
- fill() const
+ /**
+ * @brief Retrieves the @a empty character.
+ * @return The current fill character.
+ *
+ * It defaults to a space (' ') in the current locale.
+ */
+ char_type
+ fill() const
{
if (!_M_fill_init)
{
_M_fill = this->widen(' ');
_M_fill_init = true;
}
- return _M_fill;
+ return _M_fill;
}
- char_type
+ /**
+ * @brief Sets a new @a empty character.
+ * @param __ch The new character.
+ * @return The previous fill character.
+ *
+ * The fill character is used to fill out space when P+ characters
+ * have been requested (e.g., via setw), Q characters are actually
+ * used, and Q<P. It defaults to a space (' ') in the current locale.
+ */
+ char_type
fill(char_type __ch)
{
char_type __old = this->fill();
}
// Locales:
- locale
+ /**
+ * @brief Moves to a new locale.
+ * @param __loc The new locale.
+ * @return The previous locale.
+ *
+ * Calls @c ios_base::imbue(loc), and if a stream buffer is associated
+ * with this stream, calls that buffer's @c pubimbue(loc).
+ *
+ * Additional l10n notes are at
+ * http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
+ */
+ locale
imbue(const locale& __loc);
- char
- narrow(char_type __c, char __dfault) const;
+ /**
+ * @brief Squeezes characters.
+ * @param __c The character to narrow.
+ * @param __dfault The character to narrow.
+ * @return The narrowed character.
+ *
+ * Maps a character of @c char_type to a character of @c char,
+ * if possible.
+ *
+ * Returns the result of
+ * @code
+ * std::use_facet<ctype<char_type> >(getloc()).narrow(c,dfault)
+ * @endcode
+ *
+ * Additional l10n notes are at
+ * http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
+ */
+ char
+ narrow(char_type __c, char __dfault) const
+ { return __check_facet(_M_ctype).narrow(__c, __dfault); }
+
+ /**
+ * @brief Widens characters.
+ * @param __c The character to widen.
+ * @return The widened character.
+ *
+ * Maps a character of @c char to a character of @c char_type.
+ *
+ * Returns the result of
+ * @code
+ * std::use_facet<ctype<char_type> >(getloc()).widen(c)
+ * @endcode
+ *
+ * Additional l10n notes are at
+ * http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
+ */
+ char_type
+ widen(char __c) const
+ { return __check_facet(_M_ctype).widen(__c); }
- char_type
- widen(char __c) const;
-
protected:
// 27.4.5.1 basic_ios constructors
- basic_ios() : ios_base()
+ /**
+ * @brief Empty.
+ *
+ * The default constructor does nothing and is not normally
+ * accessible to users.
+ */
+ basic_ios()
+ : ios_base(), _M_tie(0), _M_fill(char_type()), _M_fill_init(false),
+ _M_streambuf(0), _M_ctype(0), _M_num_put(0), _M_num_get(0)
{ }
- void
+ /**
+ * @brief All setup is performed here.
+ *
+ * This is called from the public constructor. It is not virtual and
+ * cannot be redefined.
+ */
+ void
init(basic_streambuf<_CharT, _Traits>* __sb);
- bool
- _M_check_facet(const locale::facet* __f) const
- {
- if (!__f)
- __throw_bad_cast();
- return true;
- }
-
void
- _M_cache_facets(const locale& __loc);
+ _M_cache_locale(const locale& __loc);
};
-} // namespace std
-#ifdef _GLIBCPP_NO_TEMPLATE_EXPORT
-# define export
+_GLIBCXX_END_NAMESPACE_VERSION
+} // namespace
+
#include <bits/basic_ios.tcc>
-#endif
-#endif /* _CPP_BITS_BASICIOS_H */
+#endif /* _BASIC_IOS_H */
OSDN Git Service
