+2002-11-21 Phil Edwards <pme@gcc.gnu.org>
+
+ * docs/doxygen/TODO: Note change in clause 27 docs.
+ * include/bits/basic_ios.h, include/bits/fpos.h,
+ include/bits/ios_base.h, include/bits/stl_deque.h,
+ include/bits/stl_iterator_base_types.h, include/std/std_fstream.h,
+ include/std/std_iomanip.h, include/std/std_iosfwd.h,
+ include/std/std_iostream.h, include/std/std_istream.h,
+ include/std/std_ostream.h, include/std/std_sstream.h,
+ include/std/std_streambuf.h: Doxygenate all I/O entities.
+
2002-11-20 Benjamin Kosnik <bkoz@redhat.com>
Jonathan Lennox <lennox@cs.columbia.edu>
stream iterators
c25 stl_algo.h (lots of stuff)
c26 <complex>, <valarray>, stl_numeric.h[26.4], Note A
-c27 Untouched
+c27 ios_base callbacks and local storage
+ basic_ios::copyfmt()
+ std_streambuf.h's __copy_streambufs()
+ " " _M_* protected memfns (data has been done)
+ fstream and sstream protected members
backward/* Not scanned by doxygen. Should it be? Doubtful.
namespace std
{
// 27.4.5 Template class basic_ios
+ /**
+ * @brief Virtual base class for all stream classes.
+ *
+ * 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;
+ //@}
+
+ //@{
+ /**
+ * @if maint
+ * These are non-standard types.
+ * @endif
+ */
+ 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;
+ //@}
// Data members:
protected:
- basic_ostream<_CharT, _Traits>* _M_tie;
- mutable char_type _M_fill;
- mutable bool _M_fill_init;
- basic_streambuf<_CharT, _Traits>* _M_streambuf;
+ 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_fctype;
+ const __ctype_type* _M_fctype;
// From ostream.
- const __numput_type* _M_fnumput;
+ const __numput_type* _M_fnumput;
// From istream.
- const __numget_type* _M_fnumget;
+ const __numget_type* _M_fnumget;
public:
+ //@{
+ /**
+ * @brief The quick-and-easy status check.
+ *
+ * This allows you to write constructs such as
+ * "if (!a_stream) ..." and "while (a_stream) ..."
+ */
operator void*() const
{ return this->fail() ? 0 : const_cast<basic_ios*>(this); }
bool
operator!() const
{ return this->fail(); }
-
+ //@}
+
+ /**
+ * @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; }
+ /**
+ * @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);
+ /**
+ * @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); }
+ /**
+ * @brief Fast error checking.
+ * @return True if no error flags are set.
+ *
+ * A wrapper around rdstate.
+ */
bool
good() const
{ return this->rdstate() == 0; }
+ /**
+ * @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; }
+ /**
+ * @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; }
+ /**
+ * @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; }
+ /**
+ * @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; }
+ /**
+ * @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 flage 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);
+ _M_exception = __except;
+ this->clear(_M_streambuf_state);
}
// Constructor/destructor:
+ /**
+ * @brief Constructor performs initialization.
+ *
+ * The parameter is passed by derived streams.
+ */
explicit
basic_ios(basic_streambuf<_CharT, _Traits>* __sb) : ios_base()
{ this->init(__sb); }
+ /**
+ * @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
{ 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
{ return _M_streambuf; }
+ /**
+ * @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.
+ */
basic_streambuf<_CharT, _Traits>*
rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
+ /**
+ * @doctodo
+ */
basic_ios&
copyfmt(const basic_ios& __rhs);
+ /**
+ * @brief Retreives the "empty" character.
+ * @return The current fill character.
+ *
+ * It defaults to a space (' ') in the current locale.
+ */
char_type
fill() const
{
return _M_fill;
}
+ /**
+ * @brief Sets a new "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)
{
}
// Locales:
+ /**
+ * @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++/22_locale/howto.html
+ */
locale
imbue(const locale& __loc);
+ /**
+ * @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++/22_locale/howto.html
+ */
char
narrow(char_type __c, char __dfault) const;
+ /**
+ * @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++/22_locale/howto.html
+ */
char_type
widen(char __c) const;
protected:
// 27.4.5.1 basic_ios constructors
+ /**
+ * @brief Empty.
+ *
+ * The default constructor does nothing and is not normally
+ * accessible to users.
+ */
basic_ios() : ios_base()
{ }
+ /**
+ * @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);
{
// 27.4.1 Types
- // 27.4.3 Template class fpos
+ // [27.4.3] template class fpos
+ /**
+ * @doctodo
+ */
template<typename _StateT>
class fpos
{
_M_position(streamoff __off) { _M_off = __off; }
};
- // 27.2, paragraph 10 about fpos/char_traits circularity
+ /// 27.2, paragraph 10 about fpos/char_traits circularity
typedef fpos<mbstate_t> streampos;
# ifdef _GLIBCPP_USE_WCHAR_T
+ /// 27.2, paragraph 10 about fpos/char_traits circularity
typedef fpos<mbstate_t> wstreampos;
# endif
} // namespace std
enum _Ios_Seekdir { _M_ios_seekdir_end = 1L << 16 };
// 27.4.2 Class ios_base
+ /**
+ * @brief The very top of the I/O class hierarchy.
+ *
+ * This class defines everything that can be defined about I/O that does
+ * not depend on the type of characters being input or output. Most
+ * people will only see @c ios_base when they need to specify the full
+ * name of the various I/O flags (e.g., the openmodes).
+ */
class ios_base
{
public:
// 27.4.2.1.1 Class ios_base::failure
+ /// These are thrown to indicate problems. Doc me.
class failure : public exception
{
public:
};
// 27.4.2.1.2 Type ios_base::fmtflags
+ /**
+ * @brief This is a bitmask type.
+ *
+ * @c "_Ios_Fmtflags" is implementation-defined, but it is valid to
+ * perform bitwise operations on these values and expect the Right
+ * Thing to happen. Defined objects of type fmtflags are:
+ * - boolalpha
+ * - dec
+ * - fixed
+ * - hex
+ * - internal
+ * - left
+ * - oct
+ * - right
+ * - scientific
+ * - showbase
+ * - showpoint
+ * - showpos
+ * - skipws
+ * - unitbuf
+ * - uppercase
+ * - adjustfield
+ * - basefield
+ * - floatfield
+ */
typedef _Ios_Fmtflags fmtflags;
- // 27.4.2.1.2 Type fmtflags
+ /// Insert/extract @c bool in alphabetic rather than numeric format.
static const fmtflags boolalpha = fmtflags(__ios_flags::_S_boolalpha);
+ /// Converts integer input or generates integer output in decimal base.
static const fmtflags dec = fmtflags(__ios_flags::_S_dec);
+ /// Generate floating-point output in fixed-point notation.
static const fmtflags fixed = fmtflags(__ios_flags::_S_fixed);
+ /// Converts integer input or generates integer output in hexadecimal base.
static const fmtflags hex = fmtflags(__ios_flags::_S_hex);
+ /// Adds fill characters at a designated internal point in certain
+ /// generated output, or identical to @c right if no such point is
+ /// designated.
static const fmtflags internal = fmtflags(__ios_flags::_S_internal);
+ /// Adds fill characters on the right (final positions) of certain
+ /// generated output. (I.e., the thing you print is flush left.)
static const fmtflags left = fmtflags(__ios_flags::_S_left);
+ /// Converts integer input or generates integer output in octal base.
static const fmtflags oct = fmtflags(__ios_flags::_S_oct);
+ /// Adds fill characters on the left (initial positions) of certain
+ /// generated output. (I.e., the thing you print is flush right.)
static const fmtflags right = fmtflags(__ios_flags::_S_right);
+ /// Generates floating-point output in scientific notation.
static const fmtflags scientific = fmtflags(__ios_flags::_S_scientific);
+ /// Generates a prefix indicating the numeric base of generated integer
+ /// output.
static const fmtflags showbase = fmtflags(__ios_flags::_S_showbase);
+ /// Generates a decimal-point character unconditionally in generated
+ /// floating-point output.
static const fmtflags showpoint = fmtflags(__ios_flags::_S_showpoint);
+ /// Generates a + sign in non-negative generated numeric output.
static const fmtflags showpos = fmtflags(__ios_flags::_S_showpos);
+ /// Skips leading white space before certain input operations.
static const fmtflags skipws = fmtflags(__ios_flags::_S_skipws);
+ /// Flushes output after each output operation.
static const fmtflags unitbuf = fmtflags(__ios_flags::_S_unitbuf);
+ /// Replaces certain lowercase letters with their uppercase equivalents
+ /// in generated output.
static const fmtflags uppercase = fmtflags(__ios_flags::_S_uppercase);
+ /// A mask of left|right|internal. Useful for the 2-arg form of @c setf.
static const fmtflags adjustfield = fmtflags(__ios_flags::_S_adjustfield);
+ /// A mask of dec|oct|hex. Useful for the 2-arg form of @c setf.
static const fmtflags basefield = fmtflags(__ios_flags::_S_basefield);
+ /// A mask of scientific|fixed. Useful for the 2-arg form of @c setf.
static const fmtflags floatfield = fmtflags(__ios_flags::_S_floatfield);
// 27.4.2.1.3 Type ios_base::iostate
+ /**
+ * @brief This is a bitmask type.
+ *
+ * @c "_Ios_Iostate" is implementation-defined, but it is valid to
+ * perform bitwise operations on these values and expect the Right
+ * Thing to happen. Defined objects of type iostate are:
+ * - badbit
+ * - eofbit
+ * - failbit
+ * - goodbit
+ */
typedef _Ios_Iostate iostate;
+ /// Indicates a loss of integrity in an input or output sequence (such
+ /// as an irrecoverable read error from a file).
static const iostate badbit = iostate(__ios_flags::_S_badbit);
+ /// Indicates that an input operation reached the end of an input sequence.
static const iostate eofbit = iostate(__ios_flags::_S_eofbit);
+ /// Indicates that an input operation failed to read the expected
+ /// characters, or that an output operation failed to generate the
+ /// desired characters.
static const iostate failbit = iostate(__ios_flags::_S_failbit);
+ /// Indicates all is well.
static const iostate goodbit = iostate(0);
- // 27.4.2.1.4 Type openmode
+ // 27.4.2.1.4 Type ios_base::openmode
+ /**
+ * @brief This is a bitmask type.
+ *
+ * @c "_Ios_Openmode" is implementation-defined, but it is valid to
+ * perform bitwise operations on these values and expect the Right
+ * Thing to happen. Defined objects of type openmode are:
+ * - app
+ * - ate
+ * - binary
+ * - in
+ * - out
+ * - trunc
+ */
typedef _Ios_Openmode openmode;
+ /// Seek to end before each write.
static const openmode app = openmode(__ios_flags::_S_app);
+ /// Open and seek to end immediately after opening.
static const openmode ate = openmode(__ios_flags::_S_ate);
+ /// Perform input and output in binary mode (as opposed to text mode).
+ /// This is probably not what you think it is; see
+ /// http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#3 and
+ /// http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#7 for more.
static const openmode binary = openmode(__ios_flags::_S_bin);
+ /// Open for input. Default for @c ifstream and fstream.
static const openmode in = openmode(__ios_flags::_S_in);
+ /// Open for output. Default for @c ofstream and fstream.
static const openmode out = openmode(__ios_flags::_S_out);
+ /// Open for input. Default for @c ofstream.
static const openmode trunc = openmode(__ios_flags::_S_trunc);
- // 27.4.2.1.5 Type seekdir
+ // 27.4.2.1.5 Type ios_base::seekdir
+ /**
+ * @brief This is an enumerated type.
+ *
+ * @c "_Ios_Seekdir" is implementation-defined. Defined values
+ * of type seekdir are:
+ * - beg
+ * - cur, equivalent to @c SEEK_CUR in the C standard library.
+ * - end, equivalent to @c SEEK_END in the C standard library.
+ */
typedef _Ios_Seekdir seekdir;
+ /// Request a seek relative to the beginning of the stream.
static const seekdir beg = seekdir(0);
+ /// Request a seek relative to the current position within the sequence.
static const seekdir cur = seekdir(SEEK_CUR);
+ /// Request a seek relative to the current end of the sequence.
static const seekdir end = seekdir(SEEK_END);
#ifdef _GLIBCPP_DEPRECATED
#endif
// Callbacks;
+ /**
+ * @doctodo
+ */
enum event
{
erase_event,
copyfmt_event
};
+ /**
+ * @doctodo
+ */
typedef void (*event_callback) (event, ios_base&, int);
+ /**
+ * @doctodo
+ */
void
register_callback(event_callback __fn, int __index);
protected:
- // Data Members
+ //@{
+ /**
+ * @if maint
+ * ios_base data members (doc me)
+ * @endif
+ */
streamsize _M_precision;
streamsize _M_width;
fmtflags _M_flags;
iostate _M_exception;
iostate _M_streambuf_state;
+ //@}
// 27.4.2.6 Members for callbacks
// 27.4.2.6 ios_base callbacks
static bool _S_synced_with_stdio;
};
- // Fmtflags state:
+ // [27.4.2.2] fmtflags state functions
+ /**
+ * @brief Access to format flags.
+ * @return The format control flags for both input and output.
+ */
inline fmtflags
flags() const { return _M_flags; }
+ /**
+ * @brief Setting new format flags all at once.
+ * @param fmtfl The new flags to set.
+ * @return The previous format control flags.
+ *
+ * This function overwrites all the format flags with @a fmtfl.
+ */
inline fmtflags
flags(fmtflags __fmtfl)
{
return __old;
}
+ /**
+ * @brief Setting new format flags.
+ * @param fmtfl Additional flags to set.
+ * @return The previous format control flags.
+ *
+ * This function sets additional flags in format control. Flags that
+ * were previously set remain set.
+ */
inline fmtflags
setf(fmtflags __fmtfl)
{
return __old;
}
+ /**
+ * @brief Setting new format flags.
+ * @param fmtfl Additional flags to set.
+ * @param mask The flags mask for @a fmtfl.
+ * @return The previous format control flags.
+ *
+ * This function clears @a mask in the format flags, then sets
+ * @a fmtfl @c & @a mask. An example mask is @c ios_base::adjustfield.
+ */
inline fmtflags
setf(fmtflags __fmtfl, fmtflags __mask)
{
return __old;
}
+ /**
+ * @brief Clearing format flags.
+ * @param mask The flags to unset.
+ *
+ * This function clears @a mask in the format flags.
+ */
inline void
unsetf(fmtflags __mask) { _M_flags &= ~__mask; }
+ /**
+ * @brief Flags access.
+ * @return The precision to generate on certain output operations.
+ *
+ * @if maint
+ * Be careful if you try to give a definition of "precision" here; see
+ * DR 189.
+ * @endif
+ */
inline streamsize
precision() const { return _M_precision; }
+ /**
+ * @brief Changing flags.
+ * @param prec The new precision value.
+ * @return The previous value of precision().
+ */
inline streamsize
precision(streamsize __prec)
{
return __old;
}
+ /**
+ * @brief Flags access.
+ * @return The minimum field width to generate on output operations.
+ *
+ * "Minimum field width" refers to the number of characters.
+ */
inline streamsize
width() const { return _M_width; }
+ /**
+ * @brief Changing flags.
+ * @param wide The new width value.
+ * @return The previous value of width().
+ */
inline streamsize
width(streamsize __wide)
{
return __old;
}
+ // [27.4.2.4] ios_base static members
+ /**
+ * @brief Interaction with the standard C I/O objects.
+ * @param sync Whether to synchronize or not.
+ * @return True if the standard streams were previously synchronized.
+ *
+ * The synchronization referred to is @e only that between the standard
+ * C facilities (e.g., stdout) and the standard C++ objects (e.g.,
+ * cout). User-declared streams are unaffected. See
+ * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#8 for more.
+ */
static bool
sync_with_stdio(bool __sync = true);
- // Locales:
+ // [27.4.2.3] ios_base locale functions
+ /**
+ * @brief Setting a new locale.
+ * @param loc The new locale.
+ * @return The previous locale.
+ *
+ * Sets the new locale for this stream, and
+ * [XXX does something with callbacks].
+ */
locale
imbue(const locale& __loc);
+ /**
+ * @brief Locale access
+ * @return The locale currently in effect.
+ *
+ * If @c imbue(loc) has previously been called, then this function
+ * returns @c loc. Otherwise, it returns a copy of @c std::locale(),
+ * the global C++ locale.
+ */
inline locale
getloc() const { return _M_ios_locale; }
- // Storage:
+ // [27.4.2.5] ios_base storage functions
+ /**
+ * @doctodo
+ */
static int
xalloc() throw();
+ /**
+ * @doctodo
+ */
inline long&
iword(int __ix)
{
return __word._M_iword;
}
+ /**
+ * @doctodo
+ */
inline void*&
pword(int __ix)
{
}
// Destructor
+ /**
+ * Destroys local storage and
+ * [XXX does something with callbacks].
+ */
virtual ~ios_base();
protected:
#endif
};
- // 27.4.5.1 fmtflags manipulators:
+ // [27.4.5.1] fmtflags manipulators
+ /// Calls base.setf(ios_base::boolalpha).
inline ios_base&
boolalpha(ios_base& __base)
{
return __base;
}
+ /// Calls base.unsetf(ios_base::boolalpha).
inline ios_base&
noboolalpha(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::showbase).
inline ios_base&
showbase(ios_base& __base)
{
return __base;
}
+ /// Calls base.unsetf(ios_base::showbase).
inline ios_base&
noshowbase(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::showpoint).
inline ios_base&
showpoint(ios_base& __base)
{
return __base;
}
+ /// Calls base.unsetf(ios_base::showpoint).
inline ios_base&
noshowpoint(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::showpos).
inline ios_base&
showpos(ios_base& __base)
{
return __base;
}
+ /// Calls base.unsetf(ios_base::showpos).
inline ios_base&
noshowpos(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::skipws).
inline ios_base&
skipws(ios_base& __base)
{
return __base;
}
+ /// Calls base.unsetf(ios_base::skipws).
inline ios_base&
noskipws(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::uppercase).
inline ios_base&
uppercase(ios_base& __base)
{
return __base;
}
+ /// Calls base.unsetf(ios_base::uppercase).
inline ios_base&
nouppercase(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::unitbuf).
inline ios_base&
unitbuf(ios_base& __base)
{
return __base;
}
+ /// Calls base.unsetf(ios_base::unitbuf).
inline ios_base&
nounitbuf(ios_base& __base)
{
return __base;
}
- // 27.4.5.2 adjustfield anipulators:
+ // [27.4.5.2] adjustfield anipulators
+ /// Calls base.setf(ios_base::internal, ios_base::adjustfield).
inline ios_base&
internal(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::left, ios_base::adjustfield).
inline ios_base&
left(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::right, ios_base::adjustfield).
inline ios_base&
right(ios_base& __base)
{
return __base;
}
- // 27.4.5.3 basefield anipulators:
+ // [27.4.5.3] basefield anipulators
+ /// Calls base.setf(ios_base::dec, ios_base::basefield).
inline ios_base&
dec(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::hex, ios_base::basefield).
inline ios_base&
hex(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::oct, ios_base::basefield).
inline ios_base&
oct(ios_base& __base)
{
return __base;
}
- // 27.4.5.4 floatfield anipulators:
+ // [27.4.5.4] floatfield anipulators
+ /// Calls base.setf(ios_base::fixed, ios_base::floatfield).
inline ios_base&
fixed(ios_base& __base)
{
return __base;
}
+ /// Calls base.setf(ios_base::scientific, ios_base::floatfield).
inline ios_base&
scientific(ios_base& __base)
{
}
// called by the second initialize_dispatch above
- /** @{
+ //@{
+ /**
* @if maint
* @brief Fills the deque with whatever is in [first,last).
* @param first An input iterator.
void
_M_range_initialize(_ForwardIterator __first, _ForwardIterator __last,
forward_iterator_tag);
- /** @} */
+ //@}
/**
* @if maint
}
- /** @{
+ //@{
+ /**
* @if maint
* @brief Helper functions for push_* and pop_*.
* @endif
#endif
void _M_pop_back_aux();
void _M_pop_front_aux();
- /** @} */
+ //@}
// Internal insert functions follow. The *_aux functions do the actual
iterator _M_insert_aux(iterator __pos);
#endif
- /** @{
+ //@{
+ /**
* @if maint
* @brief Memory-handling helpers for the previous internal insert
* functions.
void
_M_new_elements_at_back(size_type __new_elements);
- /** @} */
+ //@}
- /** @{
+ //@{
+ /**
* @if maint
* @brief Memory-handling helpers for the major %map.
*
void
_M_reallocate_map(size_type __nodes_to_add, bool __add_at_front);
- /** @} */
+ //@}
};
namespace std
{
- /** @{
+ //@{
+ /**
* @defgroup iterator_tags Iterator Tags
* These are empty types, used to distinguish different iterators. The
* distinction is not made by what they contain, but simply by what they
namespace std
{
+ // [27.8.1.1] template class basic_filebuf
+ /**
+ * @brief The actual work of input and output (for files).
+ *
+ * This class associates both its input and output sequence with an
+ * external disk file, and maintains a joint file position for both
+ * sequences. Many of its sematics are described in terms of similar
+ * behavior in the Standard C Library's @c FILE streams.
+ */
template<typename _CharT, typename _Traits>
class basic_filebuf : public basic_streambuf<_CharT, _Traits>
{
typedef typename traits_type::pos_type pos_type;
typedef typename traits_type::off_type off_type;
- // Non-standard Types:
+ //@{
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
typedef basic_streambuf<char_type, traits_type> __streambuf_type;
typedef basic_filebuf<char_type, traits_type> __filebuf_type;
typedef __basic_file<char> __file_type;
typedef codecvt<char_type, char, __state_type> __codecvt_type;
typedef typename __codecvt_type::result __res_type;
typedef ctype<char_type> __ctype_type;
+ //@}
friend class ios_base; // For sync_with_stdio.
protected:
// Data Members:
// MT lock inherited from libio or other low-level io library.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__c_lock _M_lock;
// External buffer.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__file_type _M_file;
// Current and beginning state type for codecvt.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__state_type _M_state_cur;
__state_type _M_state_beg;
// Set iff _M_buf is allocated memory from _M_allocate_internal_buffer.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
bool _M_buf_allocated;
// XXX Needed?
// The position in the buffer corresponding to the external file
// pointer.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
char_type* _M_filepos;
public:
// Constructors/destructor:
+ /**
+ * @brief Does not open any files.
+ *
+ * The default constructor initializes the parent class using its
+ * own default ctor.
+ */
basic_filebuf();
+ /**
+ * @brief The destructor closes the file first.
+ */
virtual
~basic_filebuf()
{
}
// Members:
+ /**
+ * @brief Returns true if the external file is open.
+ */
bool
is_open() const { return _M_file.is_open(); }
+ /**
+ * @brief Opens an external file.
+ * @param s The name of the file.
+ * @param mode The open mode flags.
+ * @return @c this on success, NULL on failure
+ *
+ * If a file is already open, this function immediately fails.
+ * Otherwise it tries to open the file named @a s using the flags
+ * given in @a mode.
+ *
+ * [Table 92 gives the relation between openmode combinations and the
+ * equivalent fopen() flags, but the table has not been copied yet.]
+ */
__filebuf_type*
open(const char* __s, ios_base::openmode __mode);
+ /**
+ * @brief Closes the currently associated file.
+ * @return @c this on success, NULL on failure
+ *
+ * If no file is currently open, this function immediately fails.
+ *
+ * If a "put buffer area" exists, @c overflow(eof) is called to flush
+ * all the characters. The file is then closed.
+ *
+ * If any operations fail, this function also fails.
+ */
__filebuf_type*
close();
protected:
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
void
_M_allocate_internal_buffer();
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
void
_M_destroy_internal_buffer();
- // Overridden virtual functions:
+ // [27.8.1.4] overridden virtual functions
+ // [documentation is inherited]
virtual streamsize
showmanyc();
// the underflow() case in order to maintain synchronization. So
// instead of calling underflow() from uflow(), we create a common
// subroutine to do the real work.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
int_type
_M_underflow_common(bool __bump);
+ // [documentation is inherited]
virtual int_type
underflow() { return _M_underflow_common(false); }
+ // [documentation is inherited]
virtual int_type
uflow() { return _M_underflow_common(true); }
+ // [documentation is inherited]
virtual int_type
pbackfail(int_type __c = _Traits::eof());
// this in actuality be a helper function that checks for the
// eccentricities of this implementation, and then call
// overflow() if indeed the buffer is full.
+
+ // [documentation is inherited]
virtual int_type
overflow(int_type __c = _Traits::eof());
// character c.
// 27.5.2.4.5
// Consume some sequence of the characters in the pending sequence.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
int_type
_M_really_overflow(int_type __c = _Traits::eof());
// Convert internal byte sequence to external, char-based
// sequence via codecvt.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
void
_M_convert_to_external(char_type*, streamsize, streamsize&, streamsize&);
+ /**
+ * @brief Manipulates the buffer.
+ * @param s Pointer to a buffer area.
+ * @param n Size of @a s.
+ * @return @c this
+ *
+ * If no file has been opened, and both @a s and @a n are zero, then
+ * the stream becomes unbuffered. Otherwise, @c s is used as a
+ * buffer; see
+ * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2
+ * for more.
+ */
virtual __streambuf_type*
setbuf(char_type* __s, streamsize __n);
+ // [documentation is inherited]
virtual pos_type
seekoff(off_type __off, ios_base::seekdir __way,
ios_base::openmode __mode = ios_base::in | ios_base::out);
+ // [documentation is inherited]
virtual pos_type
seekpos(pos_type __pos,
ios_base::openmode __mode = ios_base::in | ios_base::out);
+ // [documentation is inherited]
virtual int
sync()
{
return 0;
}
+ // [documentation is inherited]
virtual void
imbue(const locale& __loc);
+ // [documentation is inherited]
virtual streamsize
xsgetn(char_type* __s, streamsize __n)
{
return __ret;
}
+ // [documentation is inherited]
virtual streamsize
xsputn(const char_type* __s, streamsize __n)
{
return __streambuf_type::xsputn(__s, __n);
}
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
void
_M_output_unshift();
// internal buffer does not truly reflect the contents of the
// external buffer. At this point, for whatever reason, it is in
// an indeterminate state.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
void
_M_set_indeterminate(void)
{
_M_filepos = _M_buf;
}
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
void
_M_set_determinate(off_type __off)
{
_M_filepos = _M_buf + __off;
}
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
bool
_M_is_indeterminate(void)
{
}
};
- // Explicit specializations.
+ // Explicit specializations, defined in src/fstream.cc.
template<>
basic_filebuf<char>::int_type
basic_filebuf<char>::_M_underflow_common(bool __bump);
basic_filebuf<wchar_t>::_M_underflow_common(bool __bump);
#endif
- // 27.8.1.5 Template class basic_ifstream
+ // [27.8.1.5] Template class basic_ifstream
/**
- * Derivation of general input streams, specific to files.
+ * @brief Controlling input for files.
+ *
+ * This class supports reading from named files, using the inherited
+ * functions from std::basic_istream. To control the associated
+ * sequence, an instance of std::basic_filebuf is used, which this page
+ * refers to as @c sb.
*/
template<typename _CharT, typename _Traits>
class basic_ifstream : public basic_istream<_CharT, _Traits>
typedef basic_istream<char_type, traits_type> __istream_type;
private:
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__filebuf_type _M_filebuf;
public:
- // Constructors/Destructors:
- /** Default constructor. Create an input file stream. */
+ // Constructors/Destructors:
+ /**
+ * @brief Default constructor.
+ *
+ * Initializes @c sb using its default constructor, and passes
+ * @c &sb to the base class initializer. Does not open any files
+ * (you haven't given it a filename to open).
+ */
basic_ifstream()
: __istream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
- * @brief Create an input file stream.
- * @param s Null terminated string specifying filename.
+ * @brief Create an input file stream.
+ * @param s Null terminated string specifying the filename.
* @param mode Open file in specified mode (see std::ios_base).
*
+ * @c ios_base::in is automatically included in @a mode.
+ *
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
this->open(__s, __mode);
}
+ /**
+ * @brief The destructor does nothing.
+ *
+ * The file is closed by the filebuf object, not the formatting
+ * stream.
+ */
~basic_ifstream()
{ }
// Members:
/**
- * @brief Get a pointer to the file stream's buffer.
- * @return Pointer to basic_filebuf.
+ * @brief Accessing the underlying buffer.
+ * @return The current basic_filebuf buffer.
+ *
+ * This hides both signatures of std::basic_ios::rdbuf().
*/
__filebuf_type*
rdbuf() const
{ return const_cast<__filebuf_type*>(&_M_filebuf); }
+ /**
+ * @brief Wrapper to test for an open file.
+ * @return @c rdbuf()->is_open()
+ */
bool
is_open() { return _M_filebuf.is_open(); }
+ /**
+ * @brief Opens an external file.
+ * @param s The name of the file.
+ * @param mode The open mode flags.
+ *
+ * Calls @c std::basic_filebuf::open(s,mode|in). If that function
+ * fails, @c failbit is set in the stream's error state.
+ *
+ * Tip: When using std::string to hold the filename, you must use
+ * .c_str() before passing it to this constructor.
+ */
void
open(const char* __s, ios_base::openmode __mode = ios_base::in)
{
this->setstate(ios_base::failbit);
}
- /** Close the file. */
+ /**
+ * @brief Close the file.
+ *
+ * Calls @c std::basic_filebuf::close(). If that function
+ * fails, @c failbit is set in the stream's error state.
+ */
void
close()
{
};
- // 27.8.1.8 Template class basic_ofstream
+ // [27.8.1.8] Template class basic_ofstream
/**
- * Derivation of general output streams, specific to files.
+ * @brief Controlling output for files.
+ *
+ * This class supports reading from named files, using the inherited
+ * functions from std::basic_ostream. To control the associated
+ * sequence, an instance of std::basic_filebuf is used, which this page
+ * refers to as @c sb.
*/
template<typename _CharT, typename _Traits>
class basic_ofstream : public basic_ostream<_CharT,_Traits>
typedef basic_ostream<char_type, traits_type> __ostream_type;
private:
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__filebuf_type _M_filebuf;
public:
// Constructors:
- /** Default constructor for output file_stream. */
+ /**
+ * @brief Default constructor.
+ *
+ * Initializes @c sb using its default constructor, and passes
+ * @c &sb to the base class initializer. Does not open any files
+ * (you haven't given it a filename to open).
+ */
basic_ofstream()
: __ostream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
- * @brief Create an output stream.
- * @param s Null terminated string specifying filename.
+ * @brief Create an output file stream.
+ * @param s Null terminated string specifying the filename.
* @param mode Open file in specified mode (see std::ios_base).
*
+ * @c ios_base::out|ios_base::trunc is automatically included in
+ * @a mode.
+ *
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
this->open(__s, __mode);
}
+ /**
+ * @brief The destructor does nothing.
+ *
+ * The file is closed by the filebuf object, not the formatting
+ * stream.
+ */
~basic_ofstream()
{ }
// Members:
/**
- * @brief Get a pointer to the file stream's buffer.
- * @return Pointer to basic_filebuf.
+ * @brief Accessing the underlying buffer.
+ * @return The current basic_filebuf buffer.
+ *
+ * This hides both signatures of std::basic_ios::rdbuf().
*/
__filebuf_type*
rdbuf() const
{ return const_cast<__filebuf_type*>(&_M_filebuf); }
/**
- * @brief Query to see if file stream is open.
- * @return True if stream is open.
+ * @brief Wrapper to test for an open file.
+ * @return @c rdbuf()->is_open()
*/
bool
is_open() { return _M_filebuf.is_open(); }
/**
- * @brief Specify a file to open for output.
- * @param s Null terminated string specifying filename.
- * @param mode Mode in which to open file (see std::ios_base).
+ * @brief Opens an external file.
+ * @param s The name of the file.
+ * @param mode The open mode flags.
+ *
+ * Calls @c std::basic_filebuf::open(s,mode|out|trunc). If that
+ * function fails, @c failbit is set in the stream's error state.
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
this->setstate(ios_base::failbit);
}
- /** Close the file stream. */
+ /**
+ * @brief Close the file.
+ *
+ * Calls @c std::basic_filebuf::close(). If that function
+ * fails, @c failbit is set in the stream's error state.
+ */
void
close()
{
};
- // 27.8.1.11 Template class basic_fstream
+ // [27.8.1.11] Template class basic_fstream
/**
- * Derivation of general input/output streams, specific to files.
+ * @brief Controlling intput and output for files.
+ *
+ * This class supports reading from and writing to named files, using
+ * the inherited functions from std::basic_iostream. To control the
+ * associated sequence, an instance of std::basic_filebuf is used, which
+ * this page refers to as @c sb.
*/
template<typename _CharT, typename _Traits>
class basic_fstream : public basic_iostream<_CharT, _Traits>
typedef basic_iostream<char_type, traits_type> __iostream_type;
private:
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__filebuf_type _M_filebuf;
public:
// Constructors/destructor:
- /** Default constructor. Create a file stream. */
+ /**
+ * @brief Default constructor.
+ *
+ * Initializes @c sb using its default constructor, and passes
+ * @c &sb to the base class initializer. Does not open any files
+ * (you haven't given it a filename to open).
+ */
basic_fstream()
: __iostream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
- * @brief Create an input/output stream.
- * @param s Null terminated string specifying filename.
+ * @brief Create an input/output file stream.
+ * @param s Null terminated string specifying the filename.
* @param mode Open file in specified mode (see std::ios_base).
*
* Tip: When using std::string to hold the filename, you must use
this->open(__s, __mode);
}
+ /**
+ * @brief The destructor does nothing.
+ *
+ * The file is closed by the filebuf object, not the formatting
+ * stream.
+ */
~basic_fstream()
{ }
// Members:
/**
- * @brief Get a pointer to the file stream's buffer.
- * @return Pointer to basic_filebuf.
+ * @brief Accessing the underlying buffer.
+ * @return The current basic_filebuf buffer.
+ *
+ * This hides both signatures of std::basic_ios::rdbuf().
*/
__filebuf_type*
rdbuf() const
{ return const_cast<__filebuf_type*>(&_M_filebuf); }
/**
- * @brief Query to see if file stream is open.
- * @return True if stream is open.
+ * @brief Wrapper to test for an open file.
+ * @return @c rdbuf()->is_open()
*/
bool
is_open() { return _M_filebuf.is_open(); }
/**
- * @brief Specify a file to open for input and/or output.
- * @param s Null terminated string specifying filename.
- * @param mode Mode in which to open file (see std::ios_base).
+ * @brief Opens an external file.
+ * @param s The name of the file.
+ * @param mode The open mode flags.
+ *
+ * Calls @c std::basic_filebuf::open(s,mode). If that
+ * function fails, @c failbit is set in the stream's error state.
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
setstate(ios_base::failbit);
}
- /** Close the file stream. */
+ /**
+ * @brief Close the file.
+ *
+ * Calls @c std::basic_filebuf::close(). If that function
+ * fails, @c failbit is set in the stream's error state.
+ */
void
close()
{
namespace std
{
+ // [27.6.3] standard manipulators
+ // Also see DR 183.
+
struct _Resetiosflags { ios_base::fmtflags _M_mask; };
+ /**
+ * @brief Manipulator for @c setf.
+ * @param mask A format flags mask.
+ *
+ * Sent to a stream object, this manipulator resets the specified flags,
+ * via @e stream.setf(0,mask).
+ */
inline _Resetiosflags
resetiosflags(ios_base::fmtflags __mask)
{
struct _Setiosflags { ios_base::fmtflags _M_mask; };
+ /**
+ * @brief Manipulator for @c setf.
+ * @param mask A format flags mask.
+ *
+ * Sent to a stream object, this manipulator sets the format flags
+ * to @a mask.
+ */
inline _Setiosflags
setiosflags(ios_base::fmtflags __mask)
{
struct _Setbase { int _M_base; };
+ /**
+ * @brief Manipulator for @c setf.
+ * @param base A numeric base.
+ *
+ * Sent to a stream object, this manipulator changes the
+ * @c ios_base::basefield flags to @c oct, @c dec, or @c hex when @a base
+ * is 8, 10, or 16, accordingly, and to 0 if @a base is any other value.
+ */
inline _Setbase
setbase(int __base)
{
template<typename _CharT>
struct _Setfill { _CharT _M_c; };
+ /**
+ * @brief Manipulator for @c fill.
+ * @param c The new fill character.
+ *
+ * Sent to a stream object, this manipulator calls @c fill(c) for that
+ * object.
+ */
template<typename _CharT>
inline _Setfill<_CharT>
setfill(_CharT __c)
struct _Setprecision { int _M_n; };
+ /**
+ * @brief Manipulator for @c precision.
+ * @param n The new precision.
+ *
+ * Sent to a stream object, this manipulator calls @c precision(n) for
+ * that object.
+ */
inline _Setprecision
setprecision(int __n)
{
struct _Setw { int _M_n; };
+ /**
+ * @brief Manipulator for @c width.
+ * @param n The new width.
+ *
+ * Sent to a stream object, this manipulator calls @c width(n) for
+ * that object.
+ */
inline _Setw
setw(int __n)
{
class ios_base;
#endif
- typedef basic_ios<char> ios;
- typedef basic_streambuf<char> streambuf;
- typedef basic_istream<char> istream;
- typedef basic_ostream<char> ostream;
- typedef basic_iostream<char> iostream;
- typedef basic_stringbuf<char> stringbuf;
- typedef basic_istringstream<char> istringstream;
- typedef basic_ostringstream<char> ostringstream;
- typedef basic_stringstream<char> stringstream;
- typedef basic_filebuf<char> filebuf;
- typedef basic_ifstream<char> ifstream;
- typedef basic_ofstream<char> ofstream;
- typedef basic_fstream<char> fstream;
+ /**
+ * @defgroup s27_2_iosfwd I/O Forward Declarations
+ *
+ * Nearly all of the I/O classes are parameterized on the type of
+ * characters they read and write. (The major exception is ios_base at
+ * the top of the hierarchy.) This is a change from pre-Standard
+ * streams, which were not templates.
+ *
+ * For ease of use and compatibility, all of the basic_* I/O-related
+ * classes are given typedef names for both of the builtin character
+ * widths (wide and narrow). The typedefs are the same as the
+ * pre-Standard names, for example:
+ *
+ * @code
+ * typedef basic_ifstream<char> ifstream;
+ * @endcode
+ *
+ * Because properly forward-declaring these classes can be difficult, you
+ * should not do it yourself. Instead, include the <iosfwd>
+ * header, which contains only declarations of all the I/O classes as
+ * well as the typedefs. Trying to forward-declare the typedefs
+ * themselves (e.g., "class ostream;") is not valid ISO C++.
+ *
+ * For more specific declarations, see
+ * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#10
+ *
+ * @{
+ */
+ typedef basic_ios<char> ios; ///< @isiosfwd
+ typedef basic_streambuf<char> streambuf; ///< @isiosfwd
+ typedef basic_istream<char> istream; ///< @isiosfwd
+ typedef basic_ostream<char> ostream; ///< @isiosfwd
+ typedef basic_iostream<char> iostream; ///< @isiosfwd
+ typedef basic_stringbuf<char> stringbuf; ///< @isiosfwd
+ typedef basic_istringstream<char> istringstream; ///< @isiosfwd
+ typedef basic_ostringstream<char> ostringstream; ///< @isiosfwd
+ typedef basic_stringstream<char> stringstream; ///< @isiosfwd
+ typedef basic_filebuf<char> filebuf; ///< @isiosfwd
+ typedef basic_ifstream<char> ifstream; ///< @isiosfwd
+ typedef basic_ofstream<char> ofstream; ///< @isiosfwd
+ typedef basic_fstream<char> fstream; ///< @isiosfwd
#ifdef _GLIBCPP_USE_WCHAR_T
- typedef basic_ios<wchar_t> wios;
- typedef basic_streambuf<wchar_t> wstreambuf;
- typedef basic_istream<wchar_t> wistream;
- typedef basic_ostream<wchar_t> wostream;
- typedef basic_iostream<wchar_t> wiostream;
- typedef basic_stringbuf<wchar_t> wstringbuf;
- typedef basic_istringstream<wchar_t> wistringstream;
- typedef basic_ostringstream<wchar_t> wostringstream;
- typedef basic_stringstream<wchar_t> wstringstream;
- typedef basic_filebuf<wchar_t> wfilebuf;
- typedef basic_ifstream<wchar_t> wifstream;
- typedef basic_ofstream<wchar_t> wofstream;
- typedef basic_fstream<wchar_t> wfstream;
+ typedef basic_ios<wchar_t> wios; ///< @isiosfwd
+ typedef basic_streambuf<wchar_t> wstreambuf; ///< @isiosfwd
+ typedef basic_istream<wchar_t> wistream; ///< @isiosfwd
+ typedef basic_ostream<wchar_t> wostream; ///< @isiosfwd
+ typedef basic_iostream<wchar_t> wiostream; ///< @isiosfwd
+ typedef basic_stringbuf<wchar_t> wstringbuf; ///< @isiosfwd
+ typedef basic_istringstream<wchar_t> wistringstream; ///< @isiosfwd
+ typedef basic_ostringstream<wchar_t> wostringstream; ///< @isiosfwd
+ typedef basic_stringstream<wchar_t> wstringstream; ///< @isiosfwd
+ typedef basic_filebuf<wchar_t> wfilebuf; ///< @isiosfwd
+ typedef basic_ifstream<wchar_t> wifstream; ///< @isiosfwd
+ typedef basic_ofstream<wchar_t> wofstream; ///< @isiosfwd
+ typedef basic_fstream<wchar_t> wfstream; ///< @isiosfwd
#endif
+ /** @} */
} // namespace std
#endif
namespace std
{
- extern istream cin;
- extern ostream cout;
- extern ostream cerr;
- extern ostream clog;
+ /**
+ * @name Standard Stream Objects
+ *
+ * The <iostream> header declares the eight <em>standard stream
+ * objects</em>. For other declarations, see
+ * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#10 and the
+ * @link s27_2_iosfwd I/O forward declarations @endlink
+ *
+ * They are required by default to cooperate with the global C library's
+ * @c FILE streams, and to be available during program startup and
+ * termination. For more information, see the HOWTO linked to above.
+ */
+ //@{
+ extern istream cin; ///< Linked to standard input
+ extern ostream cout; ///< Linked to standard output
+ extern ostream cerr; ///< Linked to standard error (unbuffered)
+ extern ostream clog; ///< Linked to standard error (buffered)
#ifdef _GLIBCPP_USE_WCHAR_T
- extern wistream wcin;
- extern wostream wcout;
- extern wostream wcerr;
- extern wostream wclog;
+ extern wistream wcin; ///< Linked to standard input
+ extern wostream wcout; ///< Linked to standard output
+ extern wostream wcerr; ///< Linked to standard error (unbuffered)
+ extern wostream wclog; ///< Linked to standard error (buffered)
#endif
+ //@}
// For construction of filebuffers for cout, cin, cerr, clog et. al.
static ios_base::Init __ioinit;
namespace std
{
- // 27.6.1.1 Template class basic_istream
+ // [27.6.1.1] Template class basic_istream
+ /**
+ * @brief Controlling input.
+ *
+ * This is the base class for all input streams. It provides text
+ * formatting of all builtin types, and communicates with any class
+ * derived from basic_streambuf to do the actual input.
+ */
template<typename _CharT, typename _Traits>
class basic_istream : virtual public basic_ios<_CharT, _Traits>
{
protected:
// Data Members:
+ /**
+ * @if maint
+ * The number of characters extracted in the previous unformatted
+ * function; see gcount().
+ * @endif
+ */
streamsize _M_gcount;
public:
- // 27.6.1.1.1 Constructor/destructor:
+ // [27.6.1.1.1] constructor/destructor
+ /**
+ * @brief Base constructor.
+ *
+ * This ctor is almost never called by the user directly, rather from
+ * derived classes' initialization lists, which pass a pointer to
+ * their own stream buffer.
+ */
explicit
basic_istream(__streambuf_type* __sb)
{
_M_gcount = streamsize(0);
}
+ /**
+ * @brief Base destructor.
+ *
+ * This does very little apart from providing a virtual base dtor.
+ */
virtual
~basic_istream()
{ _M_gcount = streamsize(0); }
- // 27.6.1.1.2 Prefix/suffix:
+ // [27.6.1.1.2] prefix/suffix
class sentry;
friend class sentry;
- // 27.6.1.2 Formatted input:
- // 27.6.1.2.3 basic_istream::operator>>
+ // [27.6.1.2] formatted input
+ // [27.6.1.2.3] basic_istream::operator>>
+ //@{
+ /**
+ * @brief Interface for manipulators.
+ *
+ * Manuipulators such as @c std::ws and @c std::dec use these
+ * functions in constructs like "std::cin >> std::ws". For more
+ * information, see the iomanip header.
+ */
__istream_type&
operator>>(__istream_type& (*__pf)(__istream_type&));
__istream_type&
operator>>(ios_base& (*__pf)(ios_base&));
+ //@}
- // 27.6.1.2.2 Arithmetic Extractors
+ // [27.6.1.2.2] arithmetic extractors
+ /**
+ * @name Arithmetic Extractors
+ *
+ * All the @c operator>> functions (aka <em>formatted input
+ * functions</em>) have some common behavior. Each starts by
+ * constructing a temporary object of type std::basic_istream::sentry
+ * with the second argument (noskipws) set to false. This has several
+ * effects, concluding with the setting of a status flag; see the
+ * sentry documentation for more.
+ *
+ * If the sentry status is good, the function tries to extract
+ * whatever data is appropriate for the type of the argument.
+ *
+ * If an exception is thrown during extraction, ios_base::badbit
+ * will be turned on in the stream's error state without causing an
+ * ios_base::failure to be thrown. The original exception will then
+ * be rethrown.
+ */
+ //@{
+ /**
+ * @brief Basic arithmetic extractors
+ * @param A variable of builtin type.
+ * @return @c *this if successful
+ *
+ * These functions use the stream's current locale (specifically, the
+ * @c num_get facet) to parse the input data.
+ */
__istream_type&
operator>>(bool& __n);
__istream_type&
operator>>(void*& __p);
+ /**
+ * @brief Extracting into another streambuf.
+ * @param sb A pointer to a streambuf
+ *
+ * This function behaves like one of the basic arithmetic extractors,
+ * in that it also constructs a sentry onject and has the same error
+ * handling behavior.
+ *
+ * If @a sb is NULL, the stream will set failbit in its error state.
+ *
+ * Characters are extracted from this stream and inserted into the
+ * @a sb streambuf until one of the following occurs:
+ *
+ * - the input stream reaches end-of-file,
+ * - insertion into the output buffer fails (in this case, the
+ * character that would have been inserted is not extracted), or
+ * - an exception occurs (and in this case is caught)
+ *
+ * If the function inserts no characters, failbit is set.
+ */
__istream_type&
operator>>(__streambuf_type* __sb);
+ //@}
- // 27.6.1.3 Unformatted input:
+ // [27.6.1.3] unformatted input
+ /**
+ * @brief Character counting
+ * @return The number of characters extracted by the previous
+ * unformatted input function dispatched for this stream.
+ */
inline streamsize
- gcount(void) const
+ gcount() const
{ return _M_gcount; }
+ /**
+ * @name Unformatted Input Functions
+ *
+ * All the unformatted input functions have some common behavior.
+ * Each starts by constructing a temporary object of type
+ * std::basic_istream::sentry with the second argument (noskipws)
+ * set to true. This has several effects, concluding with the
+ * setting of a status flag; see the sentry documentation for more.
+ *
+ * If the sentry status is good, the function tries to extract
+ * whatever data is appropriate for the type of the argument.
+ *
+ * The number of characters extracted is stored for later retrieval
+ * by gcount().
+ *
+ * If an exception is thrown during extraction, ios_base::badbit
+ * will be turned on in the stream's error state without causing an
+ * ios_base::failure to be thrown. The original exception will then
+ * be rethrown.
+ */
+ //@{
+ /**
+ * @brief Simple extraction.
+ * @return A character, or eof().
+ *
+ * Tries to extract a character. If none are available, sets failbit
+ * and returns traits::eof().
+ */
int_type
- get(void);
-
+ get();
+
+ /**
+ * @brief Simple extraction.
+ * @param c The character in which to store data.
+ * @return *this
+ *
+ * Tries to extract a character and store it in @a c. If none are
+ * available, sets failbit and returns traits::eof().
+ *
+ * @note This function is not overloaded on signed char and
+ * unsigned char.
+ */
__istream_type&
get(char_type& __c);
+ /**
+ * @brief Simple multiple-character extraction.
+ * @param s Pointer to an array.
+ * @param n Maximum number of characters to store in @a s.
+ * @param delim A "stop" character.
+ * @return *this
+ *
+ * Characters are extracted and stored into @a s until one of the
+ * following happens:
+ *
+ * - @c n-1 characters are stored
+ * - the input sequence reaches EOF
+ * - the next character equals @a delim, in which case the character
+ * is not extracted
+ *
+ * If no characters are stored, failbit is set in the stream's error
+ * state.
+ *
+ * In any case, a null character is stored into the next location in
+ * the array.
+ *
+ * @note This function is not overloaded on signed char and
+ * unsigned char.
+ */
__istream_type&
get(char_type* __s, streamsize __n, char_type __delim);
+ /**
+ * @brief Simple multiple-character extraction.
+ * @param s Pointer to an array.
+ * @param n Maximum number of characters to store in @a s.
+ * @return *this
+ *
+ * Returns @c get(s,n,widen('\n')).
+ */
inline __istream_type&
get(char_type* __s, streamsize __n)
{ return this->get(__s, __n, this->widen('\n')); }
+ /**
+ * @brief Extraction into another streambuf.
+ * @param sb A streambuf in which to store data.
+ * @param delim A "stop" character.
+ * @return *this
+ *
+ * Characters are extracted and inserted into @a sb until one of the
+ * following happens:
+ *
+ * - the input sequence reaches EOF
+ * - insertion into the output buffer fails (in this case, the
+ * character that would have been inserted is not extracted)
+ * - the next character equals @a delim (in this case, the character
+ * is not extracted)
+ * - an exception occurs (and in this case is caught)
+ *
+ * If no characters are stored, failbit is set in the stream's error
+ * state.
+ */
__istream_type&
get(__streambuf_type& __sb, char_type __delim);
+ /**
+ * @brief Extraction into another streambuf.
+ * @param sb A streambuf in which to store data.
+ * @return *this
+ *
+ * Returns @c get(sb,widen('\n')).
+ */
inline __istream_type&
get(__streambuf_type& __sb)
{ return this->get(__sb, this->widen('\n')); }
+ /**
+ * @brief String extraction.
+ * @param s A character array in which to store the data.
+ * @param n Maximum number of characters to extract.
+ * @param delim A "stop" character.
+ * @return *this
+ *
+ * Extracts and stores characters into @a s until one of the
+ * following happens. Note that these criteria are required to be
+ * tested in the order listed here, to allow an input line to exactly
+ * fill the @a s array without setting failbit.
+ *
+ * -# the input sequence reaches end-of-file, in which case eofbit
+ * is set in the stream error state
+ * -# the next character equals @c delim, in which case the character
+ * is extracted (and therefore counted in @c gcount()) but not stored
+ * -# @c n-1 characters are stored, in which case failbit is set
+ * in the stream error state
+ *
+ * If no characters are extracted, failbit is set. (An empty line of
+ * input should therefore not cause failbit to be set.)
+ *
+ * In any case, a null character is stored in the next location in
+ * the array.
+ */
__istream_type&
getline(char_type* __s, streamsize __n, char_type __delim);
+ /**
+ * @brief String extraction.
+ * @param s A character array in which to store the data.
+ * @param n Maximum number of characters to extract.
+ * @return *this
+ *
+ * Returns @c getline(s,n,widen('\n')).
+ */
inline __istream_type&
getline(char_type* __s, streamsize __n)
{ return this->getline(__s, __n, this->widen('\n')); }
+ /**
+ * @brief Discarding characters
+ * @param n Number of characters to discard.
+ * @param delim A "stop" character.
+ * @return *this
+ *
+ * Extracts characters and throws them away until one of the
+ * following happens:
+ * - if @a n @c != @c std::numeric_limits<int>::max(), @a n
+ * characters are extracted
+ * - the input sequence reaches end-of-file
+ * - the next character equals @a delim (in this case, the character
+ * is extracted); note that this condition will never occur if
+ * @a delim equals @c traits::eof().
+ */
__istream_type&
ignore(streamsize __n = 1, int_type __delim = traits_type::eof());
+ /**
+ * @brief Looking ahead in the stream
+ * @return The next character, or eof().
+ *
+ * If, after constructing the sentry object, @c good() is false,
+ * returns @c traits::eof(). Otherwise reads but does not extract
+ * the next input character.
+ */
int_type
- peek(void);
+ peek();
+ /**
+ * @brief Extraction without delimiters.
+ * @param s A character array.
+ * @param n Maximum number of characters to store.
+ * @return *this
+ *
+ * If the stream state is @c good(), extracts characters and stores
+ * them into @a s until one of the following happens:
+ * - @a n characters are stored
+ * - the input sequence reaches end-of-file, in which case the error
+ * state is set to @c failbit|eofbit.
+ *
+ * @note This function is not overloaded on signed char and
+ * unsigned char.
+ */
__istream_type&
read(char_type* __s, streamsize __n);
+ /**
+ * @brief Extraction until the buffer is exhausted, but no more.
+ * @param s A character array.
+ * @param n Maximum number of characters to store.
+ * @return The number of characters extracted.
+ *
+ * Extracts characters and stores them into @a s depending on the
+ * number of characters remaining in the streambuf's buffer,
+ * @c rdbuf()->in_avail(), called @c A here:
+ * - if @c A @c == @c -1, sets eofbit and extracts no characters
+ * - if @c A @c == @c 0, extracts no characters
+ * - if @c A @c > @c 0, extracts @c min(A,n)
+ *
+ * The goal is to empty the current buffer, and to not request any
+ * more from the external input sequence controlled by the streambuf.
+ */
streamsize
readsome(char_type* __s, streamsize __n);
+ /**
+ * @brief Unextracting a single character.
+ * @param c The character to push back into the input stream.
+ * @return *this
+ *
+ * If @c rdbuf() is not null, calls @c rdbuf()->sputbackc(c).
+ *
+ * If @c rdbuf() is null or if @c sputbackc() fails, sets badbit in
+ * the error state.
+ *
+ * @note Since no characters are extracted, the next call to
+ * @c gcount() will return 0, as required by DR 60.
+ *
+ * @if maint
+ * FIXME We don't comply with DR 60 here, _M_gcount is untouched.
+ * @endif
+ */
__istream_type&
putback(char_type __c);
+ /**
+ * @brief Unextracting the previous character.
+ * @return *this
+ *
+ * If @c rdbuf() is not null, calls @c rdbuf()->sungetc(c).
+ *
+ * If @c rdbuf() is null or if @c sungetc() fails, sets badbit in
+ * the error state.
+ *
+ * @note Since no characters are extracted, the next call to
+ * @c gcount() will return 0, as required by DR 60.
+ */
__istream_type&
- unget(void);
-
+ unget();
+
+ /**
+ * @brief Synchronizing the stream buffer.
+ * @return 0 on success, -1 on failure
+ *
+ * If @c rdbuf() is a null pointer, returns -1.
+ *
+ * Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
+ * sets badbit and returns -1.
+ *
+ * Otherwise, returns 0.
+ *
+ * @note This function does not count the number of characters
+ * extracted, if any, and therefore does not affect the next
+ * call to @c gcount().
+ * @if maint
+ * FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
+ * @endif
+ */
int
- sync(void);
-
+ sync();
+
+ /**
+ * @brief Getting the current read position.
+ * @return A file position object.
+ *
+ * If @c fail() is not false, returns @c pos_type(-1) to indicate
+ * failure. Otherwise returns @c rdbuf()->pubseekoff(0,cur,in).
+ *
+ * @note This function does not count the number of characters
+ * extracted, if any, and therefore does not affect the next
+ * call to @c gcount().
+ */
pos_type
- tellg(void);
-
+ tellg();
+
+ /**
+ * @brief Changing the current read position.
+ * @param pos A file position object.
+ * @return *this
+ *
+ * If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos). If
+ * that function fails, sets failbit.
+ *
+ * @note This function does not count the number of characters
+ * extracted, if any, and therefore does not affect the next
+ * call to @c gcount().
+ * @if maint
+ * FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
+ * @endif
+ */
__istream_type&
seekg(pos_type);
+ /**
+ * @brief Changing the current read position.
+ * @param off A file offset object.
+ * @param dir The direction in which to seek.
+ * @return *this
+ *
+ * If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
+ * If that function fails, sets failbit.
+ *
+ * @note This function does not count the number of characters
+ * extracted, if any, and therefore does not affect the next
+ * call to @c gcount().
+ * @if maint
+ * FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
+ * @endif
+ */
__istream_type&
seekg(off_type, ios_base::seekdir);
+ //@}
};
+ /**
+ * @brief Performs setup work for input streams.
+ *
+ * Objects of this class are created before all of the standard
+ * extractors are run. It is responsible for "exception-safe prefix and
+ * suffix operations," although only prefix actions are currently required
+ * by the standard. Additional actions may be added by the
+ * implementation, and we list them in
+ * http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5
+ * under [27.6] notes.
+ */
template<typename _CharT, typename _Traits>
class basic_istream<_CharT, _Traits>::sentry
{
public:
+ /// Easy access to dependant types.
typedef _Traits traits_type;
typedef basic_streambuf<_CharT, _Traits> __streambuf_type;
typedef basic_istream<_CharT, _Traits> __istream_type;
typedef typename __istream_type::__ctype_type __ctype_type;
typedef typename _Traits::int_type __int_type;
+ /**
+ * @brief The constructor performs all the work.
+ * @param is The input stream to guard.
+ * @param noskipws Whether to consume whitespace or not.
+ *
+ * If the stream state is good (@a is.good() is true), then the
+ * following actions are performed, otherwise the sentry state is
+ * false ("not okay") and failbit is set in the stream state.
+ *
+ * The sentry's preparatory actions are:
+ *
+ * -# if the stream is tied to an output stream, @c is.tie()->flush()
+ * is called to synchronize the output sequence
+ * -# if @a noskipws is false, and @c ios_base::skipws is set in
+ * @c is.flags(), the sentry extracts and discards whitespace
+ * characters from the stream. The currently imbued locale is
+ * used to determine whether each character is whitespace.
+ *
+ * If the stream state is still good, then the sentry state becomes
+ * true ("okay").
+ */
explicit
sentry(basic_istream<_CharT, _Traits>& __is, bool __noskipws = false);
+ /**
+ * @brief Quick status checking.
+ * @return The sentry state.
+ *
+ * For ease of use, sentries may be converted to booleans. The
+ * return value is that of the sentry state (true == okay).
+ */
operator bool() { return _M_ok; }
private:
bool _M_ok;
};
- // 27.6.1.2.3 Character extraction templates
+ // [27.6.1.2.3] character extraction templates
+ //@{
+ /**
+ * @brief Character extractors
+ * @param in An input stream.
+ * @param c A character reference.
+ * @return in
+ *
+ * Behaves like one of the formatted arithmetic extractors described in
+ * std::basic_istream. After constructing a sentry object with good
+ * status, this function extracts a character (if one is available) and
+ * stores it in @a c. Otherwise, sets failbit in the input stream.
+ */
template<typename _CharT, typename _Traits>
basic_istream<_CharT, _Traits>&
operator>>(basic_istream<_CharT, _Traits>& __in, _CharT& __c);
basic_istream<char, _Traits>&
operator>>(basic_istream<char, _Traits>& __in, signed char& __c)
{ return (__in >> reinterpret_cast<char&>(__c)); }
-
+ //@}
+
+ //@{
+ /**
+ * @brief Character string extractors
+ * @param in An input stream.
+ * @param s A pointer to a character array.
+ * @return in
+ *
+ * Behaves like one of the formatted arithmetic extractors described in
+ * std::basic_istream. After constructing a sentry object with good
+ * status, this function extracts up to @c n characters and stores them
+ * into the array starting at @a s. @c n is defined as:
+ *
+ * - if @c width() is greater than zero, @c n is width()
+ * - otherwise @c n is "the number of elements of the largest array of
+ * @c char_type that can store a terminating @c eos." [27.6.1.2.3]/6
+ *
+ * Characters are extracted and stored until one of the following happens:
+ * - @c n-1 characters are stored
+ * - EOF is reached
+ * - the next character is whitespace according to the current locale
+ * - the next character is a null byte (i.e., @c charT() )
+ *
+ * @c width(0) is then called for the input stream.
+ *
+ * If no characters are extracted, sets failbit.
+ */
template<typename _CharT, typename _Traits>
basic_istream<_CharT, _Traits>&
operator>>(basic_istream<_CharT, _Traits>& __in, _CharT* __s);
basic_istream<char,_Traits>&
operator>>(basic_istream<char,_Traits>& __in, signed char* __s)
{ return (__in >> reinterpret_cast<char*>(__s)); }
+ //@}
// 27.6.1.5 Template class basic_iostream
+ /**
+ * @brief Merging istream and ostream capabilities.
+ *
+ * This class multiply inherits from the input and output stream classes
+ * simply to provide a single interface.
+ */
template<typename _CharT, typename _Traits>
class basic_iostream
: public basic_istream<_CharT, _Traits>,
typedef basic_istream<_CharT, _Traits> __istream_type;
typedef basic_ostream<_CharT, _Traits> __ostream_type;
+ /**
+ * @brief Constructor does nothing.
+ *
+ * Both of the parent classes are initialized with the same
+ * streambuf pointer passed to this constructor.
+ */
explicit
basic_iostream(basic_streambuf<_CharT, _Traits>* __sb)
: __istream_type(__sb), __ostream_type(__sb)
{ }
+ /**
+ * @brief Destructor does nothing.
+ */
virtual
~basic_iostream() { }
};
- // 27.6.1.4 Standard basic_istream manipulators
+ // [27.6.1.4] standard basic_istream manipulators
+ /**
+ * @brief Quick and easy way to eat whitespace
+ *
+ * This manipulator extracts whitespace characters, stopping when the
+ * next character is non-whitespace, or when the input sequence is empty.
+ * If the sequence is empty, @c eofbit is set in the stream, but not
+ * @c failbit.
+ *
+ * The current locale is used to distinguish whitespace characters.
+ *
+ * Example:
+ * @code
+ * MyClass mc;
+ *
+ * std::cin >> std::ws >> mc;
+ * @endcode
+ * will skip leading whitespace before calling operator>> on cin and your
+ * object. Note that the same effect can be achieved by creating a
+ * std::basic_istream::sentry inside your definition of operator>>.
+ */
template<typename _CharT, typename _Traits>
basic_istream<_CharT, _Traits>&
ws(basic_istream<_CharT, _Traits>& __is);
namespace std
{
- // 27.6.2.1 Template class basic_ostream
+ // [27.6.2.1] Template class basic_ostream
+ /**
+ * @brief Controlling output.
+ *
+ * This is the base class for all output streams. It provides text
+ * formatting of all builtin types, and communicates with any class
+ * derived from basic_streambuf to do the actual output.
+ */
template<typename _CharT, typename _Traits>
class basic_ostream : virtual public basic_ios<_CharT, _Traits>
{
typedef num_put<_CharT, __ostreambuf_iter> __numput_type;
typedef ctype<_CharT> __ctype_type;
- // 27.6.2.2 Constructor/destructor:
+ // [27.6.2.2] constructor/destructor
+ /**
+ * @brief Base constructor.
+ *
+ * This ctor is almost never called by the user directly, rather from
+ * derived classes' initialization lists, which pass a pointer to
+ * their own stream buffer.
+ */
explicit
basic_ostream(__streambuf_type* __sb)
{ this->init(__sb); }
+ /**
+ * @brief Base destructor.
+ *
+ * This does very little apart from providing a virtual base dtor.
+ */
virtual
~basic_ostream() { }
- // 27.6.2.3 Prefix/suffix:
+ // [27.6.2.3] prefix/suffix
class sentry;
friend class sentry;
- // 27.6.2.5 Formatted output:
- // 27.6.2.5.3 basic_ostream::operator<<
+ // [27.6.2.5] formatted output
+ // [27.6.2.5.3] basic_ostream::operator<<
+ //@{
+ /**
+ * @brief Interface for manipulators.
+ *
+ * Manuipulators such as @c std::endl and @c std::hex use these
+ * functions in constructs like "std::cout << std::endl". For more
+ * information, see the iomanip header.
+ */
__ostream_type&
operator<<(__ostream_type& (*__pf)(__ostream_type&));
__ostream_type&
operator<<(ios_base& (*__pf) (ios_base&));
-
- // 27.6.2.5.2 Arithmetic Inserters
+ //@}
+
+ // [27.6.2.5.2] arithmetic inserters
+ /**
+ * @name Arithmetic Inserters
+ *
+ * All the @c operator<< functions (aka <em>formatted output
+ * functions</em>) have some common behavior. Each starts by
+ * constructing a temporary object of type std::basic_ostream::sentry.
+ * This can have several effects, concluding with the setting of a
+ * status flag; see the sentry documentation for more.
+ *
+ * If the sentry status is good, the function tries to generate
+ * whatever data is appropriate for the type of the argument.
+ *
+ * If an exception is thrown during insertion, ios_base::badbit
+ * will be turned on in the stream's error state without causing an
+ * ios_base::failure to be thrown. The original exception will then
+ * be rethrown.
+ */
+ //@{
+ /**
+ * @brief Basic arithmetic inserters
+ * @param A variable of builtin type.
+ * @return @c *this if successful
+ *
+ * These functions use the stream's current locale (specifically, the
+ * @c num_get facet) to perform numeric formatting.
+ */
__ostream_type&
operator<<(long __n);
__ostream_type&
operator<<(const void* __p);
+ /**
+ * @brief Extracting from another streambuf.
+ * @param sb A pointer to a streambuf
+ *
+ * This function behaves like one of the basic arithmetic extractors,
+ * in that it also constructs a sentry onject and has the same error
+ * handling behavior.
+ *
+ * If @a sb is NULL, the stream will set failbit in its error state.
+ *
+ * Characters are extracted from @a sb and inserted into @c *this
+ * until one of the following occurs:
+ *
+ * - the input stream reaches end-of-file,
+ * - insertion into the output sequence fails (in this case, the
+ * character that would have been inserted is not extracted), or
+ * - an exception occurs while getting a character from @a sb, which
+ * sets failbit in the error state
+ *
+ * If the function inserts no characters, failbit is set.
+ */
__ostream_type&
operator<<(__streambuf_type* __sb);
-
- // Unformatted output:
+ //@}
+
+ // [27.6.2.6] unformatted output functions
+ /**
+ * @name Unformatted Output Functions
+ *
+ * All the unformatted output functions have some common behavior.
+ * Each starts by constructing a temporary object of type
+ * std::basic_ostream::sentry. This has several effects, concluding
+ * with the setting of a status flag; see the sentry documentation
+ * for more.
+ *
+ * If the sentry status is good, the function tries to generate
+ * whatever data is appropriate for the type of the argument.
+ *
+ * If an exception is thrown during insertion, ios_base::badbit
+ * will be turned on in the stream's error state. If badbit is on in
+ * the stream's exceptions mask, the exception will be rethrown
+ * without completing its actions.
+ */
+ //@{
+ /**
+ * @brief Simple insertion.
+ * @param c The character to insert.
+ * @return *this
+ *
+ * Tries to insert @a c.
+ *
+ * @note This function is not overloaded on signed char and
+ * unsigned char.
+ */
__ostream_type&
put(char_type __c);
+ /**
+ * @brief Character string insertion.
+ * @param s The array to insert.
+ * @param n Maximum number of characters to insert.
+ * @return *this
+ *
+ * Characters are copied from @a s and inserted into the stream until
+ * one of the following happens:
+ *
+ * - @a n characters are inserted
+ * - inserting into the output sequence fails (in this case, badbit
+ * will be set in the stream's error state)
+ *
+ * @note This function is not overloaded on signed char and
+ * unsigned char.
+ */
__ostream_type&
write(const char_type* __s, streamsize __n);
-
+ //@}
+
+ /**
+ * @brief Synchronizing the stream buffer.
+ * @return *this
+ *
+ * If @c rdbuf() is a null pointer, changes nothing.
+ *
+ * Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
+ * sets badbit.
+ */
__ostream_type&
flush();
- // Seeks:
+ // [27.6.2.4] seek members
+ /**
+ * @brief Getting the current write position.
+ * @return A file position object.
+ *
+ * If @c fail() is not false, returns @c pos_type(-1) to indicate
+ * failure. Otherwise returns @c rdbuf()->pubseekoff(0,cur,out).
+ */
pos_type
tellp();
+ /**
+ * @brief Changing the current write position.
+ * @param pos A file position object.
+ * @return *this
+ *
+ * If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos). If
+ * that function fails, sets failbit.
+ */
__ostream_type&
seekp(pos_type);
- __ostream_type&
+ /**
+ * @brief Changing the current write position.
+ * @param off A file offset object.
+ * @param dir The direction in which to seek.
+ * @return *this
+ *
+ * If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
+ * If that function fails, sets failbit.
+ */
+ __ostream_type&
seekp(off_type, ios_base::seekdir);
};
- // 27.6.2.3 Class basic_ostream::sentry
+ /**
+ * @brief Performs setup work for output streams.
+ *
+ * Objects of this class are created before all of the standard
+ * inserters are run. It is responsible for "exception-safe prefix and
+ * suffix operations." Additional actions may be added by the
+ * implementation, and we list them in
+ * http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5
+ * under [27.6] notes.
+ */
template <typename _CharT, typename _Traits>
class basic_ostream<_CharT, _Traits>::sentry
{
basic_ostream<_CharT,_Traits>& _M_os;
public:
+ /**
+ * @brief The constructor performs preparatory work.
+ * @param os The output stream to guard.
+ *
+ * If the stream state is good (@a os.good() is true), then if the
+ * stream is tied to another output stream, @c is.tie()->flush()
+ * is called to synchronize the output sequences.
+ *
+ * If the stream state is still good, then the sentry state becomes
+ * true ("okay").
+ */
explicit
sentry(basic_ostream<_CharT,_Traits>& __os);
+ /**
+ * @brief Possibly flushes the stream.
+ *
+ * If @c ios_base::unitbuf is set in @c os.flags(), and
+ * @c std::uncaught_exception() is true, the sentry destructor calls
+ * @c flush() on the output stream.
+ */
~sentry()
{
// XXX MT
}
}
+ /**
+ * @brief Quick status checking.
+ * @return The sentry state.
+ *
+ * For ease of use, sentries may be converted to booleans. The
+ * return value is that of the sentry state (true == okay).
+ */
operator bool()
{ return _M_ok; }
};
+ // [27.6.2.5.4] character insertion templates
+ //@{
+ /**
+ * @brief Character inserters
+ * @param out An output stream.
+ * @param c A character.
+ * @return out
+ *
+ * Behaves like one of the formatted arithmetic inserters described in
+ * std::basic_ostream. After constructing a sentry object with good
+ * status, this function inserts a single character and any required
+ * padding (as determined by [22.2.2.2.2]). @c out.width(0) is then
+ * called.
+ *
+ * If @a c is of type @c char and the character type of the stream is not
+ * @c char, the character is widened before insertion.
+ */
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c);
basic_ostream<char, _Traits>&
operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c)
{ return (__out << static_cast<char>(__c)); }
+ //@}
+ //@{
+ /**
+ * @brief String inserters
+ * @param out An output stream.
+ * @param s A character string.
+ * @return out
+ * @pre @a s must be a non-NULL pointer
+ *
+ * Behaves like one of the formatted arithmetic inserters described in
+ * std::basic_ostream. After constructing a sentry object with good
+ * status, this function inserts @c traits::length(s) characters starting
+ * at @a s, widened if necessary, followed by any required padding (as
+ * determined by [22.2.2.2.2]). @c out.width(0) is then called.
+ */
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s);
basic_ostream<char, _Traits> &
operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s)
{ return (__out << reinterpret_cast<const char*>(__s)); }
-
- // 27.6.2.7 Standard basic_ostream manipulators
+ //@}
+
+ // [27.6.2.7] standard basic_ostream manipulators
+ /**
+ * @brief Write a newline and flush the stream.
+ *
+ * This manipulator is often mistakenly used when a simple newline is
+ * desired, leading to poor buffering performance. See
+ * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for more
+ * on this subject.
+ */
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
endl(basic_ostream<_CharT, _Traits>& __os)
{ return flush(__os.put(__os.widen('\n'))); }
+ /**
+ * @brief Write a null character into the output sequence.
+ *
+ * "Null character" is @c CharT() by definition. For CharT of @c char,
+ * this correctly writes the ASCII @c NUL character string terminator.
+ */
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
ends(basic_ostream<_CharT, _Traits>& __os)
{ return __os.put(_CharT()); }
+ /**
+ * @brief Flushes the output stream.
+ *
+ * This manipulator simply calls the stream's @c flush() member function.
+ */
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
flush(basic_ostream<_CharT, _Traits>& __os)
namespace std
{
+ // [27.7.1] template class basic_stringbuf
+ /**
+ * @brief The actual work of input and output (for std::string).
+ *
+ * This class associates either or both of its input and output sequences
+ * with a sequence of characters, which can be initialized from, or made
+ * available as, a @c std::basic_string. (Paraphrased from [27.7.1]/1.)
+ *
+ * For this class, open modes (of type @c ios_base::openmode) have
+ * @c in set if the input sequence can be read, and @c out set if the
+ * output sequence can be written.
+ */
template<typename _CharT, typename _Traits, typename _Alloc>
class basic_stringbuf : public basic_streambuf<_CharT, _Traits>
{
typedef typename traits_type::pos_type pos_type;
typedef typename traits_type::off_type off_type;
- // Non-standard Types:
+ //@{
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
typedef basic_streambuf<char_type, traits_type> __streambuf_type;
typedef basic_string<char_type, _Traits, _Alloc> __string_type;
typedef typename __string_type::size_type __size_type;
+ //@}
protected:
// Data Members:
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__string_type _M_string;
public:
// Constructors:
+ /**
+ * @brief Starts with an empty string buffer.
+ * @param mode Whether the buffer can read, or write, or both.
+ *
+ * The default constructor initializes the parent class using its
+ * own default ctor.
+ */
explicit
basic_stringbuf(ios_base::openmode __mode = ios_base::in | ios_base::out)
: __streambuf_type(), _M_string()
{ _M_stringbuf_init(__mode); }
+ /**
+ * @brief Starts with an existing string buffer.
+ * @param str A string to copy as a starting buffer.
+ * @param mode Whether the buffer can read, or write, or both.
+ *
+ * This constructor initializes the parent class using its
+ * own default ctor.
+ */
explicit
basic_stringbuf(const __string_type& __str,
ios_base::openmode __mode = ios_base::in | ios_base::out)
{ _M_stringbuf_init(__mode); }
// Get and set:
+ /**
+ * @brief Copying out the string buffer.
+ * @return A copy of one of the underlying sequences.
+ *
+ * "If the buffer is only created in input mode, the underlying
+ * character sequence is equal to the input sequence; otherwise, it
+ * is equal to the output sequence." [27.7.1.2]/1
+ */
__string_type
str() const
{
return _M_string;
}
+ /**
+ * @brief Setting a new buffer.
+ * @param s The string to use as a new sequence.
+ *
+ * Deallocates any previous stored sequence, then copies @a s to
+ * use as a new one.
+ */
void
str(const __string_type& __s)
{
protected:
// Common initialization code for both ctors goes here.
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
void
_M_stringbuf_init(ios_base::openmode __mode)
{
}
// Overridden virtual functions:
+ // [documentation is inherited]
virtual int_type
underflow()
{
return traits_type::eof();
}
+ // [documentation is inherited]
virtual int_type
pbackfail(int_type __c = traits_type::eof());
+ // [documentation is inherited]
virtual int_type
overflow(int_type __c = traits_type::eof());
+ /**
+ * @brief Manipulates the buffer.
+ * @param s Pointer to a buffer area.
+ * @param n Size of @a s.
+ * @return @c this
+ *
+ * If no buffer has already been created, and both @a s and @a n are
+ * non-zero, then @c s is used as a buffer; see
+ * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2
+ * for more.
+ */
virtual __streambuf_type*
setbuf(char_type* __s, streamsize __n)
{
return this;
}
+ // [documentation is inherited]
virtual pos_type
seekoff(off_type __off, ios_base::seekdir __way,
ios_base::openmode __mode = ios_base::in | ios_base::out);
+ // [documentation is inherited]
virtual pos_type
seekpos(pos_type __sp,
ios_base::openmode __mode = ios_base::in | ios_base::out);
// Assumes: contents of _M_string and internal buffer match exactly.
// __i == _M_in_cur - _M_in_beg
// __o == _M_out_cur - _M_out_beg
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
virtual int
_M_really_sync(__size_type __i, __size_type __o)
{
};
- // 27.7.2 Template class basic_istringstream
+ // [27.7.2] Template class basic_istringstream
+ /**
+ * @brief Controlling input for std::string.
+ *
+ * This class supports reading from objects of type std::basic_string,
+ * using the inherited functions from std::basic_istream. To control
+ * the associated sequence, an instance of std::basic_stringbuf is used,
+ * which this page refers to as @c sb.
+ */
template<typename _CharT, typename _Traits, typename _Alloc>
class basic_istringstream : public basic_istream<_CharT, _Traits>
{
typedef basic_istream<char_type, traits_type> __istream_type;
private:
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__stringbuf_type _M_stringbuf;
public:
// Constructors:
+ /**
+ * @brief Default constructor starts with an empty string buffer.
+ * @param mode Whether the buffer can read, or write, or both.
+ *
+ * @c ios_base::in is automatically included in @a mode.
+ *
+ * Initializes @c sb using @c mode|in, and passes @c &sb to the base
+ * class initializer. Does not allocate any buffer.
+ *
+ * @if maint
+ * That's a lie. We initialize the base class with NULL, because the
+ * string class does its own memory management.
+ * @endif
+ */
explicit
basic_istringstream(ios_base::openmode __mode = ios_base::in)
: __istream_type(NULL), _M_stringbuf(__mode | ios_base::in)
{ this->init(&_M_stringbuf); }
+ /**
+ * @brief Starts with an existing string buffer.
+ * @param str A string to copy as a starting buffer.
+ * @param mode Whether the buffer can read, or write, or both.
+ *
+ * @c ios_base::in is automatically included in @a mode.
+ *
+ * Initializes @c sb using @a str and @c mode|in, and passes @c &sb
+ * to the base class initializer.
+ *
+ * @if maint
+ * That's a lie. We initialize the base class with NULL, because the
+ * string class does its own memory management.
+ * @endif
+ */
explicit
basic_istringstream(const __string_type& __str,
ios_base::openmode __mode = ios_base::in)
: __istream_type(NULL), _M_stringbuf(__str, __mode | ios_base::in)
{ this->init(&_M_stringbuf); }
+ /**
+ * @brief The destructor does nothing.
+ *
+ * The buffer is deallocated by the stringbuf object, not the
+ * formatting stream.
+ */
~basic_istringstream()
{ }
// Members:
+ /**
+ * @brief Accessing the underlying buffer.
+ * @return The current basic_stringbuf buffer.
+ *
+ * This hides both signatures of std::basic_ios::rdbuf().
+ */
__stringbuf_type*
rdbuf() const
{ return const_cast<__stringbuf_type*>(&_M_stringbuf); }
+ /**
+ * @brief Copying out the string buffer.
+ * @return @c rdbuf()->str()
+ */
__string_type
str() const
{ return _M_stringbuf.str(); }
+ /**
+ * @brief Setting a new buffer.
+ * @param s The string to use as a new sequence.
+ *
+ * Calls @c rdbuf()->str(s).
+ */
void
str(const __string_type& __s)
{ _M_stringbuf.str(__s); }
};
- // 27.7.3 Template class basic_ostringstream
+ // [27.7.3] Template class basic_ostringstream
+ /**
+ * @brief Controlling output for std::string.
+ *
+ * This class supports writing to objects of type std::basic_string,
+ * using the inherited functions from std::basic_ostream. To control
+ * the associated sequence, an instance of std::basic_stringbuf is used,
+ * which this page refers to as @c sb.
+ */
template <typename _CharT, typename _Traits, typename _Alloc>
class basic_ostringstream : public basic_ostream<_CharT, _Traits>
{
typedef basic_ostream<char_type, traits_type> __ostream_type;
private:
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__stringbuf_type _M_stringbuf;
public:
- // Constructors/destructor:
+ // Constructors/destructor:
+ /**
+ * @brief Default constructor starts with an empty string buffer.
+ * @param mode Whether the buffer can read, or write, or both.
+ *
+ * @c ios_base::out is automatically included in @a mode.
+ *
+ * Initializes @c sb using @c mode|out, and passes @c &sb to the base
+ * class initializer. Does not allocate any buffer.
+ *
+ * @if maint
+ * That's a lie. We initialize the base class with NULL, because the
+ * string class does its own memory management.
+ * @endif
+ */
explicit
basic_ostringstream(ios_base::openmode __mode = ios_base::out)
: __ostream_type(NULL), _M_stringbuf(__mode | ios_base::out)
{ this->init(&_M_stringbuf); }
+ /**
+ * @brief Starts with an existing string buffer.
+ * @param str A string to copy as a starting buffer.
+ * @param mode Whether the buffer can read, or write, or both.
+ *
+ * @c ios_base::out is automatically included in @a mode.
+ *
+ * Initializes @c sb using @a str and @c mode|out, and passes @c &sb
+ * to the base class initializer.
+ *
+ * @if maint
+ * That's a lie. We initialize the base class with NULL, because the
+ * string class does its own memory management.
+ * @endif
+ */
explicit
basic_ostringstream(const __string_type& __str,
ios_base::openmode __mode = ios_base::out)
: __ostream_type(NULL), _M_stringbuf(__str, __mode | ios_base::out)
{ this->init(&_M_stringbuf); }
+ /**
+ * @brief The destructor does nothing.
+ *
+ * The buffer is deallocated by the stringbuf object, not the
+ * formatting stream.
+ */
~basic_ostringstream()
{ }
// Members:
+ /**
+ * @brief Accessing the underlying buffer.
+ * @return The current basic_stringbuf buffer.
+ *
+ * This hides both signatures of std::basic_ios::rdbuf().
+ */
__stringbuf_type*
rdbuf() const
{ return const_cast<__stringbuf_type*>(&_M_stringbuf); }
+ /**
+ * @brief Copying out the string buffer.
+ * @return @c rdbuf()->str()
+ */
__string_type
str() const
{ return _M_stringbuf.str(); }
+ /**
+ * @brief Setting a new buffer.
+ * @param s The string to use as a new sequence.
+ *
+ * Calls @c rdbuf()->str(s).
+ */
void
str(const __string_type& __s)
{ _M_stringbuf.str(__s); }
};
- // 27.7.4 Template class basic_stringstream
+ // [27.7.4] Template class basic_stringstream
+ /**
+ * @brief Controlling input and output for std::string.
+ *
+ * This class supports reading from and writing to objects of type
+ * std::basic_string, using the inherited functions from
+ * std::basic_iostream. To control the associated sequence, an instance
+ * of std::basic_stringbuf is used, which this page refers to as @c sb.
+ */
template <typename _CharT, typename _Traits, typename _Alloc>
class basic_stringstream : public basic_iostream<_CharT, _Traits>
{
typedef basic_iostream<char_type, traits_type> __iostream_type;
private:
+ /**
+ * @if maint
+ * @doctodo
+ * @endif
+ */
__stringbuf_type _M_stringbuf;
public:
// Constructors/destructors
+ /**
+ * @brief Default constructor starts with an empty string buffer.
+ * @param mode Whether the buffer can read, or write, or both.
+ *
+ * Initializes @c sb using @c mode, and passes @c &sb to the base
+ * class initializer. Does not allocate any buffer.
+ *
+ * @if maint
+ * That's a lie. We initialize the base class with NULL, because the
+ * string class does its own memory management.
+ * @endif
+ */
explicit
basic_stringstream(ios_base::openmode __m = ios_base::out | ios_base::in)
: __iostream_type(NULL), _M_stringbuf(__m)
{ this->init(&_M_stringbuf); }
+ /**
+ * @brief Starts with an existing string buffer.
+ * @param str A string to copy as a starting buffer.
+ * @param mode Whether the buffer can read, or write, or both.
+ *
+ * Initializes @c sb using @a str and @c mode, and passes @c &sb
+ * to the base class initializer.
+ *
+ * @if maint
+ * That's a lie. We initialize the base class with NULL, because the
+ * string class does its own memory management.
+ * @endif
+ */
explicit
basic_stringstream(const __string_type& __str,
ios_base::openmode __m = ios_base::out | ios_base::in)
: __iostream_type(NULL), _M_stringbuf(__str, __m)
{ this->init(&_M_stringbuf); }
+ /**
+ * @brief The destructor does nothing.
+ *
+ * The buffer is deallocated by the stringbuf object, not the
+ * formatting stream.
+ */
~basic_stringstream()
{ }
// Members:
+ /**
+ * @brief Accessing the underlying buffer.
+ * @return The current basic_stringbuf buffer.
+ *
+ * This hides both signatures of std::basic_ios::rdbuf().
+ */
__stringbuf_type*
rdbuf() const
{ return const_cast<__stringbuf_type*>(&_M_stringbuf); }
+ /**
+ * @brief Copying out the string buffer.
+ * @return @c rdbuf()->str()
+ */
__string_type
str() const
{ return _M_stringbuf.str(); }
+ /**
+ * @brief Setting a new buffer.
+ * @param s The string to use as a new sequence.
+ *
+ * Calls @c rdbuf()->str(s).
+ */
void
str(const __string_type& __s)
{ _M_stringbuf.str(__s); }
namespace std
{
+ /**
+ * @if maint
+ * Does stuff.
+ * @endif
+ */
template<typename _CharT, typename _Traits>
streamsize
__copy_streambufs(basic_ios<_CharT, _Traits>& _ios,
basic_streambuf<_CharT, _Traits>* __sbin,
basic_streambuf<_CharT, _Traits>* __sbout);
- // 27.5.2 Template class basic_streambuf<_CharT, _Traits>
+ /**
+ * @brief The actual work of input and output (interface).
+ *
+ * This is a base class. Derived stream buffers each control a
+ * pair of character sequences: one for input, and one for output.
+ *
+ * Section [27.5.1] of the standard describes the requirements and
+ * behavior of stream buffer classes. That section (three paragraphs)
+ * is reproduced here, for simplicity and accuracy.
+ *
+ * -# Stream buffers can impose various constraints on the sequences
+ * they control. Some constraints are:
+ * - The controlled input sequence can be not readable.
+ * - The controlled output sequence can be not writable.
+ * - The controlled sequences can be associated with the contents of
+ * other representations for character sequences, such as external
+ * files.
+ * - The controlled sequences can support operations @e directly to or
+ * from associated sequences.
+ * - The controlled sequences can impose limitations on how the
+ * program can read characters from a sequence, write characters to
+ * a sequence, put characters back into an input sequence, or alter
+ * the stream position.
+ * .
+ * -# Each sequence is characterized by three pointers which, if non-null,
+ * all point into the same @c charT array object. The array object
+ * represents, at any moment, a (sub)sequence of characters from the
+ * sequence. Operations performed on a sequence alter the values
+ * stored in these pointers, perform reads and writes directly to or
+ * from associated sequences, and alter "the stream position" and
+ * conversion state as needed to maintain this subsequence relationship.
+ * The three pointers are:
+ * - the <em>beginning pointer</em>, or lowest element address in the
+ * array (called @e xbeg here);
+ * - the <em>next pointer</em>, or next element address that is a
+ * current candidate for reading or writing (called @e xnext here);
+ * - the <em>end pointer</em>, or first element address beyond the
+ * end of the array (called @e xend here).
+ * .
+ * -# The following semantic constraints shall always apply for any set
+ * of three pointers for a sequence, using the pointer names given
+ * immediately above:
+ * - If @e xnext is not a null pointer, then @e xbeg and @e xend shall
+ * also be non-null pointers into the same @c charT array, as
+ * described above; otherwise, @e xbeg and @e xend shall also be null.
+ * - If @e xnext is not a null pointer and @e xnext < @e xend for an
+ * output sequence, then a <em>write position</em> is available.
+ * In this case, @e *xnext shall be assignable as the next element
+ * to write (to put, or to store a character value, into the sequence).
+ * - If @e xnext is not a null pointer and @e xbeg < @e xnext for an
+ * input sequence, then a <em>putback position</em> is available.
+ * In this case, @e xnext[-1] shall have a defined value and is the
+ * next (preceding) element to store a character that is put back
+ * into the input sequence.
+ * - If @e xnext is not a null pointer and @e xnext< @e xend for an
+ * input sequence, then a <em>read position</em> is available.
+ * In this case, @e *xnext shall have a defined value and is the
+ * next element to read (to get, or to obtain a character value,
+ * from the sequence).
+ */
template<typename _CharT, typename _Traits>
class basic_streambuf
{
public:
- // Types:
+ //@{
+ /**
+ * 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 _Traits traits_type;
typedef typename traits_type::int_type int_type;
typedef typename traits_type::pos_type pos_type;
typedef typename traits_type::off_type off_type;
-
- // Non-standard Types:
+ //@}
+
+ //@{
+ /**
+ * @if maint
+ * These are non-standard types.
+ * @endif
+ */
typedef ctype<char_type> __ctype_type;
typedef basic_streambuf<char_type, traits_type> __streambuf_type;
typedef typename traits_type::state_type __state_type;
+ //@}
friend class basic_ios<char_type, traits_type>;
friend class basic_istream<char_type, traits_type>;
__streambuf_type* __sbin,__streambuf_type* __sbout);
protected:
- // Pointer to the beginning of internally-allocated
- // space. Filebuf manually allocates/deallocates this, whereas
- // stringstreams attempt to use the built-in intelligence of the
- // string class. If you are managing memory, set this. If not,
- // leave it NULL.
+ /**
+ * @if maint
+ * Pointer to the beginning of internally-allocated space. Filebuf
+ * manually allocates/deallocates this, whereas stringstreams attempt
+ * to use the built-in intelligence of the string class. If you are
+ * managing memory, set this. If not, leave it NULL.
+ * @endif
+ */
char_type* _M_buf;
- // Actual size of allocated internal buffer, in bytes.
+ /**
+ * @if maint
+ * Actual size of allocated internal buffer, in bytes.
+ * @endif
+ */
size_t _M_buf_size;
- // Optimal or preferred size of internal buffer, in bytes.
+ /**
+ * @if maint
+ * Optimal or preferred size of internal buffer, in bytes.
+ * @endif
+ */
size_t _M_buf_size_opt;
- // True iff _M_in_* and _M_out_* buffers should always point to
- // the same place. True for fstreams, false for sstreams.
+ /**
+ * @if maint
+ * True iff _M_in_* and _M_out_* buffers should always point to
+ * the same place. True for fstreams, false for sstreams.
+ * @endif
+ */
bool _M_buf_unified;
- // This is based on _IO_FILE, just reordered to be more
- // consistent, and is intended to be the most minimal abstraction
- // for an internal buffer.
- // get == input == read
- // put == output == write
+ //@{
+ /**
+ * @if maint
+ * This is based on _IO_FILE, just reordered to be more consistent,
+ * and is intended to be the most minimal abstraction for an
+ * internal buffer.
+ * - get == input == read
+ * - put == output == write
+ * @endif
+ */
char_type* _M_in_beg; // Start of get area.
char_type* _M_in_cur; // Current read area.
char_type* _M_in_end; // End of get area.
char_type* _M_out_beg; // Start of put area.
char_type* _M_out_cur; // Current put area.
char_type* _M_out_end; // End of put area.
+ //@}
- // Place to stash in || out || in | out settings for current streambuf.
+ /**
+ * @if maint
+ * Place to stash in || out || in | out settings for current streambuf.
+ * @endif
+ */
ios_base::openmode _M_mode;
- // Current locale setting.
+ /**
+ * @if maint
+ * Current locale setting.
+ * @endif
+ */
locale _M_buf_locale;
- // True iff locale is initialized.
+ /**
+ * @if maint
+ * True iff locale is initialized.
+ * @endif
+ */
bool _M_buf_locale_init;
- // Necessary bits for putback buffer management. Only used in
- // the basic_filebuf class, as necessary for the standard
- // requirements. The only basic_streambuf member function that
- // needs access to these data members is in_avail...
- // NB: pbacks of over one character are not currently supported.
+ //@{
+ /**
+ * @if maint
+ * Necessary bits for putback buffer management. Only used in
+ * the basic_filebuf class, as necessary for the standard
+ * requirements. The only basic_streambuf member function that
+ * needs access to these data members is in_avail...
+ *
+ * @note pbacks of over one character are not currently supported.
+ * @endif
+ */
static const size_t _S_pback_size = 1;
char_type _M_pback[_S_pback_size];
char_type* _M_pback_cur_save;
char_type* _M_pback_end_save;
bool _M_pback_init;
+ //@}
- // Yet unused.
+ /**
+ * @if maint
+ * Yet unused.
+ * @endif
+ */
fpos<__state_type> _M_pos;
// Initializes pback buffers, and moves normal buffers to safety.
}
public:
+ /// Destructor deallocates no buffer space.
virtual
~basic_streambuf()
{
_M_buf_locale_init = false;
}
- // Locales:
+ // [27.5.2.2.1] locales
+ /**
+ * @brief Entry point for imbue().
+ * @param loc The new locale.
+ * @return The previous locale.
+ *
+ * Calls the derived imbue(loc).
+ */
locale
pubimbue(const locale &__loc)
{
return __tmp;
}
+ /**
+ * @brief Locale access.
+ * @return The current locale in effect.
+ *
+ * If pubimbue(loc) has been called, then the most recent @c loc
+ * is returned. Otherwise the global locale in effect at the time
+ * of construction is returned.
+ */
locale
getloc() const
{
return locale();
}
- // Buffer and positioning:
+ // [27.5.2.2.2] buffer management and positioning
+ //@{
+ /**
+ * @brief Entry points for derived buffer functions.
+ *
+ * The public versions of @c pubfoo dispatch to the protected
+ * derived @c foo member functions, passing the arguments (if any)
+ * and returning the result unchanged.
+ */
__streambuf_type*
pubsetbuf(char_type* __s, streamsize __n)
{ return this->setbuf(__s, __n); }
int
pubsync() { return this->sync(); }
-
- // Get and put areas:
- // Get area:
+ //@}
+
+ // [27.5.2.2.3] get area
+ /**
+ * @brief Looking ahead into the stream.
+ * @return The number of characters available.
+ *
+ * If a read position is available, returns the number of characters
+ * available for reading before the buffer must be refilled.
+ * Otherwise returns the derived @c showmanyc().
+ */
streamsize
in_avail()
{
return __ret;
}
+ /**
+ * @brief Getting the next character.
+ * @return The next character, or eof.
+ *
+ * Calls @c sbumpc(), and if that function returns
+ * @c traits::eof(), so does this function. Otherwise, @c sgetc().
+ */
int_type
snextc()
{
? __eof : this->sgetc());
}
+ /**
+ * @brief Getting the next character.
+ * @return The next character, or eof.
+ *
+ * If the input read position is available, returns that character
+ * and increments the read pointer, otherwise calls and returns
+ * @c uflow().
+ */
int_type
sbumpc();
+ /**
+ * @brief Getting the next character.
+ * @return The next character, or eof.
+ *
+ * If the input read position is available, returns that character,
+ * otherwise calls and returns @c underflow(). Does not move the
+ * read position after fetching the character.
+ */
int_type
sgetc()
{
return __ret;
}
+ /**
+ * @brief Entry point for xsgetn.
+ * @param s A buffer area.
+ * @param n A count.
+ *
+ * Returns xsgetn(s,n). The effect is to fill @a s[0] through
+ * @a s[n-1] with characters from the input sequence, if possible.
+ */
streamsize
sgetn(char_type* __s, streamsize __n)
{ return this->xsgetn(__s, __n); }
- // Putback:
+ // [27.5.2.2.4] putback
+ /**
+ * @brief Pushing characters back into the input stream.
+ * @param c The character to push back.
+ * @return The previous character, if possible.
+ *
+ * Similar to sungetc(), but @a c is pushed onto the stream instead
+ * of "the previous character". If successful, the next character
+ * fetched from the input stream will be @a c.
+ */
int_type
sputbackc(char_type __c);
+ /**
+ * @brief Moving backwards in the input stream.
+ * @return The previous character, if possible.
+ *
+ * If a putback position is available, this function decrements the
+ * input pointer and returns that character. Otherwise, calls and
+ * returns pbackfail(). The effect is to "unget" the last character
+ * "gotten".
+ */
int_type
sungetc();
- // Put area:
+ // [27.5.2.2.5] put area
+ /**
+ * @brief Entry point for all single-character output functions.
+ * @param c A character to output.
+ * @return @a c, if possible.
+ *
+ * One of two public output functions.
+ *
+ * If a write position is available for the output sequence (i.e.,
+ * the buffer is not full), stores @a c in that position, increments
+ * the position, and returns @c traits::to_int_type(c). If a write
+ * position is not available, returns @c overflow(c).
+ */
int_type
sputc(char_type __c);
+ /**
+ * @brief Entry point for all single-character output functions.
+ * @param s A buffer read area.
+ * @param n A count.
+ *
+ * One of two public output functions.
+ *
+ *
+ * Returns xsputn(s,n). The effect is to write @a s[0] through
+ * @a s[n-1] to the output sequence, if possible.
+ */
streamsize
sputn(const char_type* __s, streamsize __n)
{ return this->xsputn(__s, __n); }
protected:
+ /**
+ * @brief Base constructor.
+ *
+ * Only called from derived constructors, and sets up all the
+ * buffer data to zero, including the pointers described in the
+ * basic_streambuf class description. Note that, as a result,
+ * - the class starts with no read nor write positions available,
+ * - this is not an error
+ */
basic_streambuf()
: _M_buf(NULL), _M_buf_size(0), _M_buf_size_opt(BUFSIZ),
_M_buf_unified(false), _M_in_beg(0), _M_in_cur(0), _M_in_end(0),
_M_pback_init(false)
{ }
- // Get area:
+ // [27.5.2.3.1] get area access
+ //@{
+ /**
+ * @brief Access to the get area.
+ *
+ * These functions are only available to other protected functions,
+ * including derived classes.
+ *
+ * - eback() returns the beginning pointer for the input sequence
+ * - gptr() returns the next pointer for the input sequence
+ * - egptr() returns the end pointer for the input sequence
+ */
char_type*
eback() const { return _M_in_beg; }
char_type*
egptr() const { return _M_in_end; }
-
+ //@}
+
+ /**
+ * @brief Moving the read position.
+ * @param n The delta by which to move.
+ *
+ * This just advances the read position without returning any data.
+ */
void
gbump(int __n) { _M_in_cur += __n; }
+ /**
+ * @brief Setting the three read area pointers.
+ * @param gbeg A pointer.
+ * @param gnext A pointer.
+ * @param gend A pointer.
+ * @post @a gbeg == @c eback(), @a gnext == @c gptr(), and
+ * @a gend == @c egptr()
+ */
void
setg(char_type* __gbeg, char_type* __gnext, char_type* __gend)
{
_M_mode = _M_mode | ios_base::in;
}
- // Put area:
+ // [27.5.2.3.2] put area access
+ //@{
+ /**
+ * @brief Access to the put area.
+ *
+ * These functions are only available to other protected functions,
+ * including derived classes.
+ *
+ * - pbase() returns the beginning pointer for the output sequence
+ * - pptr() returns the next pointer for the output sequence
+ * - epptr() returns the end pointer for the output sequence
+ */
char_type*
pbase() const { return _M_out_beg; }
char_type*
epptr() const { return _M_out_end; }
-
+ //@}
+
+ /**
+ * @brief Moving the write position.
+ * @param n The delta by which to move.
+ *
+ * This just advances the write position without returning any data.
+ */
void
pbump(int __n) { _M_out_cur += __n; }
+ /**
+ * @brief Setting the three write area pointers.
+ * @param pbeg A pointer.
+ * @param pend A pointer.
+ * @post @a pbeg == @c pbase(), @a pbeg == @c pptr(), and
+ * @a pend == @c epptr()
+ */
void
setp(char_type* __pbeg, char_type* __pend)
{
_M_mode = _M_mode | ios_base::out;
}
- // Virtual functions:
- // Locales:
+ // [27.5.2.4] virtual functions
+ // [27.5.2.4.1] locales
+ /**
+ * @brief Changes translations.
+ * @param loc A new locale.
+ *
+ * Translations done during I/O which depend on the current locale
+ * are changed by this call. The standard adds, "Between invocations
+ * of this function a class derived from streambuf can safely cache
+ * results of calls to locale functions and to members of facets
+ * so obtained." This function simply stores the new locale for use
+ * by derived classes.
+ */
virtual void
imbue(const locale& __loc)
{
_M_buf_locale = __loc;
}
- // Buffer management and positioning:
+ // [27.5.2.4.2] buffer management and positioning
+ /**
+ * @brief Maniuplates the buffer.
+ *
+ * Each derived class provides its own appropriate behavior. See
+ * the next-to-last paragraph of
+ * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for
+ * more on this function.
+ *
+ * @note Base class version does nothing, returns @c this.
+ */
virtual basic_streambuf<char_type,_Traits>*
setbuf(char_type*, streamsize)
{ return this; }
+ /**
+ * @brief Alters the stream positions.
+ *
+ * Each derived class provides its own appropriate behavior.
+ * @note Base class version does nothing, returns a @c pos_type
+ * that represents an invalid stream position.
+ */
virtual pos_type
seekoff(off_type, ios_base::seekdir,
ios_base::openmode /*__mode*/ = ios_base::in | ios_base::out)
{ return pos_type(off_type(-1)); }
+ /**
+ * @brief Alters the stream positions.
+ *
+ * Each derived class provides its own appropriate behavior.
+ * @note Base class version does nothing, returns a @c pos_type
+ * that represents an invalid stream position.
+ */
virtual pos_type
seekpos(pos_type,
ios_base::openmode /*__mode*/ = ios_base::in | ios_base::out)
{ return pos_type(off_type(-1)); }
+ /**
+ * @brief Synchronizes the buffer arrays with the controlled sequences.
+ * @return -1 on failure.
+ *
+ * Each derived class provides its own appropriate behavior,
+ * including the definition of "failure".
+ * @note Base class version does nothing, returns zero.
+ */
virtual int
sync() { return 0; }
- // Get area:
+ // [27.5.2.4.3] get area
+ /**
+ * @brief Investigating the data available.
+ * @return An estimate of the number of characters available in the
+ * input sequence, or -1.
+ *
+ * "If it returns a positive value, then successive calls to
+ * @c underflow() will not return @c traits::eof() until at least that
+ * number of characters have been supplied. If @c showmanyc()
+ * returns -1, then calls to @c underflow() or @c uflow() will fail."
+ * [27.5.2.4.3]/1
+ *
+ * @note Base class version does nothing, returns zero.
+ * @note The standard adds that "the intention is not only that the
+ * calls [to underflow or uflow] will not return @c eof() but
+ * that they will return "immediately".
+ * @note The standard adds that "the morphemes of @c showmanyc are
+ * "es-how-many-see", not "show-manic".
+ */
virtual streamsize
showmanyc() { return 0; }
+ /**
+ * @brief Multiple character extraction.
+ * @param s A buffer area.
+ * @param n Maximum number of characters to assign.
+ * @return The number of characters assigned.
+ *
+ * Fills @a s[0] through @a s[n-1] with characters from the input
+ * sequence, as if by @c sbumpc(). Stops when either @a n characters
+ * have been copied, or when @c traits::eof() would be copied.
+ *
+ * It is expected that derived classes provide a more efficient
+ * implementation by overriding this definition.
+ */
virtual streamsize
xsgetn(char_type* __s, streamsize __n);
+ /**
+ * @brief Fetches more data from the controlled sequence.
+ * @return The first character from the <em>pending sequence</em>.
+ *
+ * Informally, this function is called when the input buffer is
+ * exhausted (or does not exist, as buffering need not actually be
+ * done). If a buffer exists, it is "refilled". In either case, the
+ * next available character is returned, or @c traits::eof() to
+ * indicate a null pending sequence.
+ *
+ * For a formal definiton of the pending sequence, see a good text
+ * such as Langer & Kreft, or [27.5.2.4.3]/7-14.
+ *
+ * A functioning input streambuf can be created by overriding only
+ * this function (no buffer area will be used). For an example, see
+ * http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#6
+ *
+ * @note Base class version does nothing, returns eof().
+ */
virtual int_type
underflow()
{ return traits_type::eof(); }
+ /**
+ * @brief Fetches more data from the controlled sequence.
+ * @return The first character from the <em>pending sequence</em>.
+ *
+ * Informally, this function does the same thing as @c underflow(),
+ * and in fact is required to call that function. It also returns
+ * the new character, like @c underflow() does. However, this
+ * function also moves the read position forward by one.
+ */
virtual int_type
uflow()
{
return __ret;
}
- // Putback:
+ // [27.5.2.4.4] putback
+ /**
+ * @brief Tries to back up the input sequence.
+ * @param c The character to be inserted back into the sequence.
+ * @return eof() on failure, "some other value" on success
+ * @post The constraints of @c gptr(), @c eback(), and @c pptr()
+ * are the same as for @c underflow().
+ *
+ * @note Base class version does nothing, returns eof().
+ */
virtual int_type
pbackfail(int_type /* __c */ = traits_type::eof())
{ return traits_type::eof(); }
// Put area:
+ /**
+ * @brief Multiple character insertion.
+ * @param s A buffer area.
+ * @param n Maximum number of characters to write.
+ * @return The number of characters written.
+ *
+ * Writes @a s[0] through @a s[n-1] to the output sequence, as if
+ * by @c sputc(). Stops when either @a n characters have been
+ * copied, or when @c sputc() would return @c traits::eof().
+ *
+ * It is expected that derived classes provide a more efficient
+ * implementation by overriding this definition.
+ */
virtual streamsize
xsputn(const char_type* __s, streamsize __n);
+ /**
+ * @brief Consumes data from the buffer; writes to the
+ * controlled sequence.
+ * @param c An additional character to consume.
+ * @return eof() to indicate failure, something else (usually
+ * @a c, or not_eof())
+ *
+ * Informally, this function is called when the output buffer is full
+ * (or does not exist, as buffering need not actually be done). If a
+ * buffer exists, it is "consumed", with "some effect" on the
+ * controlled sequence. (Typically, the buffer is written out to the
+ * sequence verbatim.) In either case, the character @a c is also
+ * written out, if @a c is not @c eof().
+ *
+ * For a formal definiton of this function, see a good text
+ * such as Langer & Kreft, or [27.5.2.4.5]/3-7.
+ *
+ * A functioning output streambuf can be created by overriding only
+ * this function (no buffer area will be used).
+ *
+ * @note Base class version does nothing, returns eof().
+ */
virtual int_type
overflow(int_type /* __c */ = traits_type::eof())
{ return traits_type::eof(); }
#ifdef _GLIBCPP_DEPRECATED
- // http://gcc.gnu.org/ml/libstdc++/2002-05/msg00168.html
// Annex D.6
public:
+ /**
+ * @brief Tosses a character.
+ *
+ * Advances the read pointer, ignoring the character that would have
+ * been read.
+ *
+ * See http://gcc.gnu.org/ml/libstdc++/2002-05/msg00168.html
+ *
+ * @note This function has been deprecated by the standard. You
+ * must define @c _GLIBCPP_DEPRECATED to make this visible; see
+ * c++config.h.
+ */
void
stossc()
{
projects / platform / upstream / linaro-gcc.git / commitdiff