From 840ceb345b02d8f883b740949984878c9ed6f18e Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Thu, 21 Nov 2002 07:06:41 +0000 Subject: [PATCH] TODO: Note change in clause 27 docs. 2002-11-21 Phil Edwards * 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. From-SVN: r59325 --- libstdc++-v3/ChangeLog | 11 + libstdc++-v3/docs/doxygen/TODO | 6 +- libstdc++-v3/include/bits/basic_ios.h | 283 ++++++++++- libstdc++-v3/include/bits/fpos.h | 8 +- libstdc++-v3/include/bits/ios_base.h | 268 ++++++++++- libstdc++-v3/include/bits/stl_deque.h | 20 +- .../include/bits/stl_iterator_base_types.h | 3 +- libstdc++-v3/include/std/std_fstream.h | 334 +++++++++++-- libstdc++-v3/include/std/std_iomanip.h | 46 ++ libstdc++-v3/include/std/std_iosfwd.h | 81 +++- libstdc++-v3/include/std/std_iostream.h | 30 +- libstdc++-v3/include/std/std_istream.h | 516 +++++++++++++++++++- libstdc++-v3/include/std/std_ostream.h | 270 ++++++++++- libstdc++-v3/include/std/std_sstream.h | 277 ++++++++++- libstdc++-v3/include/std/std_streambuf.h | 529 +++++++++++++++++++-- 15 files changed, 2477 insertions(+), 205 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index d330a0e675b..48118781e58 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,14 @@ +2002-11-21 Phil Edwards + + * 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 Jonathan Lennox diff --git a/libstdc++-v3/docs/doxygen/TODO b/libstdc++-v3/docs/doxygen/TODO index 50ddfe7f2d6..0b6e3d6c00b 100644 --- a/libstdc++-v3/docs/doxygen/TODO +++ b/libstdc++-v3/docs/doxygen/TODO @@ -31,7 +31,11 @@ c24 stl_iterator.h (__normal_iterator, other small TODO bits) stream iterators c25 stl_algo.h (lots of stuff) c26 , , 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. diff --git a/libstdc++-v3/include/bits/basic_ios.h b/libstdc++-v3/include/bits/basic_ios.h index 13ad0f82e99..b6ef89ba8b0 100644 --- a/libstdc++-v3/include/bits/basic_ios.h +++ b/libstdc++-v3/include/bits/basic_ios.h @@ -43,115 +43,282 @@ 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 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, 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(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 + * #include + * #include + * + * 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 { @@ -163,6 +330,15 @@ namespace std 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 >(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 >(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); diff --git a/libstdc++-v3/include/bits/fpos.h b/libstdc++-v3/include/bits/fpos.h index 279e0ab16ba..5432527421a 100644 --- a/libstdc++-v3/include/bits/fpos.h +++ b/libstdc++-v3/include/bits/fpos.h @@ -48,7 +48,10 @@ namespace std { // 27.4.1 Types - // 27.4.3 Template class fpos + // [27.4.3] template class fpos + /** + * @doctodo + */ template class fpos { @@ -113,9 +116,10 @@ namespace std _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 streampos; # ifdef _GLIBCPP_USE_WCHAR_T + /// 27.2, paragraph 10 about fpos/char_traits circularity typedef fpos wstreampos; # endif } // namespace std diff --git a/libstdc++-v3/include/bits/ios_base.h b/libstdc++-v3/include/bits/ios_base.h index 2cfe4134c92..1f085d9e4e7 100644 --- a/libstdc++-v3/include/bits/ios_base.h +++ b/libstdc++-v3/include/bits/ios_base.h @@ -145,11 +145,20 @@ 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: @@ -173,47 +182,148 @@ namespace std }; // 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 @@ -227,6 +337,9 @@ namespace std #endif // Callbacks; + /** + * @doctodo + */ enum event { erase_event, @@ -234,18 +347,30 @@ namespace std 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 @@ -329,10 +454,21 @@ namespace std 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) { @@ -341,6 +477,14 @@ namespace std 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) { @@ -349,6 +493,15 @@ namespace std 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) { @@ -358,12 +511,32 @@ namespace std 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) { @@ -372,9 +545,20 @@ namespace std 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) { @@ -383,20 +567,53 @@ namespace std 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) { @@ -405,6 +622,9 @@ namespace std return __word._M_iword; } + /** + * @doctodo + */ inline void*& pword(int __ix) { @@ -414,6 +634,10 @@ namespace std } // Destructor + /** + * Destroys local storage and + * [XXX does something with callbacks]. + */ virtual ~ios_base(); protected: @@ -429,7 +653,8 @@ namespace std #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) { @@ -437,6 +662,7 @@ namespace std return __base; } + /// Calls base.unsetf(ios_base::boolalpha). inline ios_base& noboolalpha(ios_base& __base) { @@ -444,6 +670,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::showbase). inline ios_base& showbase(ios_base& __base) { @@ -451,6 +678,7 @@ namespace std return __base; } + /// Calls base.unsetf(ios_base::showbase). inline ios_base& noshowbase(ios_base& __base) { @@ -458,6 +686,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::showpoint). inline ios_base& showpoint(ios_base& __base) { @@ -465,6 +694,7 @@ namespace std return __base; } + /// Calls base.unsetf(ios_base::showpoint). inline ios_base& noshowpoint(ios_base& __base) { @@ -472,6 +702,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::showpos). inline ios_base& showpos(ios_base& __base) { @@ -479,6 +710,7 @@ namespace std return __base; } + /// Calls base.unsetf(ios_base::showpos). inline ios_base& noshowpos(ios_base& __base) { @@ -486,6 +718,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::skipws). inline ios_base& skipws(ios_base& __base) { @@ -493,6 +726,7 @@ namespace std return __base; } + /// Calls base.unsetf(ios_base::skipws). inline ios_base& noskipws(ios_base& __base) { @@ -500,6 +734,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::uppercase). inline ios_base& uppercase(ios_base& __base) { @@ -507,6 +742,7 @@ namespace std return __base; } + /// Calls base.unsetf(ios_base::uppercase). inline ios_base& nouppercase(ios_base& __base) { @@ -514,6 +750,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::unitbuf). inline ios_base& unitbuf(ios_base& __base) { @@ -521,6 +758,7 @@ namespace std return __base; } + /// Calls base.unsetf(ios_base::unitbuf). inline ios_base& nounitbuf(ios_base& __base) { @@ -528,7 +766,8 @@ namespace std 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) { @@ -536,6 +775,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::left, ios_base::adjustfield). inline ios_base& left(ios_base& __base) { @@ -543,6 +783,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::right, ios_base::adjustfield). inline ios_base& right(ios_base& __base) { @@ -550,7 +791,8 @@ namespace std 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) { @@ -558,6 +800,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::hex, ios_base::basefield). inline ios_base& hex(ios_base& __base) { @@ -565,6 +808,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::oct, ios_base::basefield). inline ios_base& oct(ios_base& __base) { @@ -572,7 +816,8 @@ namespace std 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) { @@ -580,6 +825,7 @@ namespace std return __base; } + /// Calls base.setf(ios_base::scientific, ios_base::floatfield). inline ios_base& scientific(ios_base& __base) { diff --git a/libstdc++-v3/include/bits/stl_deque.h b/libstdc++-v3/include/bits/stl_deque.h index 7dbbbea7e83..454fed31bf7 100644 --- a/libstdc++-v3/include/bits/stl_deque.h +++ b/libstdc++-v3/include/bits/stl_deque.h @@ -1280,7 +1280,8 @@ namespace std } // called by the second initialize_dispatch above - /** @{ + //@{ + /** * @if maint * @brief Fills the deque with whatever is in [first,last). * @param first An input iterator. @@ -1302,7 +1303,7 @@ namespace std void _M_range_initialize(_ForwardIterator __first, _ForwardIterator __last, forward_iterator_tag); - /** @} */ + //@} /** * @if maint @@ -1383,7 +1384,8 @@ namespace std } - /** @{ + //@{ + /** * @if maint * @brief Helper functions for push_* and pop_*. * @endif @@ -1396,7 +1398,7 @@ namespace std #endif void _M_pop_back_aux(); void _M_pop_front_aux(); - /** @} */ + //@} // Internal insert functions follow. The *_aux functions do the actual @@ -1462,7 +1464,8 @@ namespace std iterator _M_insert_aux(iterator __pos); #endif - /** @{ + //@{ + /** * @if maint * @brief Memory-handling helpers for the previous internal insert * functions. @@ -1491,10 +1494,11 @@ namespace std void _M_new_elements_at_back(size_type __new_elements); - /** @} */ + //@} - /** @{ + //@{ + /** * @if maint * @brief Memory-handling helpers for the major %map. * @@ -1519,7 +1523,7 @@ namespace std void _M_reallocate_map(size_type __nodes_to_add, bool __add_at_front); - /** @} */ + //@} }; diff --git a/libstdc++-v3/include/bits/stl_iterator_base_types.h b/libstdc++-v3/include/bits/stl_iterator_base_types.h index e7f131280c3..8b040e49602 100644 --- a/libstdc++-v3/include/bits/stl_iterator_base_types.h +++ b/libstdc++-v3/include/bits/stl_iterator_base_types.h @@ -68,7 +68,8 @@ 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 diff --git a/libstdc++-v3/include/std/std_fstream.h b/libstdc++-v3/include/std/std_fstream.h index c3861051d40..685a38dd944 100644 --- a/libstdc++-v3/include/std/std_fstream.h +++ b/libstdc++-v3/include/std/std_fstream.h @@ -50,6 +50,15 @@ 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 class basic_filebuf : public basic_streambuf<_CharT, _Traits> { @@ -61,7 +70,12 @@ namespace std 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 __streambuf_type; typedef basic_filebuf __filebuf_type; typedef __basic_file __file_type; @@ -69,22 +83,43 @@ namespace std typedef codecvt __codecvt_type; typedef typename __codecvt_type::result __res_type; typedef ctype __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? @@ -92,12 +127,26 @@ namespace std // 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() { @@ -106,23 +155,61 @@ namespace std } // 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(); @@ -137,15 +224,23 @@ namespace std // 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()); @@ -157,6 +252,8 @@ namespace std // 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()); @@ -167,25 +264,50 @@ namespace std // 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() { @@ -207,9 +329,11 @@ namespace std return 0; } + // [documentation is inherited] virtual void imbue(const locale& __loc); + // [documentation is inherited] virtual streamsize xsgetn(char_type* __s, streamsize __n) { @@ -231,6 +355,7 @@ namespace std return __ret; } + // [documentation is inherited] virtual streamsize xsputn(const char_type* __s, streamsize __n) { @@ -238,6 +363,11 @@ namespace std return __streambuf_type::xsputn(__s, __n); } + /** + * @if maint + * @doctodo + * @endif + */ void _M_output_unshift(); @@ -248,6 +378,11 @@ namespace std // 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) { @@ -258,6 +393,11 @@ namespace std _M_filepos = _M_buf; } + /** + * @if maint + * @doctodo + * @endif + */ void _M_set_determinate(off_type __off) { @@ -270,6 +410,11 @@ namespace std _M_filepos = _M_buf + __off; } + /** + * @if maint + * @doctodo + * @endif + */ bool _M_is_indeterminate(void) { @@ -286,7 +431,7 @@ namespace std } }; - // Explicit specializations. + // Explicit specializations, defined in src/fstream.cc. template<> basic_filebuf::int_type basic_filebuf::_M_underflow_common(bool __bump); @@ -297,9 +442,14 @@ namespace std basic_filebuf::_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 class basic_ifstream : public basic_istream<_CharT, _Traits> @@ -317,20 +467,33 @@ namespace std typedef basic_istream __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. */ @@ -342,21 +505,44 @@ namespace std 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) { @@ -364,7 +550,12 @@ namespace std 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() { @@ -374,9 +565,14 @@ namespace std }; - // 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 class basic_ofstream : public basic_ostream<_CharT,_Traits> @@ -394,20 +590,34 @@ namespace std typedef basic_ostream __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. */ @@ -420,29 +630,40 @@ namespace std 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. @@ -455,7 +676,12 @@ namespace std 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() { @@ -465,9 +691,14 @@ namespace std }; - // 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 class basic_fstream : public basic_iostream<_CharT, _Traits> @@ -486,18 +717,29 @@ namespace std typedef basic_iostream __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 @@ -512,29 +754,40 @@ namespace std 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. @@ -547,7 +800,12 @@ namespace std 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() { diff --git a/libstdc++-v3/include/std/std_iomanip.h b/libstdc++-v3/include/std/std_iomanip.h index 23237ce210d..26756a8041c 100644 --- a/libstdc++-v3/include/std/std_iomanip.h +++ b/libstdc++-v3/include/std/std_iomanip.h @@ -47,8 +47,18 @@ 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) { @@ -76,6 +86,13 @@ namespace std 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) { @@ -103,6 +120,14 @@ namespace std 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) { @@ -137,6 +162,13 @@ namespace std template 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 inline _Setfill<_CharT> setfill(_CharT __c) @@ -165,6 +197,13 @@ namespace std 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) { @@ -192,6 +231,13 @@ namespace std 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) { diff --git a/libstdc++-v3/include/std/std_iosfwd.h b/libstdc++-v3/include/std/std_iosfwd.h index 797f4936dc8..124c8ffc5ff 100644 --- a/libstdc++-v3/include/std/std_iosfwd.h +++ b/libstdc++-v3/include/std/std_iosfwd.h @@ -102,35 +102,64 @@ namespace std class ios_base; #endif - typedef basic_ios ios; - typedef basic_streambuf streambuf; - typedef basic_istream istream; - typedef basic_ostream ostream; - typedef basic_iostream iostream; - typedef basic_stringbuf stringbuf; - typedef basic_istringstream istringstream; - typedef basic_ostringstream ostringstream; - typedef basic_stringstream stringstream; - typedef basic_filebuf filebuf; - typedef basic_ifstream ifstream; - typedef basic_ofstream ofstream; - typedef basic_fstream 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 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 ios; ///< @isiosfwd + typedef basic_streambuf streambuf; ///< @isiosfwd + typedef basic_istream istream; ///< @isiosfwd + typedef basic_ostream ostream; ///< @isiosfwd + typedef basic_iostream iostream; ///< @isiosfwd + typedef basic_stringbuf stringbuf; ///< @isiosfwd + typedef basic_istringstream istringstream; ///< @isiosfwd + typedef basic_ostringstream ostringstream; ///< @isiosfwd + typedef basic_stringstream stringstream; ///< @isiosfwd + typedef basic_filebuf filebuf; ///< @isiosfwd + typedef basic_ifstream ifstream; ///< @isiosfwd + typedef basic_ofstream ofstream; ///< @isiosfwd + typedef basic_fstream fstream; ///< @isiosfwd #ifdef _GLIBCPP_USE_WCHAR_T - typedef basic_ios wios; - typedef basic_streambuf wstreambuf; - typedef basic_istream wistream; - typedef basic_ostream wostream; - typedef basic_iostream wiostream; - typedef basic_stringbuf wstringbuf; - typedef basic_istringstream wistringstream; - typedef basic_ostringstream wostringstream; - typedef basic_stringstream wstringstream; - typedef basic_filebuf wfilebuf; - typedef basic_ifstream wifstream; - typedef basic_ofstream wofstream; - typedef basic_fstream wfstream; + typedef basic_ios wios; ///< @isiosfwd + typedef basic_streambuf wstreambuf; ///< @isiosfwd + typedef basic_istream wistream; ///< @isiosfwd + typedef basic_ostream wostream; ///< @isiosfwd + typedef basic_iostream wiostream; ///< @isiosfwd + typedef basic_stringbuf wstringbuf; ///< @isiosfwd + typedef basic_istringstream wistringstream; ///< @isiosfwd + typedef basic_ostringstream wostringstream; ///< @isiosfwd + typedef basic_stringstream wstringstream; ///< @isiosfwd + typedef basic_filebuf wfilebuf; ///< @isiosfwd + typedef basic_ifstream wifstream; ///< @isiosfwd + typedef basic_ofstream wofstream; ///< @isiosfwd + typedef basic_fstream wfstream; ///< @isiosfwd #endif + /** @} */ } // namespace std #endif diff --git a/libstdc++-v3/include/std/std_iostream.h b/libstdc++-v3/include/std/std_iostream.h index d0736b83513..d70949377df 100644 --- a/libstdc++-v3/include/std/std_iostream.h +++ b/libstdc++-v3/include/std/std_iostream.h @@ -47,17 +47,31 @@ namespace std { - extern istream cin; - extern ostream cout; - extern ostream cerr; - extern ostream clog; + /** + * @name Standard Stream Objects + * + * The <iostream> header declares the eight standard stream + * objects. 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; diff --git a/libstdc++-v3/include/std/std_istream.h b/libstdc++-v3/include/std/std_istream.h index 8aa9123ed5c..7e050322328 100644 --- a/libstdc++-v3/include/std/std_istream.h +++ b/libstdc++-v3/include/std/std_istream.h @@ -46,7 +46,14 @@ 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 class basic_istream : virtual public basic_ios<_CharT, _Traits> { @@ -68,10 +75,23 @@ namespace std 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) { @@ -79,16 +99,29 @@ namespace std _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&)); @@ -97,8 +130,36 @@ namespace std __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 formatted 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 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); @@ -140,92 +201,444 @@ namespace std __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::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 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 basic_istream<_CharT, _Traits>& operator>>(basic_istream<_CharT, _Traits>& __in, _CharT& __c); @@ -239,7 +652,34 @@ namespace std basic_istream& operator>>(basic_istream& __in, signed char& __c) { return (__in >> reinterpret_cast(__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 basic_istream<_CharT, _Traits>& operator>>(basic_istream<_CharT, _Traits>& __in, _CharT* __s); @@ -253,8 +693,15 @@ namespace std basic_istream& operator>>(basic_istream& __in, signed char* __s) { return (__in >> reinterpret_cast(__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 class basic_iostream : public basic_istream<_CharT, _Traits>, @@ -275,16 +722,45 @@ namespace std 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 basic_istream<_CharT, _Traits>& ws(basic_istream<_CharT, _Traits>& __is); diff --git a/libstdc++-v3/include/std/std_ostream.h b/libstdc++-v3/include/std/std_ostream.h index eff4bb5119f..7a553296102 100644 --- a/libstdc++-v3/include/std/std_ostream.h +++ b/libstdc++-v3/include/std/std_ostream.h @@ -46,7 +46,14 @@ 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 class basic_ostream : virtual public basic_ios<_CharT, _Traits> { @@ -66,20 +73,40 @@ namespace std 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&)); @@ -88,8 +115,35 @@ namespace std __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 formatted output + * functions) 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); @@ -150,31 +204,140 @@ namespace std __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 class basic_ostream<_CharT, _Traits>::sentry { @@ -183,9 +346,27 @@ namespace std 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 @@ -197,10 +378,34 @@ namespace std } } + /** + * @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 basic_ostream<_CharT, _Traits>& operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c); @@ -225,7 +430,22 @@ namespace std basic_ostream& operator<<(basic_ostream& __out, unsigned char __c) { return (__out << static_cast(__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 basic_ostream<_CharT, _Traits>& operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s); @@ -249,18 +469,38 @@ namespace std basic_ostream & operator<<(basic_ostream& __out, const unsigned char* __s) { return (__out << reinterpret_cast(__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 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 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 basic_ostream<_CharT, _Traits>& flush(basic_ostream<_CharT, _Traits>& __os) diff --git a/libstdc++-v3/include/std/std_sstream.h b/libstdc++-v3/include/std/std_sstream.h index 6ee75053148..aaec83f082b 100644 --- a/libstdc++-v3/include/std/std_sstream.h +++ b/libstdc++-v3/include/std/std_sstream.h @@ -46,6 +46,18 @@ 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 class basic_stringbuf : public basic_streambuf<_CharT, _Traits> { @@ -61,22 +73,48 @@ namespace std 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 __streambuf_type; typedef basic_string __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) @@ -84,6 +122,14 @@ namespace std { _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 { @@ -102,6 +148,13 @@ namespace std 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) { @@ -112,6 +165,11 @@ namespace std protected: // Common initialization code for both ctors goes here. + /** + * @if maint + * @doctodo + * @endif + */ void _M_stringbuf_init(ios_base::openmode __mode) { @@ -135,6 +193,7 @@ namespace std } // Overridden virtual functions: + // [documentation is inherited] virtual int_type underflow() { @@ -144,12 +203,25 @@ namespace std 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) { @@ -161,10 +233,12 @@ namespace std 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); @@ -175,6 +249,11 @@ namespace std // 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) { @@ -196,7 +275,15 @@ namespace std }; - // 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 class basic_istringstream : public basic_istream<_CharT, _Traits> { @@ -218,40 +305,104 @@ namespace std typedef basic_istream __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 class basic_ostringstream : public basic_ostream<_CharT, _Traits> { @@ -273,40 +424,104 @@ namespace std typedef basic_ostream __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 class basic_stringstream : public basic_iostream<_CharT, _Traits> { @@ -328,33 +543,85 @@ namespace std typedef basic_iostream __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); } diff --git a/libstdc++-v3/include/std/std_streambuf.h b/libstdc++-v3/include/std/std_streambuf.h index ecd546e85a8..883401bf6ee 100644 --- a/libstdc++-v3/include/std/std_streambuf.h +++ b/libstdc++-v3/include/std/std_streambuf.h @@ -50,28 +50,104 @@ namespace std { + /** + * @if maint + * Does stuff. + * @endif + */ template 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 beginning pointer, or lowest element address in the + * array (called @e xbeg here); + * - the next pointer, or next element address that is a + * current candidate for reading or writing (called @e xnext here); + * - the end pointer, 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 write position 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 putback position 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 read position 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 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 __ctype_type; typedef basic_streambuf __streambuf_type; typedef typename traits_type::state_type __state_type; + //@} friend class basic_ios; friend class basic_istream; @@ -84,56 +160,100 @@ namespace std __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. @@ -236,6 +356,7 @@ namespace std } public: + /// Destructor deallocates no buffer space. virtual ~basic_streambuf() { @@ -246,7 +367,14 @@ namespace std _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) { @@ -255,6 +383,14 @@ namespace std 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 { @@ -264,7 +400,15 @@ namespace std 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); } @@ -281,9 +425,17 @@ namespace std 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() { @@ -304,6 +456,13 @@ namespace std 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() { @@ -312,9 +471,25 @@ namespace std ? __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() { @@ -326,26 +501,84 @@ namespace std 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), @@ -355,7 +588,18 @@ namespace std _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; } @@ -364,10 +608,25 @@ namespace std 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) { @@ -378,7 +637,18 @@ namespace std _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; } @@ -387,10 +657,24 @@ namespace std 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) { @@ -400,8 +684,19 @@ namespace std _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) { @@ -410,35 +705,126 @@ namespace std _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* 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 pending sequence. + * + * 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 pending sequence. + * + * 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() { @@ -455,23 +841,78 @@ namespace std 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() { -- 2.11.4.GIT