Skip to content

R
riscv-gcc-1
Commit 840ceb34 by Phil Edwards
Options

TODO: Note change in clause 27 docs. 

2002-11-21  Phil Edwards  <pme@gcc.gnu.org>

	* docs/doxygen/TODO:  Note change in clause 27 docs.
	* include/bits/basic_ios.h, include/bits/fpos.h,
	include/bits/ios_base.h, include/bits/stl_deque.h,
	include/bits/stl_iterator_base_types.h, include/std/std_fstream.h,
	include/std/std_iomanip.h, include/std/std_iosfwd.h,
	include/std/std_iostream.h, include/std/std_istream.h,
	include/std/std_ostream.h, include/std/std_sstream.h,
	include/std/std_streambuf.h:  Doxygenate all I/O entities.

From-SVN: r59325
parent 02f0f531
Showing with 2477 additions and 205 deletions
libstdc++-v3/ChangeLog
2002-11-21 Phil Edwards <pme@gcc.gnu.org>
* docs/doxygen/TODO: Note change in clause 27 docs.
* include/bits/basic_ios.h, include/bits/fpos.h,
include/bits/ios_base.h, include/bits/stl_deque.h,
include/bits/stl_iterator_base_types.h, include/std/std_fstream.h,
include/std/std_iomanip.h, include/std/std_iosfwd.h,
include/std/std_iostream.h, include/std/std_istream.h,
include/std/std_ostream.h, include/std/std_sstream.h,
include/std/std_streambuf.h: Doxygenate all I/O entities.
2002-11-20 Benjamin Kosnik <bkoz@redhat.com>
Jonathan Lennox <lennox@cs.columbia.edu>
......
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 <complex>, <valarray>, stl_numeric.h[26.4], Note A
c27 Untouched
c27 ios_base callbacks and local storage
basic_ios::copyfmt()
std_streambuf.h's __copy_streambufs()
" " _M_* protected memfns (data has been done)
fstream and sstream protected members
backward/* Not scanned by doxygen. Should it be? Doubtful.
......
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<typename _CharT, typename _Traits>
class basic_ios : public ios_base
{
public:
// Types:
typedef _CharT char_type;
typedef typename _Traits::int_type int_type;
typedef typename _Traits::pos_type pos_type;
typedef typename _Traits::off_type off_type;
typedef _Traits traits_type;
// Non-standard Types:
typedef ctype<_CharT> __ctype_type;
typedef ostreambuf_iterator<_CharT, _Traits> __ostreambuf_iter;
typedef num_put<_CharT, __ostreambuf_iter> __numput_type;
typedef istreambuf_iterator<_CharT, _Traits> __istreambuf_iter;
typedef num_get<_CharT, __istreambuf_iter> __numget_type;
//@{
/**
* These are standard types. They permit a standardized way of
* referring to names of (or names dependant on) the template
* parameters, which are specific to the implementation.
*/
typedef _CharT char_type;
typedef typename _Traits::int_type int_type;
typedef typename _Traits::pos_type pos_type;
typedef typename _Traits::off_type off_type;
typedef _Traits traits_type;
//@}
//@{
/**
* @if maint
* These are non-standard types.
* @endif
*/
typedef ctype<_CharT> __ctype_type;
typedef ostreambuf_iterator<_CharT, _Traits> __ostreambuf_iter;
typedef num_put<_CharT, __ostreambuf_iter> __numput_type;
typedef istreambuf_iterator<_CharT, _Traits> __istreambuf_iter;
typedef num_get<_CharT, __istreambuf_iter> __numget_type;
//@}
// Data members:
protected:
basic_ostream<_CharT, _Traits>* _M_tie;
mutable char_type _M_fill;
mutable bool _M_fill_init;
basic_streambuf<_CharT, _Traits>* _M_streambuf;
basic_ostream<_CharT, _Traits>* _M_tie;
mutable char_type _M_fill;
mutable bool _M_fill_init;
basic_streambuf<_CharT, _Traits>* _M_streambuf;
// Cached use_facet<ctype>, which is based on the current locale info.
const __ctype_type* _M_fctype;
const __ctype_type* _M_fctype;
// From ostream.
const __numput_type* _M_fnumput;
const __numput_type* _M_fnumput;
// From istream.
const __numget_type* _M_fnumget;
const __numget_type* _M_fnumget;
public:
//@{
/**
* @brief The quick-and-easy status check.
*
* This allows you to write constructs such as
* "if (!a_stream) ..." and "while (a_stream) ..."
*/
operator void*() const
{ return this->fail() ? 0 : const_cast<basic_ios*>(this); }
bool
operator!() const
{ return this->fail(); }
//@}
/**
* @brief Returns the error state of the stream buffer.
* @return A bit pattern (well, isn't everything?)
*
* See std::ios_base::iostate for the possible bit values. Most
* users will call one of the interpreting wrappers, e.g., good().
*/
iostate
rdstate() const
{ return _M_streambuf_state; }
/**
* @brief [Re]sets the error state.
* @param state The new state flag(s) to set.
*
* See std::ios_base::iostate for the possible bit values. Most
* users will not need to pass an argument.
*/
void
clear(iostate __state = goodbit);
/**
* @brief Sets additional flags in the error state.
* @param state The additional state flag(s) to set.
*
* See std::ios_base::iostate for the possible bit values.
*/
void
setstate(iostate __state)
{ this->clear(this->rdstate() | __state); }
/**
* @brief Fast error checking.
* @return True if no error flags are set.
*
* A wrapper around rdstate.
*/
bool
good() const
{ return this->rdstate() == 0; }
/**
* @brief Fast error checking.
* @return True if the eofbit is set.
*
* Note that other iostate flags may also be set.
*/
bool
eof() const
{ return (this->rdstate() & eofbit) != 0; }
/**
* @brief Fast error checking.
* @return True if either the badbit or the failbit is set.
*
* Checking the badbit in fail() is historical practice.
* Note that other iostate flags may also be set.
*/
bool
fail() const
{ return (this->rdstate() & (badbit | failbit)) != 0; }
/**
* @brief Fast error checking.
* @return True if the badbit is set.
*
* Note that other iostate flags may also be set.
*/
bool
bad() const
{ return (this->rdstate() & badbit) != 0; }
/**
* @brief Throwing exceptions on errors.
* @return The current exceptions mask.
*
* This changes nothing in the stream. See the one-argument version
* of exceptions(iostate) for the meaning of the return value.
*/
iostate
exceptions() const
{ return _M_exception; }
/**
* @brief Throwing exceptions on errors.
* @param except The new exceptions mask.
*
* By default, error flags are set silently. You can set an
* exceptions mask for each stream; if a bit in the mask becomes set
* in the error flags, then an exception of type
* std::ios_base::failure is thrown.
*
* If the error flage is already set when the exceptions mask is
* added, the exception is immediately thrown. Try running the
* following under GCC 3.1 or later:
* @code
* #include <iostream>
* #include <fstream>
* #include <exception>
*
* int main()
* {
* std::set_terminate (__gnu_cxx::__verbose_terminate_handler);
*
* std::ifstream f ("/etc/motd");
*
* std::cerr << "Setting badbit\n";
* f.setstate (std::ios_base::badbit);
*
* std::cerr << "Setting exception mask\n";
* f.exceptions (std::ios_base::badbit);
* }
* @endcode
*/
void
exceptions(iostate __except)
{
_M_exception = __except;
this->clear(_M_streambuf_state);
_M_exception = __except;
this->clear(_M_streambuf_state);
}
// Constructor/destructor:
/**
* @brief Constructor performs initialization.
*
* The parameter is passed by derived streams.
*/
explicit
basic_ios(basic_streambuf<_CharT, _Traits>* __sb) : ios_base()
{ this->init(__sb); }
/**
* @brief Empty.
*
* The destructor does nothing. More specifically, it does not
* destroy the streambuf held by rdbuf().
*/
virtual
~basic_ios() { }
// Members:
/**
* @brief Fetches the current @e tied stream.
* @return A pointer to the tied stream, or NULL if the stream is
* not tied.
*
* A stream may be @e tied (or synchronized) to a second output
* stream. When this stream performs any I/O, the tied stream is
* first flushed. For example, @c std::cin is tied to @c std::cout.
*/
basic_ostream<_CharT, _Traits>*
tie() const
{ return _M_tie; }
/**
* @brief Ties this stream to an output stream.
* @param tiestr The output stream.
* @return The previously tied output stream, or NULL if the stream
* was not tied.
*
* This sets up a new tie; see tie() for more.
*/
basic_ostream<_CharT, _Traits>*
tie(basic_ostream<_CharT, _Traits>* __tiestr)
{
basic_ostream<_CharT, _Traits>* __old = _M_tie;
_M_tie = __tiestr;
return __old;
basic_ostream<_CharT, _Traits>* __old = _M_tie;
_M_tie = __tiestr;
return __old;
}
/**
* @brief Accessing the underlying buffer.
* @return The current stream buffer.
*
* This does not change the state of the stream.
*/
basic_streambuf<_CharT, _Traits>*
rdbuf() const
{ return _M_streambuf; }
/**
* @brief Changing the underlying buffer.
* @param sb The new stream buffer.
* @return The previous stream buffer.
*
* Associates a new buffer with the current stream, and clears the
* error state.
*
* Due to historical accidents which the LWG refuses to correct, the
* I/O library suffers from a design error: this function is hidden
* in derived classes by overrides of the zero-argument @c rdbuf(),
* which is non-virtual for hysterical raisins. As a result, you
* must use explicit qualifications to access this function via any
* derived class.
*/
basic_streambuf<_CharT, _Traits>*
rdbuf(basic_streambuf<_CharT, _Traits>* __sb);
/**
* @doctodo
*/
basic_ios&
copyfmt(const basic_ios& __rhs);
/**
* @brief Retreives the "empty" character.
* @return The current fill character.
*
* It defaults to a space (' ') in the current locale.
*/
char_type
fill() const
{
......@@ -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<P. It defaults to a space (' ') in the current locale.
*/
char_type
fill(char_type __ch)
{
......@@ -172,20 +348,75 @@ namespace std
}
// Locales:
/**
* @brief Moves to a new locale.
* @param loc The new locale.
* @return The previous locale.
*
* Calls @c ios_base::imbue(loc), and if a stream buffer is associated
* with this stream, calls that buffer's @c pubimbue(loc).
*
* Additional l10n notes are at
* http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
*/
locale
imbue(const locale& __loc);
/**
* @brief Squeezes characters.
* @param c The character to narrow.
* @param dfault The character to narrow.
* @return The narrowed character.
*
* Maps a character of @c char_type to a character of @c char,
* if possible.
*
* Returns the result of
* @code
* std::use_facet< ctype<char_type> >(getloc()).narrow(c,dfault)
* @endcode
*
* Additional l10n notes are at
* http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
*/
char
narrow(char_type __c, char __dfault) const;
/**
* @brief Widens characters.
* @param c The character to widen.
* @return The widened character.
*
* Maps a character of @c char to a character of @c char_type.
*
* Returns the result of
* @code
* std::use_facet< ctype<char_type> >(getloc()).widen(c)
* @endcode
*
* Additional l10n notes are at
* http://gcc.gnu.org/onlinedocs/libstdc++/22_locale/howto.html
*/
char_type
widen(char __c) const;
protected:
// 27.4.5.1 basic_ios constructors
/**
* @brief Empty.
*
* The default constructor does nothing and is not normally
* accessible to users.
*/
basic_ios() : ios_base()
{ }
/**
* @brief All setup is performed here.
*
* This is called from the public constructor. It is not virtual and
* cannot be redefined.
*/
void
init(basic_streambuf<_CharT, _Traits>* __sb);
......
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<typename _StateT>
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<mbstate_t> streampos;
# ifdef _GLIBCPP_USE_WCHAR_T
/// 27.2, paragraph 10 about fpos/char_traits circularity
typedef fpos<mbstate_t> wstreampos;
# endif
} // namespace std
......
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)
{
......
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);
/** @} */
//@}
};
......
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
......
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<typename _CharT, typename _Traits>
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<char_type, traits_type> __streambuf_type;
typedef basic_filebuf<char_type, traits_type> __filebuf_type;
typedef __basic_file<char> __file_type;
......@@ -69,22 +83,43 @@ namespace std
typedef codecvt<char_type, char, __state_type> __codecvt_type;
typedef typename __codecvt_type::result __res_type;
typedef ctype<char_type> __ctype_type;
//@}
friend class ios_base; // For sync_with_stdio.
protected:
// Data Members:
// MT lock inherited from libio or other low-level io library.
/**
* @if maint
* @doctodo
* @endif
*/
__c_lock _M_lock;
// External buffer.
/**
* @if maint
* @doctodo
* @endif
*/
__file_type _M_file;
// Current and beginning state type for codecvt.
/**
* @if maint
* @doctodo
* @endif
*/
__state_type _M_state_cur;
__state_type _M_state_beg;
// Set iff _M_buf is allocated memory from _M_allocate_internal_buffer.
/**
* @if maint
* @doctodo
* @endif
*/
bool _M_buf_allocated;
// XXX Needed?
......@@ -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<char>::int_type
basic_filebuf<char>::_M_underflow_common(bool __bump);
......@@ -297,9 +442,14 @@ namespace std
basic_filebuf<wchar_t>::_M_underflow_common(bool __bump);
#endif
// 27.8.1.5 Template class basic_ifstream
// [27.8.1.5] Template class basic_ifstream
/**
* Derivation of general input streams, specific to files.
* @brief Controlling input for files.
*
* This class supports reading from named files, using the inherited
* functions from std::basic_istream. To control the associated
* sequence, an instance of std::basic_filebuf is used, which this page
* refers to as @c sb.
*/
template<typename _CharT, typename _Traits>
class basic_ifstream : public basic_istream<_CharT, _Traits>
......@@ -317,20 +467,33 @@ namespace std
typedef basic_istream<char_type, traits_type> __istream_type;
private:
/**
* @if maint
* @doctodo
* @endif
*/
__filebuf_type _M_filebuf;
public:
// Constructors/Destructors:
/** Default constructor. Create an input file stream. */
// Constructors/Destructors:
/**
* @brief Default constructor.
*
* Initializes @c sb using its default constructor, and passes
* @c &sb to the base class initializer. Does not open any files
* (you haven't given it a filename to open).
*/
basic_ifstream()
: __istream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
* @brief Create an input file stream.
* @param s Null terminated string specifying filename.
* @brief Create an input file stream.
* @param s Null terminated string specifying the filename.
* @param mode Open file in specified mode (see std::ios_base).
*
* @c ios_base::in is automatically included in @a mode.
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
......@@ -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<typename _CharT, typename _Traits>
class basic_ofstream : public basic_ostream<_CharT,_Traits>
......@@ -394,20 +590,34 @@ namespace std
typedef basic_ostream<char_type, traits_type> __ostream_type;
private:
/**
* @if maint
* @doctodo
* @endif
*/
__filebuf_type _M_filebuf;
public:
// Constructors:
/** Default constructor for output file_stream. */
/**
* @brief Default constructor.
*
* Initializes @c sb using its default constructor, and passes
* @c &sb to the base class initializer. Does not open any files
* (you haven't given it a filename to open).
*/
basic_ofstream()
: __ostream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
* @brief Create an output stream.
* @param s Null terminated string specifying filename.
* @brief Create an output file stream.
* @param s Null terminated string specifying the filename.
* @param mode Open file in specified mode (see std::ios_base).
*
* @c ios_base::out|ios_base::trunc is automatically included in
* @a mode.
*
* Tip: When using std::string to hold the filename, you must use
* .c_str() before passing it to this constructor.
*/
......@@ -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<typename _CharT, typename _Traits>
class basic_fstream : public basic_iostream<_CharT, _Traits>
......@@ -486,18 +717,29 @@ namespace std
typedef basic_iostream<char_type, traits_type> __iostream_type;
private:
/**
* @if maint
* @doctodo
* @endif
*/
__filebuf_type _M_filebuf;
public:
// Constructors/destructor:
/** Default constructor. Create a file stream. */
/**
* @brief Default constructor.
*
* Initializes @c sb using its default constructor, and passes
* @c &sb to the base class initializer. Does not open any files
* (you haven't given it a filename to open).
*/
basic_fstream()
: __iostream_type(NULL), _M_filebuf()
{ this->init(&_M_filebuf); }
/**
* @brief Create an input/output stream.
* @param s Null terminated string specifying filename.
* @brief Create an input/output file stream.
* @param s Null terminated string specifying the filename.
* @param mode Open file in specified mode (see std::ios_base).
*
* Tip: When using std::string to hold the filename, you must use
......@@ -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()
{
......
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<typename _CharT>
struct _Setfill { _CharT _M_c; };
/**
* @brief Manipulator for @c fill.
* @param c The new fill character.
*
* Sent to a stream object, this manipulator calls @c fill(c) for that
* object.
*/
template<typename _CharT>
inline _Setfill<_CharT>
setfill(_CharT __c)
......@@ -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)
{
......
libstdc++-v3/include/std/std_iosfwd.h
......@@ -102,35 +102,64 @@ namespace std
class ios_base;
#endif
typedef basic_ios<char> ios;
typedef basic_streambuf<char> streambuf;
typedef basic_istream<char> istream;
typedef basic_ostream<char> ostream;
typedef basic_iostream<char> iostream;
typedef basic_stringbuf<char> stringbuf;
typedef basic_istringstream<char> istringstream;
typedef basic_ostringstream<char> ostringstream;
typedef basic_stringstream<char> stringstream;
typedef basic_filebuf<char> filebuf;
typedef basic_ifstream<char> ifstream;
typedef basic_ofstream<char> ofstream;
typedef basic_fstream<char> fstream;
/**
* @defgroup s27_2_iosfwd I/O Forward Declarations
*
* Nearly all of the I/O classes are parameterized on the type of
* characters they read and write. (The major exception is ios_base at
* the top of the hierarchy.) This is a change from pre-Standard
* streams, which were not templates.
*
* For ease of use and compatibility, all of the basic_* I/O-related
* classes are given typedef names for both of the builtin character
* widths (wide and narrow). The typedefs are the same as the
* pre-Standard names, for example:
*
* @code
* typedef basic_ifstream<char> ifstream;
* @endcode
*
* Because properly forward-declaring these classes can be difficult, you
* should not do it yourself. Instead, include the &lt;iosfwd&gt;
* header, which contains only declarations of all the I/O classes as
* well as the typedefs. Trying to forward-declare the typedefs
* themselves (e.g., "class ostream;") is not valid ISO C++.
*
* For more specific declarations, see
* http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#10
*
* @{
*/
typedef basic_ios<char> ios; ///< @isiosfwd
typedef basic_streambuf<char> streambuf; ///< @isiosfwd
typedef basic_istream<char> istream; ///< @isiosfwd
typedef basic_ostream<char> ostream; ///< @isiosfwd
typedef basic_iostream<char> iostream; ///< @isiosfwd
typedef basic_stringbuf<char> stringbuf; ///< @isiosfwd
typedef basic_istringstream<char> istringstream; ///< @isiosfwd
typedef basic_ostringstream<char> ostringstream; ///< @isiosfwd
typedef basic_stringstream<char> stringstream; ///< @isiosfwd
typedef basic_filebuf<char> filebuf; ///< @isiosfwd
typedef basic_ifstream<char> ifstream; ///< @isiosfwd
typedef basic_ofstream<char> ofstream; ///< @isiosfwd
typedef basic_fstream<char> fstream; ///< @isiosfwd
#ifdef _GLIBCPP_USE_WCHAR_T
typedef basic_ios<wchar_t> wios;
typedef basic_streambuf<wchar_t> wstreambuf;
typedef basic_istream<wchar_t> wistream;
typedef basic_ostream<wchar_t> wostream;
typedef basic_iostream<wchar_t> wiostream;
typedef basic_stringbuf<wchar_t> wstringbuf;
typedef basic_istringstream<wchar_t> wistringstream;
typedef basic_ostringstream<wchar_t> wostringstream;
typedef basic_stringstream<wchar_t> wstringstream;
typedef basic_filebuf<wchar_t> wfilebuf;
typedef basic_ifstream<wchar_t> wifstream;
typedef basic_ofstream<wchar_t> wofstream;
typedef basic_fstream<wchar_t> wfstream;
typedef basic_ios<wchar_t> wios; ///< @isiosfwd
typedef basic_streambuf<wchar_t> wstreambuf; ///< @isiosfwd
typedef basic_istream<wchar_t> wistream; ///< @isiosfwd
typedef basic_ostream<wchar_t> wostream; ///< @isiosfwd
typedef basic_iostream<wchar_t> wiostream; ///< @isiosfwd
typedef basic_stringbuf<wchar_t> wstringbuf; ///< @isiosfwd
typedef basic_istringstream<wchar_t> wistringstream; ///< @isiosfwd
typedef basic_ostringstream<wchar_t> wostringstream; ///< @isiosfwd
typedef basic_stringstream<wchar_t> wstringstream; ///< @isiosfwd
typedef basic_filebuf<wchar_t> wfilebuf; ///< @isiosfwd
typedef basic_ifstream<wchar_t> wifstream; ///< @isiosfwd
typedef basic_ofstream<wchar_t> wofstream; ///< @isiosfwd
typedef basic_fstream<wchar_t> wfstream; ///< @isiosfwd
#endif
/** @} */
} // namespace std
#endif
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 &lt;iostream&gt; header declares the eight <em>standard stream
* objects</em>. For other declarations, see
* http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#10 and the
* @link s27_2_iosfwd I/O forward declarations @endlink
*
* They are required by default to cooperate with the global C library's
* @c FILE streams, and to be available during program startup and
* termination. For more information, see the HOWTO linked to above.
*/
//@{
extern istream cin; ///< Linked to standard input
extern ostream cout; ///< Linked to standard output
extern ostream cerr; ///< Linked to standard error (unbuffered)
extern ostream clog; ///< Linked to standard error (buffered)
#ifdef _GLIBCPP_USE_WCHAR_T
extern wistream wcin;
extern wostream wcout;
extern wostream wcerr;
extern wostream wclog;
extern wistream wcin; ///< Linked to standard input
extern wostream wcout; ///< Linked to standard output
extern wostream wcerr; ///< Linked to standard error (unbuffered)
extern wostream wclog; ///< Linked to standard error (buffered)
#endif
//@}
// For construction of filebuffers for cout, cin, cerr, clog et. al.
static ios_base::Init __ioinit;
......
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<typename _CharT, typename _Traits>
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 <em>formatted input
* functions</em>) have some common behavior. Each starts by
* constructing a temporary object of type std::basic_istream::sentry
* with the second argument (noskipws) set to false. This has several
* effects, concluding with the setting of a status flag; see the
* sentry documentation for more.
*
* If the sentry status is good, the function tries to extract
* whatever data is appropriate for the type of the argument.
*
* If an exception is thrown during extraction, ios_base::badbit
* will be turned on in the stream's error state without causing an
* ios_base::failure to be thrown. The original exception will then
* be rethrown.
*/
//@{
/**
* @brief Basic arithmetic extractors
* @param A variable of builtin type.
* @return @c *this if successful
*
* These functions use the stream's current locale (specifically, the
* @c num_get facet) to parse the input data.
*/
__istream_type&
operator>>(bool& __n);
......@@ -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<int>::max(), @a n
* characters are extracted
* - the input sequence reaches end-of-file
* - the next character equals @a delim (in this case, the character
* is extracted); note that this condition will never occur if
* @a delim equals @c traits::eof().
*/
__istream_type&
ignore(streamsize __n = 1, int_type __delim = traits_type::eof());
/**
* @brief Looking ahead in the stream
* @return The next character, or eof().
*
* If, after constructing the sentry object, @c good() is false,
* returns @c traits::eof(). Otherwise reads but does not extract
* the next input character.
*/
int_type
peek(void);
peek();
/**
* @brief Extraction without delimiters.
* @param s A character array.
* @param n Maximum number of characters to store.
* @return *this
*
* If the stream state is @c good(), extracts characters and stores
* them into @a s until one of the following happens:
* - @a n characters are stored
* - the input sequence reaches end-of-file, in which case the error
* state is set to @c failbit|eofbit.
*
* @note This function is not overloaded on signed char and
* unsigned char.
*/
__istream_type&
read(char_type* __s, streamsize __n);
/**
* @brief Extraction until the buffer is exhausted, but no more.
* @param s A character array.
* @param n Maximum number of characters to store.
* @return The number of characters extracted.
*
* Extracts characters and stores them into @a s depending on the
* number of characters remaining in the streambuf's buffer,
* @c rdbuf()->in_avail(), called @c A here:
* - if @c A @c == @c -1, sets eofbit and extracts no characters
* - if @c A @c == @c 0, extracts no characters
* - if @c A @c > @c 0, extracts @c min(A,n)
*
* The goal is to empty the current buffer, and to not request any
* more from the external input sequence controlled by the streambuf.
*/
streamsize
readsome(char_type* __s, streamsize __n);
/**
* @brief Unextracting a single character.
* @param c The character to push back into the input stream.
* @return *this
*
* If @c rdbuf() is not null, calls @c rdbuf()->sputbackc(c).
*
* If @c rdbuf() is null or if @c sputbackc() fails, sets badbit in
* the error state.
*
* @note Since no characters are extracted, the next call to
* @c gcount() will return 0, as required by DR 60.
*
* @if maint
* FIXME We don't comply with DR 60 here, _M_gcount is untouched.
* @endif
*/
__istream_type&
putback(char_type __c);
/**
* @brief Unextracting the previous character.
* @return *this
*
* If @c rdbuf() is not null, calls @c rdbuf()->sungetc(c).
*
* If @c rdbuf() is null or if @c sungetc() fails, sets badbit in
* the error state.
*
* @note Since no characters are extracted, the next call to
* @c gcount() will return 0, as required by DR 60.
*/
__istream_type&
unget(void);
unget();
/**
* @brief Synchronizing the stream buffer.
* @return 0 on success, -1 on failure
*
* If @c rdbuf() is a null pointer, returns -1.
*
* Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
* sets badbit and returns -1.
*
* Otherwise, returns 0.
*
* @note This function does not count the number of characters
* extracted, if any, and therefore does not affect the next
* call to @c gcount().
* @if maint
* FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
* @endif
*/
int
sync(void);
sync();
/**
* @brief Getting the current read position.
* @return A file position object.
*
* If @c fail() is not false, returns @c pos_type(-1) to indicate
* failure. Otherwise returns @c rdbuf()->pubseekoff(0,cur,in).
*
* @note This function does not count the number of characters
* extracted, if any, and therefore does not affect the next
* call to @c gcount().
*/
pos_type
tellg(void);
tellg();
/**
* @brief Changing the current read position.
* @param pos A file position object.
* @return *this
*
* If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos). If
* that function fails, sets failbit.
*
* @note This function does not count the number of characters
* extracted, if any, and therefore does not affect the next
* call to @c gcount().
* @if maint
* FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
* @endif
*/
__istream_type&
seekg(pos_type);
/**
* @brief Changing the current read position.
* @param off A file offset object.
* @param dir The direction in which to seek.
* @return *this
*
* If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
* If that function fails, sets failbit.
*
* @note This function does not count the number of characters
* extracted, if any, and therefore does not affect the next
* call to @c gcount().
* @if maint
* FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
* @endif
*/
__istream_type&
seekg(off_type, ios_base::seekdir);
//@}
};
/**
* @brief Performs setup work for input streams.
*
* Objects of this class are created before all of the standard
* extractors are run. It is responsible for "exception-safe prefix and
* suffix operations," although only prefix actions are currently required
* by the standard. Additional actions may be added by the
* implementation, and we list them in
* http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5
* under [27.6] notes.
*/
template<typename _CharT, typename _Traits>
class basic_istream<_CharT, _Traits>::sentry
{
public:
/// Easy access to dependant types.
typedef _Traits traits_type;
typedef basic_streambuf<_CharT, _Traits> __streambuf_type;
typedef basic_istream<_CharT, _Traits> __istream_type;
typedef typename __istream_type::__ctype_type __ctype_type;
typedef typename _Traits::int_type __int_type;
/**
* @brief The constructor performs all the work.
* @param is The input stream to guard.
* @param noskipws Whether to consume whitespace or not.
*
* If the stream state is good (@a is.good() is true), then the
* following actions are performed, otherwise the sentry state is
* false ("not okay") and failbit is set in the stream state.
*
* The sentry's preparatory actions are:
*
* -# if the stream is tied to an output stream, @c is.tie()->flush()
* is called to synchronize the output sequence
* -# if @a noskipws is false, and @c ios_base::skipws is set in
* @c is.flags(), the sentry extracts and discards whitespace
* characters from the stream. The currently imbued locale is
* used to determine whether each character is whitespace.
*
* If the stream state is still good, then the sentry state becomes
* true ("okay").
*/
explicit
sentry(basic_istream<_CharT, _Traits>& __is, bool __noskipws = false);
/**
* @brief Quick status checking.
* @return The sentry state.
*
* For ease of use, sentries may be converted to booleans. The
* return value is that of the sentry state (true == okay).
*/
operator bool() { return _M_ok; }
private:
bool _M_ok;
};
// 27.6.1.2.3 Character extraction templates
// [27.6.1.2.3] character extraction templates
//@{
/**
* @brief Character extractors
* @param in An input stream.
* @param c A character reference.
* @return in
*
* Behaves like one of the formatted arithmetic extractors described in
* std::basic_istream. After constructing a sentry object with good
* status, this function extracts a character (if one is available) and
* stores it in @a c. Otherwise, sets failbit in the input stream.
*/
template<typename _CharT, typename _Traits>
basic_istream<_CharT, _Traits>&
operator>>(basic_istream<_CharT, _Traits>& __in, _CharT& __c);
......@@ -239,7 +652,34 @@ namespace std
basic_istream<char, _Traits>&
operator>>(basic_istream<char, _Traits>& __in, signed char& __c)
{ return (__in >> reinterpret_cast<char&>(__c)); }
//@}
//@{
/**
* @brief Character string extractors
* @param in An input stream.
* @param s A pointer to a character array.
* @return in
*
* Behaves like one of the formatted arithmetic extractors described in
* std::basic_istream. After constructing a sentry object with good
* status, this function extracts up to @c n characters and stores them
* into the array starting at @a s. @c n is defined as:
*
* - if @c width() is greater than zero, @c n is width()
* - otherwise @c n is "the number of elements of the largest array of
* @c char_type that can store a terminating @c eos." [27.6.1.2.3]/6
*
* Characters are extracted and stored until one of the following happens:
* - @c n-1 characters are stored
* - EOF is reached
* - the next character is whitespace according to the current locale
* - the next character is a null byte (i.e., @c charT() )
*
* @c width(0) is then called for the input stream.
*
* If no characters are extracted, sets failbit.
*/
template<typename _CharT, typename _Traits>
basic_istream<_CharT, _Traits>&
operator>>(basic_istream<_CharT, _Traits>& __in, _CharT* __s);
......@@ -253,8 +693,15 @@ namespace std
basic_istream<char,_Traits>&
operator>>(basic_istream<char,_Traits>& __in, signed char* __s)
{ return (__in >> reinterpret_cast<char*>(__s)); }
//@}
// 27.6.1.5 Template class basic_iostream
/**
* @brief Merging istream and ostream capabilities.
*
* This class multiply inherits from the input and output stream classes
* simply to provide a single interface.
*/
template<typename _CharT, typename _Traits>
class basic_iostream
: public basic_istream<_CharT, _Traits>,
......@@ -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<typename _CharT, typename _Traits>
basic_istream<_CharT, _Traits>&
ws(basic_istream<_CharT, _Traits>& __is);
......
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<typename _CharT, typename _Traits>
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 <em>formatted output
* functions</em>) have some common behavior. Each starts by
* constructing a temporary object of type std::basic_ostream::sentry.
* This can have several effects, concluding with the setting of a
* status flag; see the sentry documentation for more.
*
* If the sentry status is good, the function tries to generate
* whatever data is appropriate for the type of the argument.
*
* If an exception is thrown during insertion, ios_base::badbit
* will be turned on in the stream's error state without causing an
* ios_base::failure to be thrown. The original exception will then
* be rethrown.
*/
//@{
/**
* @brief Basic arithmetic inserters
* @param A variable of builtin type.
* @return @c *this if successful
*
* These functions use the stream's current locale (specifically, the
* @c num_get facet) to perform numeric formatting.
*/
__ostream_type&
operator<<(long __n);
......@@ -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 <typename _CharT, typename _Traits>
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<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
operator<<(basic_ostream<_CharT, _Traits>& __out, _CharT __c);
......@@ -225,7 +430,22 @@ namespace std
basic_ostream<char, _Traits>&
operator<<(basic_ostream<char, _Traits>& __out, unsigned char __c)
{ return (__out << static_cast<char>(__c)); }
//@}
//@{
/**
* @brief String inserters
* @param out An output stream.
* @param s A character string.
* @return out
* @pre @a s must be a non-NULL pointer
*
* Behaves like one of the formatted arithmetic inserters described in
* std::basic_ostream. After constructing a sentry object with good
* status, this function inserts @c traits::length(s) characters starting
* at @a s, widened if necessary, followed by any required padding (as
* determined by [22.2.2.2.2]). @c out.width(0) is then called.
*/
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
operator<<(basic_ostream<_CharT, _Traits>& __out, const _CharT* __s);
......@@ -249,18 +469,38 @@ namespace std
basic_ostream<char, _Traits> &
operator<<(basic_ostream<char, _Traits>& __out, const unsigned char* __s)
{ return (__out << reinterpret_cast<const char*>(__s)); }
// 27.6.2.7 Standard basic_ostream manipulators
//@}
// [27.6.2.7] standard basic_ostream manipulators
/**
* @brief Write a newline and flush the stream.
*
* This manipulator is often mistakenly used when a simple newline is
* desired, leading to poor buffering performance. See
* http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#2 for more
* on this subject.
*/
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
endl(basic_ostream<_CharT, _Traits>& __os)
{ return flush(__os.put(__os.widen('\n'))); }
/**
* @brief Write a null character into the output sequence.
*
* "Null character" is @c CharT() by definition. For CharT of @c char,
* this correctly writes the ASCII @c NUL character string terminator.
*/
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
ends(basic_ostream<_CharT, _Traits>& __os)
{ return __os.put(_CharT()); }
/**
* @brief Flushes the output stream.
*
* This manipulator simply calls the stream's @c flush() member function.
*/
template<typename _CharT, typename _Traits>
basic_ostream<_CharT, _Traits>&
flush(basic_ostream<_CharT, _Traits>& __os)
......
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<typename _CharT, typename _Traits, typename _Alloc>
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<char_type, traits_type> __streambuf_type;
typedef basic_string<char_type, _Traits, _Alloc> __string_type;
typedef typename __string_type::size_type __size_type;
//@}
protected:
// Data Members:
/**
* @if maint
* @doctodo
* @endif
*/
__string_type _M_string;
public:
// Constructors:
/**
* @brief Starts with an empty string buffer.
* @param mode Whether the buffer can read, or write, or both.
*
* The default constructor initializes the parent class using its
* own default ctor.
*/
explicit
basic_stringbuf(ios_base::openmode __mode = ios_base::in | ios_base::out)
: __streambuf_type(), _M_string()
{ _M_stringbuf_init(__mode); }
/**
* @brief Starts with an existing string buffer.
* @param str A string to copy as a starting buffer.
* @param mode Whether the buffer can read, or write, or both.
*
* This constructor initializes the parent class using its
* own default ctor.
*/
explicit
basic_stringbuf(const __string_type& __str,
ios_base::openmode __mode = ios_base::in | ios_base::out)
......@@ -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<typename _CharT, typename _Traits, typename _Alloc>
class basic_istringstream : public basic_istream<_CharT, _Traits>
{
......@@ -218,40 +305,104 @@ namespace std
typedef basic_istream<char_type, traits_type> __istream_type;
private:
/**
* @if maint
* @doctodo
* @endif
*/
__stringbuf_type _M_stringbuf;
public:
// Constructors:
/**
* @brief Default constructor starts with an empty string buffer.
* @param mode Whether the buffer can read, or write, or both.
*
* @c ios_base::in is automatically included in @a mode.
*
* Initializes @c sb using @c mode|in, and passes @c &sb to the base
* class initializer. Does not allocate any buffer.
*
* @if maint
* That's a lie. We initialize the base class with NULL, because the
* string class does its own memory management.
* @endif
*/
explicit
basic_istringstream(ios_base::openmode __mode = ios_base::in)
: __istream_type(NULL), _M_stringbuf(__mode | ios_base::in)
{ this->init(&_M_stringbuf); }
/**
* @brief Starts with an existing string buffer.
* @param str A string to copy as a starting buffer.
* @param mode Whether the buffer can read, or write, or both.
*
* @c ios_base::in is automatically included in @a mode.
*
* Initializes @c sb using @a str and @c mode|in, and passes @c &sb
* to the base class initializer.
*
* @if maint
* That's a lie. We initialize the base class with NULL, because the
* string class does its own memory management.
* @endif
*/
explicit
basic_istringstream(const __string_type& __str,
ios_base::openmode __mode = ios_base::in)
: __istream_type(NULL), _M_stringbuf(__str, __mode | ios_base::in)
{ this->init(&_M_stringbuf); }
/**
* @brief The destructor does nothing.
*
* The buffer is deallocated by the stringbuf object, not the
* formatting stream.
*/
~basic_istringstream()
{ }
// Members:
/**
* @brief Accessing the underlying buffer.
* @return The current basic_stringbuf buffer.
*
* This hides both signatures of std::basic_ios::rdbuf().
*/
__stringbuf_type*
rdbuf() const
{ return const_cast<__stringbuf_type*>(&_M_stringbuf); }
/**
* @brief Copying out the string buffer.
* @return @c rdbuf()->str()
*/
__string_type
str() const
{ return _M_stringbuf.str(); }
/**
* @brief Setting a new buffer.
* @param s The string to use as a new sequence.
*
* Calls @c rdbuf()->str(s).
*/
void
str(const __string_type& __s)
{ _M_stringbuf.str(__s); }
};
// 27.7.3 Template class basic_ostringstream
// [27.7.3] Template class basic_ostringstream
/**
* @brief Controlling output for std::string.
*
* This class supports writing to objects of type std::basic_string,
* using the inherited functions from std::basic_ostream. To control
* the associated sequence, an instance of std::basic_stringbuf is used,
* which this page refers to as @c sb.
*/
template <typename _CharT, typename _Traits, typename _Alloc>
class basic_ostringstream : public basic_ostream<_CharT, _Traits>
{
......@@ -273,40 +424,104 @@ namespace std
typedef basic_ostream<char_type, traits_type> __ostream_type;
private:
/**
* @if maint
* @doctodo
* @endif
*/
__stringbuf_type _M_stringbuf;
public:
// Constructors/destructor:
// Constructors/destructor:
/**
* @brief Default constructor starts with an empty string buffer.
* @param mode Whether the buffer can read, or write, or both.
*
* @c ios_base::out is automatically included in @a mode.
*
* Initializes @c sb using @c mode|out, and passes @c &sb to the base
* class initializer. Does not allocate any buffer.
*
* @if maint
* That's a lie. We initialize the base class with NULL, because the
* string class does its own memory management.
* @endif
*/
explicit
basic_ostringstream(ios_base::openmode __mode = ios_base::out)
: __ostream_type(NULL), _M_stringbuf(__mode | ios_base::out)
{ this->init(&_M_stringbuf); }
/**
* @brief Starts with an existing string buffer.
* @param str A string to copy as a starting buffer.
* @param mode Whether the buffer can read, or write, or both.
*
* @c ios_base::out is automatically included in @a mode.
*
* Initializes @c sb using @a str and @c mode|out, and passes @c &sb
* to the base class initializer.
*
* @if maint
* That's a lie. We initialize the base class with NULL, because the
* string class does its own memory management.
* @endif
*/
explicit
basic_ostringstream(const __string_type& __str,
ios_base::openmode __mode = ios_base::out)
: __ostream_type(NULL), _M_stringbuf(__str, __mode | ios_base::out)
{ this->init(&_M_stringbuf); }
/**
* @brief The destructor does nothing.
*
* The buffer is deallocated by the stringbuf object, not the
* formatting stream.
*/
~basic_ostringstream()
{ }
// Members:
/**
* @brief Accessing the underlying buffer.
* @return The current basic_stringbuf buffer.
*
* This hides both signatures of std::basic_ios::rdbuf().
*/
__stringbuf_type*
rdbuf() const
{ return const_cast<__stringbuf_type*>(&_M_stringbuf); }
/**
* @brief Copying out the string buffer.
* @return @c rdbuf()->str()
*/
__string_type
str() const
{ return _M_stringbuf.str(); }
/**
* @brief Setting a new buffer.
* @param s The string to use as a new sequence.
*
* Calls @c rdbuf()->str(s).
*/
void
str(const __string_type& __s)
{ _M_stringbuf.str(__s); }
};
// 27.7.4 Template class basic_stringstream
// [27.7.4] Template class basic_stringstream
/**
* @brief Controlling input and output for std::string.
*
* This class supports reading from and writing to objects of type
* std::basic_string, using the inherited functions from
* std::basic_iostream. To control the associated sequence, an instance
* of std::basic_stringbuf is used, which this page refers to as @c sb.
*/
template <typename _CharT, typename _Traits, typename _Alloc>
class basic_stringstream : public basic_iostream<_CharT, _Traits>
{
......@@ -328,33 +543,85 @@ namespace std
typedef basic_iostream<char_type, traits_type> __iostream_type;
private:
/**
* @if maint
* @doctodo
* @endif
*/
__stringbuf_type _M_stringbuf;
public:
// Constructors/destructors
/**
* @brief Default constructor starts with an empty string buffer.
* @param mode Whether the buffer can read, or write, or both.
*
* Initializes @c sb using @c mode, and passes @c &sb to the base
* class initializer. Does not allocate any buffer.
*
* @if maint
* That's a lie. We initialize the base class with NULL, because the
* string class does its own memory management.
* @endif
*/
explicit
basic_stringstream(ios_base::openmode __m = ios_base::out | ios_base::in)
: __iostream_type(NULL), _M_stringbuf(__m)
{ this->init(&_M_stringbuf); }
/**
* @brief Starts with an existing string buffer.
* @param str A string to copy as a starting buffer.
* @param mode Whether the buffer can read, or write, or both.
*
* Initializes @c sb using @a str and @c mode, and passes @c &sb
* to the base class initializer.
*
* @if maint
* That's a lie. We initialize the base class with NULL, because the
* string class does its own memory management.
* @endif
*/
explicit
basic_stringstream(const __string_type& __str,
ios_base::openmode __m = ios_base::out | ios_base::in)
: __iostream_type(NULL), _M_stringbuf(__str, __m)
{ this->init(&_M_stringbuf); }
/**
* @brief The destructor does nothing.
*
* The buffer is deallocated by the stringbuf object, not the
* formatting stream.
*/
~basic_stringstream()
{ }
// Members:
/**
* @brief Accessing the underlying buffer.
* @return The current basic_stringbuf buffer.
*
* This hides both signatures of std::basic_ios::rdbuf().
*/
__stringbuf_type*
rdbuf() const
{ return const_cast<__stringbuf_type*>(&_M_stringbuf); }
/**
* @brief Copying out the string buffer.
* @return @c rdbuf()->str()
*/
__string_type
str() const
{ return _M_stringbuf.str(); }
/**
* @brief Setting a new buffer.
* @param s The string to use as a new sequence.
*
* Calls @c rdbuf()->str(s).
*/
void
str(const __string_type& __s)
{ _M_stringbuf.str(__s); }
......
libstdc++-v3/include/std/std_streambuf.h
......@@ -50,28 +50,104 @@
namespace std
{
/**
* @if maint
* Does stuff.
* @endif
*/
template<typename _CharT, typename _Traits>
streamsize
__copy_streambufs(basic_ios<_CharT, _Traits>& _ios,
basic_streambuf<_CharT, _Traits>* __sbin,
basic_streambuf<_CharT, _Traits>* __sbout);
// 27.5.2 Template class basic_streambuf<_CharT, _Traits>
/**
* @brief The actual work of input and output (interface).
*
* This is a base class. Derived stream buffers each control a
* pair of character sequences: one for input, and one for output.
*
* Section [27.5.1] of the standard describes the requirements and
* behavior of stream buffer classes. That section (three paragraphs)
* is reproduced here, for simplicity and accuracy.
*
* -# Stream buffers can impose various constraints on the sequences
* they control. Some constraints are:
* - The controlled input sequence can be not readable.
* - The controlled output sequence can be not writable.
* - The controlled sequences can be associated with the contents of
* other representations for character sequences, such as external
* files.
* - The controlled sequences can support operations @e directly to or
* from associated sequences.
* - The controlled sequences can impose limitations on how the
* program can read characters from a sequence, write characters to
* a sequence, put characters back into an input sequence, or alter
* the stream position.
* .
* -# Each sequence is characterized by three pointers which, if non-null,
* all point into the same @c charT array object. The array object
* represents, at any moment, a (sub)sequence of characters from the
* sequence. Operations performed on a sequence alter the values
* stored in these pointers, perform reads and writes directly to or
* from associated sequences, and alter "the stream position" and
* conversion state as needed to maintain this subsequence relationship.
* The three pointers are:
* - the <em>beginning pointer</em>, or lowest element address in the
* array (called @e xbeg here);
* - the <em>next pointer</em>, or next element address that is a
* current candidate for reading or writing (called @e xnext here);
* - the <em>end pointer</em>, or first element address beyond the
* end of the array (called @e xend here).
* .
* -# The following semantic constraints shall always apply for any set
* of three pointers for a sequence, using the pointer names given
* immediately above:
* - If @e xnext is not a null pointer, then @e xbeg and @e xend shall
* also be non-null pointers into the same @c charT array, as
* described above; otherwise, @e xbeg and @e xend shall also be null.
* - If @e xnext is not a null pointer and @e xnext < @e xend for an
* output sequence, then a <em>write position</em> is available.
* In this case, @e *xnext shall be assignable as the next element
* to write (to put, or to store a character value, into the sequence).
* - If @e xnext is not a null pointer and @e xbeg < @e xnext for an
* input sequence, then a <em>putback position</em> is available.
* In this case, @e xnext[-1] shall have a defined value and is the
* next (preceding) element to store a character that is put back
* into the input sequence.
* - If @e xnext is not a null pointer and @e xnext< @e xend for an
* input sequence, then a <em>read position</em> is available.
* In this case, @e *xnext shall have a defined value and is the
* next element to read (to get, or to obtain a character value,
* from the sequence).
*/
template<typename _CharT, typename _Traits>
class basic_streambuf
{
public:
// Types:
//@{
/**
* These are standard types. They permit a standardized way of
* referring to names of (or names dependant on) the template
* parameters, which are specific to the implementation.
*/
typedef _CharT char_type;
typedef _Traits traits_type;
typedef typename traits_type::int_type int_type;
typedef typename traits_type::pos_type pos_type;
typedef typename traits_type::off_type off_type;
// Non-standard Types:
//@}
//@{
/**
* @if maint
* These are non-standard types.
* @endif
*/
typedef ctype<char_type> __ctype_type;
typedef basic_streambuf<char_type, traits_type> __streambuf_type;
typedef typename traits_type::state_type __state_type;
//@}
friend class basic_ios<char_type, traits_type>;
friend class basic_istream<char_type, traits_type>;
......@@ -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<char_type,_Traits>*
setbuf(char_type*, streamsize)
{ return this; }
/**
* @brief Alters the stream positions.
*
* Each derived class provides its own appropriate behavior.
* @note Base class version does nothing, returns a @c pos_type
* that represents an invalid stream position.
*/
virtual pos_type
seekoff(off_type, ios_base::seekdir,
ios_base::openmode /*__mode*/ = ios_base::in | ios_base::out)
{ return pos_type(off_type(-1)); }
/**
* @brief Alters the stream positions.
*
* Each derived class provides its own appropriate behavior.
* @note Base class version does nothing, returns a @c pos_type
* that represents an invalid stream position.
*/
virtual pos_type
seekpos(pos_type,
ios_base::openmode /*__mode*/ = ios_base::in | ios_base::out)
{ return pos_type(off_type(-1)); }
/**
* @brief Synchronizes the buffer arrays with the controlled sequences.
* @return -1 on failure.
*
* Each derived class provides its own appropriate behavior,
* including the definition of "failure".
* @note Base class version does nothing, returns zero.
*/
virtual int
sync() { return 0; }
// Get area:
// [27.5.2.4.3] get area
/**
* @brief Investigating the data available.
* @return An estimate of the number of characters available in the
* input sequence, or -1.
*
* "If it returns a positive value, then successive calls to
* @c underflow() will not return @c traits::eof() until at least that
* number of characters have been supplied. If @c showmanyc()
* returns -1, then calls to @c underflow() or @c uflow() will fail."
* [27.5.2.4.3]/1
*
* @note Base class version does nothing, returns zero.
* @note The standard adds that "the intention is not only that the
* calls [to underflow or uflow] will not return @c eof() but
* that they will return "immediately".
* @note The standard adds that "the morphemes of @c showmanyc are
* "es-how-many-see", not "show-manic".
*/
virtual streamsize
showmanyc() { return 0; }
/**
* @brief Multiple character extraction.
* @param s A buffer area.
* @param n Maximum number of characters to assign.
* @return The number of characters assigned.
*
* Fills @a s[0] through @a s[n-1] with characters from the input
* sequence, as if by @c sbumpc(). Stops when either @a n characters
* have been copied, or when @c traits::eof() would be copied.
*
* It is expected that derived classes provide a more efficient
* implementation by overriding this definition.
*/
virtual streamsize
xsgetn(char_type* __s, streamsize __n);
/**
* @brief Fetches more data from the controlled sequence.
* @return The first character from the <em>pending sequence</em>.
*
* Informally, this function is called when the input buffer is
* exhausted (or does not exist, as buffering need not actually be
* done). If a buffer exists, it is "refilled". In either case, the
* next available character is returned, or @c traits::eof() to
* indicate a null pending sequence.
*
* For a formal definiton of the pending sequence, see a good text
* such as Langer & Kreft, or [27.5.2.4.3]/7-14.
*
* A functioning input streambuf can be created by overriding only
* this function (no buffer area will be used). For an example, see
* http://gcc.gnu.org/onlinedocs/libstdc++/27_io/howto.html#6
*
* @note Base class version does nothing, returns eof().
*/
virtual int_type
underflow()
{ return traits_type::eof(); }
/**
* @brief Fetches more data from the controlled sequence.
* @return The first character from the <em>pending sequence</em>.
*
* Informally, this function does the same thing as @c underflow(),
* and in fact is required to call that function. It also returns
* the new character, like @c underflow() does. However, this
* function also moves the read position forward by one.
*/
virtual int_type
uflow()
{
......@@ -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()
{
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment