%!TEX root = std.tex
\rSec0[input.output]{Input/output library}

\rSec1[input.output.general]{General}

\pnum
This Clause describes components that \Cpp programs may use to perform
input/output operations.

\pnum
The following subclauses describe
requirements for stream parameters,
and components for
forward declarations of iostreams,
predefined iostreams objects,
base iostreams classes,
stream buffering,
stream formatting and manipulators,
string streams,
and file streams,
as summarized in Table~\ref{tab:iostreams.lib.summary}.

\begin{libsumtab}{Input/output library summary}{tab:iostreams.lib.summary}
\ref{iostreams.requirements}  & Requirements     &           \\ \rowsep
\ref{iostream.forward}  & Forward declarations     & \tcode{<iosfwd>}  \\ \rowsep
\ref{iostream.objects}  & Standard iostream objects  & \tcode{<iostream>}  \\ \rowsep
\ref{iostreams.base}    & Iostreams base classes     & \tcode{<ios>}   \\ \rowsep
\ref{stream.buffers}    & Stream buffers         & \tcode{<streambuf>} \\ \rowsep
\ref{iostream.format}   & Formatting and manipulators & \tcode{<istream>} \\
                        &    & \tcode{<ostream>} \\
                        &    & \tcode{<iomanip>} \\ \rowsep
\ref{string.streams}    & String streams         & \tcode{<sstream>} \\ \rowsep
\ref{file.streams}      & File streams           & \tcode{<fstream>} \\
                        &    & \tcode{<cstdio>}  \\
                        &    & \tcode{<cinttypes>} \\
\end{libsumtab}

\pnum
Figure~\ref{fig:streampos} illustrates relationships among various types
described in this clause. A line from \textbf{A} to \textbf{B} indicates that \textbf{A}
is an alias (e.g. a typedef) for \textbf{B} or that \textbf{A} is defined in terms of
\textbf{B}.

\begin{importgraphic}
{Stream position, offset, and size types [non-normative]}
{fig:streampos}
{figstreampos.pdf}
\end{importgraphic}

\rSec1[iostreams.requirements]{Iostreams requirements}

\rSec2[iostream.limits.imbue]{Imbue limitations}

\pnum
No function described in Clause~\ref{input.output} except for
\tcode{ios_base::imbue}
and \tcode{basic_filebuf::pubimbue}
causes any instance of
\tcode{basic_ios::imbue}
or
\tcode{basic_streambuf::imbue}
to be called.
If any user function called from a function declared in Clause~\ref{input.output} or
as an overriding virtual function of any class declared in Clause~\ref{input.output}
calls
\tcode{imbue},
the behavior is undefined.

\rSec2[iostreams.limits.pos]{Positioning type limitations}

\pnum
The classes of Clause~\ref{input.output} with template arguments
\tcode{charT}
and
\tcode{traits}
behave as described if
\tcode{traits::pos_type}
and
\tcode{traits::off_type}
are
\tcode{streampos}
and
\tcode{streamoff}
respectively.
Except as noted explicitly below, their behavior when
\tcode{traits::pos_type}
and
\tcode{traits::off_type}
are other types is
\indextext{\idxcode{streambuf}!implementation-defined}%
\impldef{behavior of iostream classes when \tcode{traits::pos_type} is not \tcode{streampos} or when \tcode{traits::off_type} is not \tcode{streamoff}}.

\pnum
In the classes of Clause~\ref{input.output}, a template formal parameter with name
\tcode{charT} represents a member of the set of types containing \tcode{char}, \tcode{wchar_t},
and any other implementation-defined character types that satisfy the requirements for
a character on which any of the iostream components can be instantiated.

\rSec2[iostreams.threadsafety]{Thread safety}

\pnum
Concurrent access to a stream object (\ref{string.streams},~\ref{file.streams}), stream buffer
object~(\ref{stream.buffers}), or C Library stream~(\ref{c.files}) by multiple threads may result in
a data race~(\ref{intro.multithread}) unless otherwise specified~(\ref{iostream.objects}).
\enternote Data races result in undefined behavior~(\ref{intro.multithread}). \exitnote

\pnum
If one thread makes a library call \textit{a} that writes a value to a stream
and, as a result, another thread reads this value from the stream through a
library call \textit{b} such that this does not result in a data race, then
\textit{a}'s write synchronizes with
\textit{b}'s read.

\rSec1[iostream.forward]{Forward declarations}

\synopsis{Header \tcode{<iosfwd>} synopsis}
\indexlibrary{\idxhdr{iosfwd}}%

\indexlibrary{\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_streambuf}}%
\indexlibrary{\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_stringbuf}}%
\indexlibrary{\idxcode{basic_istringstream}}%
\indexlibrary{\idxcode{basic_ostringstream}}%
\indexlibrary{\idxcode{basic_stringstream}}%
\indexlibrary{\idxcode{basic_filebuf}}%
\indexlibrary{\idxcode{basic_ifstream}}%
\indexlibrary{\idxcode{basic_ofstream}}%
\indexlibrary{\idxcode{basic_fstream}}%
\indexlibrary{\idxcode{basic_istreambuf_iterator}}%
\indexlibrary{\idxcode{basic_ostreambuf_iterator}}%
\indexlibrary{\idxcode{ios}}%
\indexlibrary{\idxcode{streambuf}}%
\indexlibrary{\idxcode{istream}}%
\indexlibrary{\idxcode{ostream}}%
\indexlibrary{\idxcode{stringbuf}}%
\indexlibrary{\idxcode{istringstream}}%
\indexlibrary{\idxcode{ostringstream}}%
\indexlibrary{\idxcode{stringstream}}%
\indexlibrary{\idxcode{filebuf}}%
\indexlibrary{\idxcode{ifstream}}%
\indexlibrary{\idxcode{ofstream}}%
\indexlibrary{\idxcode{fstream}}%
\indexlibrary{\idxcode{wstreambuf}}%
\indexlibrary{\idxcode{wistream}}%
\indexlibrary{\idxcode{wostream}}%
\indexlibrary{\idxcode{wstringbuf}}%
\indexlibrary{\idxcode{wistringstream}}%
\indexlibrary{\idxcode{wostringstream}}%
\indexlibrary{\idxcode{wstringstream}}%
\indexlibrary{\idxcode{wfilebuf}}%
\indexlibrary{\idxcode{wifstream}}%
\indexlibrary{\idxcode{wofstream}}%
\indexlibrary{\idxcode{wfstream}}%
\begin{codeblock}
namespace std {
  template<class charT> class char_traits;
  template<> class char_traits<char>;
  template<> class char_traits<char16_t>;
  template<> class char_traits<char32_t>;
  template<> class char_traits<wchar_t>;

  template<class T> class allocator;

  template <class charT, class traits = char_traits<charT> >
    class basic_ios;
  template <class charT, class traits = char_traits<charT> >
    class basic_streambuf;
  template <class charT, class traits = char_traits<charT> >
    class basic_istream;
  template <class charT, class traits = char_traits<charT> >
    class basic_ostream;
  template <class charT, class traits = char_traits<charT> >
    class basic_iostream;

  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT> >
    class basic_stringbuf;
  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT> >
    class basic_istringstream;
  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT> >
    class basic_ostringstream;
  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT> >
    class basic_stringstream;

  template <class charT, class traits = char_traits<charT> >
    class basic_filebuf;
  template <class charT, class traits = char_traits<charT> >
    class basic_ifstream;
  template <class charT, class traits = char_traits<charT> >
    class basic_ofstream;
  template <class charT, class traits = char_traits<charT> >
    class basic_fstream;

  template <class charT, class traits = char_traits<charT> >
    class istreambuf_iterator;
  template <class charT, class traits = char_traits<charT> >
    class ostreambuf_iterator;

  typedef basic_ios<char>       ios;
  typedef basic_ios<wchar_t>    wios;

  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;

  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;

  template <class state> class fpos;
  typedef fpos<char_traits<char>::state_type>    streampos;
  typedef fpos<char_traits<wchar_t>::state_type> wstreampos;
}
\end{codeblock}

\pnum
Default template arguments are described as appearing both in
\tcode{<iosfwd>}
and in the synopsis of other headers
but it is well-formed to include both
\tcode{<iosfwd>}
and one or more of the other headers.\footnote{It is the implementation's
responsibility to implement headers so
that including
\tcode{<iosfwd>}
and other headers does not violate the rules about
multiple occurrences of default arguments.}

\pnum
\enternote
The
class template specialization
\tcode{basic_ios<charT,traits>}
serves as a virtual base class for the
class templates
\tcode{basic_istream},
\tcode{basic_ostream},
and
class templates
derived from them.
\tcode{basic_iostream}
is a class
template
derived from both
\tcode{basic_istream<charT,traits>}
and
\tcode{basic_ostream<charT,traits>}.

\pnum
The
class template specialization
\tcode{basic_streambuf<charT,traits>}
serves as a base class for class templates
\tcode{basic_stringbuf}
and
\tcode{basic_filebuf}.

\pnum
The
class template specialization
\tcode{basic_istream<charT,traits>}
serves as a base class for class templates
\tcode{basic_istringstream}
and
\tcode{basic_ifstream}.

\pnum
The
class template specialization
\tcode{basic_ostream<charT,traits>}
serves as a base class for class templates
\tcode{basic_ostringstream}
and
\tcode{basic_ofstream}.

\pnum
The
class template specialization
\tcode{basic_iostream<charT,traits>}
serves as a base class for class templates
\tcode{basic_stringstream}
and
\tcode{basic_fstream}.

\pnum
Other typedefs define instances of
class templates
specialized for
\tcode{char}
or
\tcode{wchar_t}
types.

\pnum
Specializations of the class template
\tcode{fpos}
are
used for specifying file position information.

\pnum
The types
\tcode{streampos}
and
\tcode{wstreampos}
are used for positioning streams specialized on
\tcode{char}
and
\tcode{wchar_t}
respectively.

\pnum
This synopsis suggests a circularity between
\tcode{streampos}
and
\tcode{char_traits<char>}.
An implementation can avoid this circularity by substituting equivalent
types.
One way to do this might be
\begin{codeblock}
template<class stateT> class fpos { ... };      // depends on nothing
typedef ... _STATE;             // implementation private declaration of \tcode{stateT}

typedef fpos<_STATE> streampos;

template<> struct char_traits<char> {
  typedef streampos
  pos_type;
}
\end{codeblock}
\exitnote

\rSec1[iostream.objects]{Standard iostream objects}

\rSec2[iostream.objects.overview]{Overview}

\synopsis{Header \tcode{<iostream>} synopsis}
\indexlibrary{\idxhdr{iostream}}%

\begin{codeblock}
#include <ios>
#include <streambuf>
#include <istream>
#include <ostream>

namespace std {
  extern istream cin;
  extern ostream cout;
  extern ostream cerr;
  extern ostream clog;

  extern wistream wcin;
  extern wostream wcout;
  extern wostream wcerr;
  extern wostream wclog;
}
\end{codeblock}

\pnum
The header
\tcode{<iostream>}
declares objects that associate objects with the
standard C streams provided for by the functions declared in
\tcode{<cstdio>}~(\ref{c.files}), and includes all the headers necessary to use
these objects.
\indexlibrary{\idxhdr{cstdio}}%

\pnum
The objects are constructed and the associations are established at some
time prior to or during the first time an object of class
\tcode{ios_base::Init} is constructed, and in any case before the body
of \tcode{main} begins execution.\footnote{If it is possible for them to do so, implementations are encouraged to
initialize the objects earlier than required.}
The objects are not destroyed during program execution.\footnote{Constructors and destructors for static objects can
access these objects to read input from
\tcode{stdin}
or write output to
\tcode{stdout}
or
\tcode{stderr}.
}
The results of including \tcode{<iostream>} in a translation unit shall be as if
\tcode{<iostream>} defined an instance of \tcode{ios_base::Init} with static
storage duration. Similarly, the entire program shall behave as if there were at least
one instance of \tcode{ios_base::Init} with static storage duration.

\pnum
Mixing operations on corresponding wide- and narrow-character streams
follows the same semantics as mixing such operations on
\tcode{FILE}s,
as specified in Amendment 1 of the ISO C standard.

\pnum
Concurrent access to a synchronized~(\ref{ios.members.static}) standard iostream object's formatted and unformatted input~(\ref{istream}) and output~(\ref{ostream}) functions or a standard C stream by multiple threads shall not result in a data race~(\ref{intro.multithread}). \enternote Users must still synchronize concurrent use of these objects and streams by multiple threads if they wish to avoid interleaved characters. \exitnote

\rSec2[narrow.stream.objects]{Narrow stream objects}

\indexlibrary{\idxcode{cin}}%
\begin{itemdecl}
istream cin;
\end{itemdecl}

\begin{itemdescr}
\pnum
The object
\tcode{cin}
controls input from a stream buffer
associated with the object
\tcode{stdin},
declared in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}.

\pnum
After the object
\tcode{cin}
is initialized,
\tcode{cin.tie()}
returns
\tcode{\&cout}.
Its state is otherwise the same as required for
\tcode{basic_ios<char>::init}~(\ref{basic.ios.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{cout}}%
\begin{itemdecl}
ostream cout;
\end{itemdecl}

\begin{itemdescr}
\pnum
The object
\tcode{cout}
controls output to a stream buffer
associated with the object
\tcode{stdout},
declared in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}~(\ref{c.files}).
\end{itemdescr}

\indexlibrary{\idxcode{cerr}}%
\begin{itemdecl}
ostream cerr;
\end{itemdecl}

\begin{itemdescr}
\pnum
The object
\tcode{cerr}
controls output to a stream buffer
associated with the object
\tcode{stderr},
declared in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}~(\ref{c.files}).

\pnum
After the object
\tcode{cerr}
is initialized,
\tcode{cerr.flags() \& unitbuf}
is nonzero and \tcode{cerr.tie()} returns \tcode{\&cout}.
Its state is otherwise the same as required for
\tcode{basic_ios<char>::init}~(\ref{basic.ios.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{clog}}%
\begin{itemdecl}
ostream clog;
\end{itemdecl}

\begin{itemdescr}
\pnum
The object
\tcode{clog}
controls output to a stream buffer
associated with the object
\tcode{stderr},
declared in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}~(\ref{c.files}).
\end{itemdescr}

\rSec2[wide.stream.objects]{Wide stream objects}

\indexlibrary{\idxcode{wcin}}%
\begin{itemdecl}
wistream wcin;
\end{itemdecl}

\begin{itemdescr}
\pnum
The object
\tcode{wcin}
controls input from a stream buffer
associated with the object
\tcode{stdin},
declared in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}.

\pnum
After the object
\tcode{wcin}
is initialized,
\tcode{wcin.tie()}
returns
\tcode{\&wcout}.
Its state is otherwise the same as required for
\tcode{basic_ios<wchar_t>::init}~(\ref{basic.ios.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{wcout}}%
\begin{itemdecl}
wostream wcout;
\end{itemdecl}

\begin{itemdescr}
\pnum
The object
\tcode{wcout}
controls output to a stream buffer
associated with the object
\tcode{stdout},
declared in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}~(\ref{c.files}).
\end{itemdescr}

\indexlibrary{\idxcode{wcerr}}%
\begin{itemdecl}
wostream wcerr;
\end{itemdecl}

\begin{itemdescr}
\pnum
The object
\tcode{wcerr}
controls output to a stream buffer
associated with the object
\tcode{stderr},
declared in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}~(\ref{c.files}).

\pnum
After the object
\tcode{wcerr}
is initialized,
\tcode{wcerr.flags() \& unitbuf}
is nonzero and \tcode{wcerr.tie()} returns \tcode{\&wcout}.
Its state is otherwise the same as required for
\tcode{basic_ios<wchar_t>::init}~(\ref{basic.ios.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{wclog}}%
\begin{itemdecl}
wostream wclog;
\end{itemdecl}

\begin{itemdescr}
\pnum
The object
\tcode{wclog}
controls output to a stream buffer
associated with the object
\tcode{stderr},
declared in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}~(\ref{c.files}).
\end{itemdescr}

\rSec1[iostreams.base]{Iostreams base classes}

\rSec2[iostreams.base.overview]{Overview}

\synopsis{Header \tcode{<ios>} synopsis}
\indexlibrary{\idxhdr{ios}}%

\begin{codeblock}
#include <iosfwd>

namespace std {
  typedef @\impdef@ streamoff;
  typedef @\impdef@ streamsize;
  template <class stateT> class fpos;

  class ios_base;
  template <class charT, class traits = char_traits<charT> >
    class basic_ios;

  // \ref{std.ios.manip}, manipulators:
  ios_base& boolalpha  (ios_base& str);
  ios_base& noboolalpha(ios_base& str);

  ios_base& showbase   (ios_base& str);
  ios_base& noshowbase (ios_base& str);

  ios_base& showpoint  (ios_base& str);
  ios_base& noshowpoint(ios_base& str);

  ios_base& showpos    (ios_base& str);
  ios_base& noshowpos  (ios_base& str);

  ios_base& skipws     (ios_base& str);
  ios_base& noskipws   (ios_base& str);

  ios_base& uppercase  (ios_base& str);
  ios_base& nouppercase(ios_base& str);

  ios_base& unitbuf    (ios_base& str);
  ios_base& nounitbuf  (ios_base& str);

  // \ref{adjustfield.manip} adjustfield:
  ios_base& internal   (ios_base& str);
  ios_base& left       (ios_base& str);
  ios_base& right      (ios_base& str);

  // \ref{basefield.manip} basefield:
  ios_base& dec        (ios_base& str);
  ios_base& hex        (ios_base& str);
  ios_base& oct        (ios_base& str);

  // \ref{floatfield.manip} floatfield:
  ios_base& fixed      (ios_base& str);
  ios_base& scientific (ios_base& str);
  ios_base& hexfloat   (ios_base& str);
  ios_base& defaultfloat(ios_base& str);

  // \ref{error.reporting} error reporting:
  enum class io_errc {
    stream = 1
  };

  template <> struct is_error_code_enum<io_errc> : public true_type { };
  error_code make_error_code(io_errc e) noexcept;
  error_condition make_error_condition(io_errc e) noexcept;
  const error_category& iostream_category() noexcept;
}
\end{codeblock}
\indexlibrary{\idxcode{ios}}%
\indexlibrary{\idxcode{basic_ios<char>}}%
\indexlibrary{\idxcode{wios}}%
\indexlibrary{\idxcode{basic_ios<wchar_t>}}%
\indexlibrary{\idxcode{fpos}}%

\rSec2[stream.types]{Types}

\indexlibrary{\idxcode{streamoff}}%
\begin{itemdecl}
typedef @\impdef@ streamoff;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type \tcode{streamoff} is a synonym for one of the signed basic integral types of
sufficient size to represent the maximum possible file size for the operating system.\footnote{Typically \tcode{long long}.}
\end{itemdescr}

\indexlibrary{\idxcode{streamsize}}%
\begin{itemdecl}
typedef @\impdef@ streamsize;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type
\tcode{streamsize}
is a synonym for one of the signed basic
integral types.
It is used to represent the number of characters transferred in an I/O
operation, or the size of I/O buffers.\footnote{\tcode{streamsize}
is used in most places where ISO C would use
\tcode{size_t}.
Most of the uses of
\tcode{streamsize}
could use
\tcode{size_t},
except for the
\tcode{strstreambuf}
constructors, which require negative values.
It should probably be the signed type corresponding to
\tcode{size_t}
(which is what Posix.2 calls
\tcode{ssize_t}).}
\end{itemdescr}

\rSec2[ios.base]{Class \tcode{ios_base}}
\indexlibrary{\idxcode{ios_base}}%
\begin{codeblock}
namespace std {
  class ios_base {
  public:
    class failure;

    // \ref{ios::fmtflags} \tcode{fmtflags}
    typedef @\textit{T1}@ fmtflags;
    static constexpr fmtflags boolalpha = @\unspec@;
    static constexpr fmtflags dec = @\unspec@;
    static constexpr fmtflags fixed = @\unspec@;
    static constexpr fmtflags hex = @\unspec@;
    static constexpr fmtflags internal = @\unspec@;
    static constexpr fmtflags left = @\unspec@;
    static constexpr fmtflags oct = @\unspec@;
    static constexpr fmtflags right = @\unspec@;
    static constexpr fmtflags scientific = @\unspec@;
    static constexpr fmtflags showbase = @\unspec@;
    static constexpr fmtflags showpoint = @\unspec@;
    static constexpr fmtflags showpos = @\unspec@;
    static constexpr fmtflags skipws = @\unspec@;
    static constexpr fmtflags unitbuf = @\unspec@;
    static constexpr fmtflags uppercase = @\unspec@;
    static constexpr fmtflags adjustfield = @\seebelow@;
    static constexpr fmtflags basefield = @\seebelow@;
    static constexpr fmtflags floatfield = @\seebelow@;

    // \ref{ios::iostate} \tcode{iostate}
    typedef @\textit{T2}@ iostate;
    static constexpr iostate badbit = @\unspec@;
    static constexpr iostate eofbit = @\unspec@;
    static constexpr iostate failbit = @\unspec@;
    static constexpr iostate goodbit = @\seebelow@;

    // \ref{ios::openmode} \tcode{openmode}
    typedef @\textit{T3}@ openmode;
    static constexpr openmode app = @\unspec@;
    static constexpr openmode ate = @\unspec@;
    static constexpr openmode binary = @\unspec@;
    static constexpr openmode in = @\unspec@;
    static constexpr openmode out = @\unspec@;
    static constexpr openmode trunc = @\unspec@;

    // \ref{ios::seekdir} \tcode{seekdir}
    typedef @\textit{T4}@ seekdir;
    static constexpr seekdir beg = @\unspec@;
    static constexpr seekdir cur = @\unspec@;
    static constexpr seekdir end = @\unspec@;

    class Init;

    // \ref{fmtflags.state} fmtflags state:
    fmtflags flags() const;
    fmtflags flags(fmtflags fmtfl);
    fmtflags setf(fmtflags fmtfl);
    fmtflags setf(fmtflags fmtfl, fmtflags mask);
    void unsetf(fmtflags mask);

    streamsize precision() const;
    streamsize precision(streamsize prec);
    streamsize width() const;
    streamsize width(streamsize wide);

    // \ref{ios.base.locales} locales:
    locale imbue(const locale& loc);
    locale getloc() const;

    // \ref{ios.base.storage} storage:
    static int xalloc();
    long&  iword(int index);
    void*& pword(int index);

    // destructor
    virtual ~ios_base();

    // \ref{ios.base.callback} callbacks;
    enum event { erase_event, imbue_event, copyfmt_event };
    typedef void (*event_callback)(event, ios_base&, int index);
    void register_callback(event_callback fn, int index);

    ios_base(const ios_base&) = delete;
    ios_base& operator=(const ios_base&) = delete;

    static bool sync_with_stdio(bool sync = true);

  protected:
    ios_base();

  private:
    static int index;  // \expos
    long* iarray;      // \expos
    void** parray;     // \expos
  };
}
\end{codeblock}

\pnum
\tcode{ios_base}
defines several member types:
\begin{itemize}
\item a class \tcode{failure} derived from \tcode{system_error};

\item a class \tcode{Init};

\item three bitmask types, \tcode{fmtflags}, \tcode{iostate}, and \tcode{openmode};

\item an enumerated type, \tcode{seekdir}.
\end{itemize}

\pnum
It maintains several kinds of data:
\begin{itemize}
\item
state information that reflects the integrity of the stream buffer;
\item
control information that influences how to interpret (format) input
sequences and how to generate (format) output sequences;
\item
additional information that is stored by the program for its private use.
\end{itemize}

\pnum
\enternote
For the sake of exposition, the maintained data is presented here as:
\begin{itemize}
\item
\tcode{static int index},
specifies the next available
unique index for the integer or pointer arrays maintained for the private use
of the program, initialized to an unspecified value;
\item
\tcode{long* iarray},
points to the first element of an
arbitrary-length
\tcode{long}
array maintained for the private use of the
program;
\item
\tcode{void** parray},
points to the first element of an
arbitrary-length pointer array maintained for the private use of the program.
\exitnote
\end{itemize}

\rSec3[ios.types]{Types}

\rSec4[ios::failure]{Class \tcode{ios_base::failure}}

\indexlibrary{\idxcode{ios_base::failure}}%
\begin{codeblock}
namespace std {
  class ios_base::failure : public system_error {
  public:
    explicit failure(const string& msg, const error_code& ec = io_errc::stream);
    explicit failure(const char* msg, const error_code& ec = io_errc::stream);
  };
}
\end{codeblock}

\pnum
The class
\tcode{failure}
defines the base class
for the types of all objects thrown as exceptions,
by functions in the iostreams library,
to report errors detected during stream buffer operations.

\pnum
When throwing \tcode{ios_base::failure} exceptions, implementations should provide
values of \tcode{ec} that identify the specific reason for the failure. \enternote
Errors arising from the operating system would typically be reported as
\tcode{system_category()} errors with an error value of the error number
reported by the operating system. Errors arising from within the stream library would
typically be reported as \tcode{error_code(io_errc::stream,
iostream_category())}. \exitnote

\indexlibrary{\idxcode{failure}!\idxcode{ios_base::failure}}%
\begin{itemdecl}
explicit failure(const string& msg, const error_code& ec = io_errc::stream);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{failure} by constructing the base class with \tcode{msg} and \tcode{ec}.
\end{itemdescr}

\indexlibrary{\idxcode{failure}!\idxcode{ios_base::failure}}%
\begin{itemdecl}
explicit failure(const char* msg, const error_code& ec = io_errc::stream);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{failure} by constructing the base class with \tcode{msg} and \tcode{ec}.
\end{itemdescr}

\rSec4[ios::fmtflags]{Type \tcode{ios_base::fmtflags}}

\indexlibrary{\idxcode{fmtflags}!\idxcode{ios_base}}%
\begin{itemdecl}
typedef @\textit{T1}@ fmtflags;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type
\tcode{fmtflags}
is a bitmask type~(\ref{bitmask.types}).
Setting its elements has the effects indicated in Table~\ref{tab:iostreams.fmtflags.effects}.

\begin{libefftab}{\tcode{fmtflags} effects}{tab:iostreams.fmtflags.effects}
\tcode{boolalpha} &
 insert and extract \tcode{bool} type in alphabetic format\\
\tcode{dec}     &
 converts integer input or generates integer output in decimal base\\
\tcode{fixed}   &
 generate floating-point output in fixed-point notation\\
\tcode{hex}     &
 converts integer input or generates integer output in hexadecimal base\\
\tcode{internal}  &
 adds fill characters at a designated internal point in certain generated output,
 or identical to \tcode{right} if no such point is designated\\
\tcode{left}    &
 adds fill characters on the right (final positions) of certain generated output\\
\tcode{oct}     &
 converts integer input or generates integer output in octal base\\
\tcode{right}   &
 adds fill characters on the left (initial positions) of certain generated output\\
\tcode{scientific}  &
 generates floating-point output in scientific notation\\
\tcode{showbase}  &
 generates a prefix indicating the numeric base of generated integer output\\
\tcode{showpoint} &
 generates a decimal-point character unconditionally in generated floating-point output\\
\tcode{showpos}   &
 generates a \tcode{+} sign in non-negative generated numeric output\\
\tcode{skipws}    &
 skips leading whitespace before certain input operations\\
\tcode{unitbuf}   &
 flushes output after each output operation\\
\tcode{uppercase} &
 replaces certain lowercase letters with their uppercase equivalents in generated output\\
\end{libefftab}

\pnum
Type
\tcode{fmtflags}
also defines the constants indicated in Table~\ref{tab:iostreams.fmtflags.constants}.

\begin{floattable}{\tcode{fmtflags} constants}{tab:iostreams.fmtflags.constants}
{ll}
\topline
\lhdr{Constant}   & \rhdr{Allowable values}       \\ \capsep
\tcode{adjustfield} & \tcode{left | right | internal}   \\
\tcode{basefield} & \tcode{dec | oct | hex}       \\
\tcode{floatfield}  & \tcode{scientific | fixed}      \\
\end{floattable}
\end{itemdescr}

\rSec4[ios::iostate]{Type \tcode{ios_base::iostate}}

\indexlibrary{\idxcode{iostate}!\idxcode{ios_base}}%
\indexlibrary{\idxcode{ios_base}!\idxcode{iostate}}%
\begin{itemdecl}
typedef @\textit{T2}@ iostate;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type
\tcode{iostate}
is a bitmask type~(\ref{bitmask.types})
that contains the elements indicated in Table~\ref{tab:iostreams.iostate.effects}.

\begin{libefftab}{\tcode{iostate} effects}{tab:iostreams.iostate.effects}
\tcode{badbit}    &
 indicates a loss of integrity in an input or output sequence
 (such as an irrecoverable read error from a file); \\
\tcode{eofbit}    &
 indicates that an input operation reached the end of an input sequence;  \\
\tcode{failbit}   &
 indicates that an input operation failed to read the expected characters,
 or that an output operation failed to generate the desired characters. \\
\end{libefftab}

\pnum
Type
\tcode{iostate}
also defines the constant:
\begin{itemize}
\item
\tcode{goodbit},
the value zero.
\end{itemize}
\end{itemdescr}

\rSec4[ios::openmode]{Type \tcode{ios_base::openmode}}

\indexlibrary{\idxcode{openmode}!\idxcode{ios_base}}%
\begin{itemdecl}
typedef @\textit{T3}@ openmode;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type
\tcode{openmode}
is a bitmask type~(\ref{bitmask.types}).
It contains the elements indicated in Table~\ref{tab:iostreams.openmode.effects}.

\begin{libefftab}{\tcode{openmode} effects}{tab:iostreams.openmode.effects}
\tcode{app}     &
 seek to end before each write  \\
\tcode{ate}     &
 open and seek to end immediately after opening \\
\tcode{binary}    &
 perform input and output in binary mode (as opposed to text mode)  \\
\tcode{in}      &
 open for input \\
\tcode{out}     &
 open for output  \\
\tcode{trunc}   &
 truncate an existing stream when opening \\
\end{libefftab}
\end{itemdescr}

\rSec4[ios::seekdir]{Type \tcode{ios_base::seekdir}}

\indexlibrary{\idxcode{seekdir}!\idxcode{ios_base}}%
\begin{itemdecl}
typedef @\textit{T4}@ seekdir;
\end{itemdecl}

\begin{itemdescr}
\pnum
The type
\tcode{seekdir}
is an enumerated type~(\ref{enumerated.types})
that contains the elements indicated in Table~\ref{tab:iostreams.seekdir.effects}.

\begin{libefftabmean}{\tcode{seekdir} effects}{tab:iostreams.seekdir.effects}
\tcode{beg}     &
 request a seek (for subsequent input or output) relative to the beginning of the stream  \\
\tcode{cur}     &
 request a seek relative to the current position within the sequence  \\
\tcode{end}     &
 request a seek relative to the current end of the sequence \\
\end{libefftabmean}
\end{itemdescr}

\rSec4[ios::Init]{Class \tcode{ios_base::Init}}

\indexlibrary{\idxcode{ios_base::Init}}%
\begin{codeblock}
namespace std {
  class ios_base::Init {
  public:
    Init();
   ~Init();
  private:
    static int init_cnt; // \expos
  };
}
\end{codeblock}

\pnum
The class
\tcode{Init}
describes an object whose construction
ensures the construction of the eight objects declared in
\tcode{<io\-stream>}~(\ref{iostream.objects}) that associate file
stream buffers with the standard C streams
provided for by the functions declared in
\tcode{<cstdio>}~(\ref{c.files}).

\pnum
For the sake of exposition, the maintained data is presented here as:
\begin{itemize}
\item
\tcode{static int init_cnt},
counts the number of
constructor and destructor calls for class
\tcode{Init},
initialized to zero.
\end{itemize}

\indexlibrary{\idxcode{Init}!\idxcode{ios_base::Init}}%
\begin{itemdecl}
Init();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{Init}.
Constructs and initializes the objects \tcode{cin}, \tcode{cout}, \tcode{cerr},
\tcode{clog}, \tcode{wcin}, \tcode{wcout}, \tcode{wcerr}, and \tcode{wclog} if
they have not already been constructed and initialized.
\end{itemdescr}

\indexlibrary{\idxcode{ios_base::Init}!destructor}%
\begin{itemdecl}
~Init();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys an object of class
\tcode{Init}.
If there are no other instances of the class still in existence,
calls
\indexlibrary{\idxcode{flush}}%
\tcode{cout.flush()},
\tcode{cerr.flush()},
\tcode{clog.flush()},
\tcode{wcout.flush()},
\tcode{wcerr.flush()},
\tcode{wclog.flush()}.
\end{itemdescr}

\rSec3[fmtflags.state]{\tcode{ios_base} state functions}

\indexlibrary{\idxcode{flags}!\idxcode{ios_base}}%
\begin{itemdecl}
fmtflags flags() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The format control information for both input and output.
\end{itemdescr}

\indexlibrary{\idxcode{fmtflags}!\idxcode{ios_base}}%
\indexlibrary{\idxcode{ios_base}!\idxcode{fmtflags}}%
\begin{itemdecl}
fmtflags flags(fmtflags fmtfl);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postcondition
\tcode{fmtfl == flags()}.

\pnum
\returns
The previous value of
\tcode{flags()}.
\end{itemdescr}

\indexlibrary{\idxcode{setf}!\idxcode{ios_base}}%
\begin{itemdecl}
fmtflags setf(fmtflags fmtfl);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Sets \tcode{fmtfl} in
\tcode{flags()}.

\pnum
\returns
The previous value of
\tcode{flags()}.
\end{itemdescr}

\indexlibrary{\idxcode{setf}!\idxcode{ios_base}}%
\indexlibrary{\idxcode{ios_base}!\idxcode{setf}}%
\begin{itemdecl}
fmtflags setf(fmtflags fmtfl, fmtflags mask);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Clears \tcode{mask} in
\tcode{flags()},
sets
\tcode{fmtfl \& mask}
in
\tcode{flags()}.

\pnum
\returns
The previous value of
\tcode{flags()}.
\end{itemdescr}

\indexlibrary{\idxcode{unsetf}!\idxcode{ios_base}}%
\begin{itemdecl}
void unsetf(fmtflags mask);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Clears \tcode{mask} in
\tcode{flags()}.
\end{itemdescr}

\indexlibrary{\idxcode{precision}!\idxcode{ios_base}}%
\begin{itemdecl}
streamsize precision() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The precision
to generate on certain output conversions.
\end{itemdescr}

\indexlibrary{\idxcode{precision}!\idxcode{ios_base}}%
\indexlibrary{\idxcode{ios_base}!\idxcode{precision}}%
\begin{itemdecl}
streamsize precision(streamsize prec);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postcondition
\tcode{prec == precision()}.

\pnum
\returns
The previous value of
\tcode{precision()}.
\end{itemdescr}

\indexlibrary{\idxcode{width}!\idxcode{ios_base}}%
\begin{itemdecl}
streamsize width() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The minimum field width (number of characters) to generate on certain output
conversions.
\end{itemdescr}

\indexlibrary{\idxcode{streamsize}!\idxcode{ios_base}}%
\indexlibrary{\idxcode{ios_base}!\idxcode{streamsize}}%
\begin{itemdecl}
streamsize width(streamsize wide);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postcondition
\tcode{wide == width()}.

\pnum
\returns
The previous value of
\tcode{width()}.
\end{itemdescr}

\rSec3[ios.base.locales]{\tcode{ios_base} functions}

\indexlibrary{\idxcode{imbue}!\idxcode{ios_base}}%
\begin{itemdecl}
locale imbue(const locale& loc);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls each registered callback pair
\tcode{(fn,index)}~(\ref{ios.base.callback})
as
\tcode{(*fn)(imbue_event,*this,index)}
at such a time that a call to
\tcode{ios_base::getloc()}
from within
\tcode{fn}
returns the new locale value
\tcode{loc}.

\pnum
\returns
The previous value of
\tcode{getloc()}.

\pnum
\postcondition
\tcode{loc == getloc()}.
\end{itemdescr}

\indexlibrary{\idxcode{getloc}!\idxcode{ios_base}}%
\begin{itemdecl}
locale getloc() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If no locale has been imbued, a copy of the global \Cpp locale,
\tcode{locale()},
in effect at the time of construction.
Otherwise, returns the imbued locale, to be used to
perform locale-dependent input and output operations.
\end{itemdescr}

\rSec3[ios.members.static]{\tcode{ios_base} static members}

\indexlibrary{\idxcode{sync_with_stdio}!\idxcode{ios_base}}%
\begin{itemdecl}
bool sync_with_stdio(bool sync = true);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true}
if the previous state of the standard iostream objects~(\ref{iostream.objects})
was synchronized and otherwise returns
\tcode{false}.
The first time it is called,
the function returns
\tcode{true}.

\pnum
\effects
If any input or output operation has occurred using the standard streams prior to the
call, the effect is
\indextext{implementation-defined}%
\impldef{effect of calling \tcode{ios_base::sync_with_stdio} after
any input or output operation on standard streams}.
Otherwise, called with a false argument, it allows the standard streams to
operate independently of the standard C streams.

\pnum
When a standard iostream object \tcode{str} is
\textit{synchronized}
with a standard stdio stream \tcode{f}, the effect of inserting a character \tcode{c} by
\begin{codeblock}
fputc(f, c);
\end{codeblock}
is the same as the effect of
\begin{codeblock}
str.rdbuf()->sputc(c);
\end{codeblock}
for any sequences of characters; the effect of extracting a character \tcode{c} by
\begin{codeblock}
c = fgetc(f);
\end{codeblock}
is the same as the effect of
\begin{codeblock}
c = str.rdbuf()->sbumpc();
\end{codeblock}
for any sequences of characters; and the effect of pushing back a character \tcode{c} by
\begin{codeblock}
ungetc(c, f);
\end{codeblock}
is the same as the effect of
\begin{codeblock}
str.rdbuf()->sputbackc(c);
\end{codeblock}
for any sequence of characters.\footnote{This implies that operations on a standard iostream object can be mixed arbitrarily
with operations on the corresponding stdio stream. In practical terms, synchronization
usually means that a standard iostream object and a standard stdio object share a
buffer.
}
\end{itemdescr}

\rSec3[ios.base.storage]{\tcode{ios_base} storage functions}

\indexlibrary{\idxcode{xalloc}!\idxcode{ios_base}}%
\begin{itemdecl}
static int xalloc();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{index}
\tcode{++}.

\pnum
\remarks
Concurrent access to this function by multiple threads shall not result in a data
race~(\ref{intro.multithread}).
\end{itemdescr}

\indexlibrary{\idxcode{iword}!\idxcode{ios_base}}%
\begin{itemdecl}
long& iword(int idx);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{iarray} is a null pointer, allocates an array of
\tcode{long}
of unspecified size and stores a pointer to its first element in
\tcode{iarray}.
The function then extends the array pointed at by
\tcode{iarray} as necessary to include the element
\tcode{iarray[idx]}.
Each newly allocated element of the array is initialized to zero.
The reference returned is invalid after any other operations on the
object.\footnote{An implementation is free to implement both the integer
array pointed at by \tcode{iarray} and the pointer array pointed at by
\tcode{parray} as sparse data structures, possibly with a one-element
cache for each.}
However, the value of the storage referred to is retained, so
that until the next call to
\tcode{copyfmt},
calling
\tcode{iword}
with the same index yields another reference to the same value.
If the function fails\footnote{for example, because it cannot allocate space.}
and
\tcode{*this}
is a base subobject of a
\tcode{basic_ios<>}
object or subobject, the effect is equivalent to calling
\tcode{basic_ios<>::setstate(badbit)}
on the derived object (which may throw
\tcode{failure}).

\pnum
\returns
On success
\tcode{iarray[idx]}.
On failure, a valid
\tcode{long\&}
initialized to 0.
\end{itemdescr}

\indexlibrary{\idxcode{pword}!\idxcode{ios_base}}%
\begin{itemdecl}
void*& pword(int idx);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If \tcode{parray} is a null pointer, allocates an array of
pointers to \tcode{void} of unspecified size and stores a pointer to
its
first element in \tcode{parray}.
The function then extends the array
pointed at by \tcode{parray} as necessary to include the element
\tcode{parray[idx]}.
Each newly allocated element of the array is initialized to a null
pointer.
The reference returned is invalid after any other operations on the
object.
However, the value of the storage referred to is retained, so
that until the next call to
\tcode{copyfmt},
calling
\tcode{pword}
with the same index yields another reference to the same value.
If the function fails\footnote{for example, because it cannot allocate space.}
and
\tcode{*this}
is a base subobject of a
\tcode{basic_ios<>}
object or subobject, the effect is equivalent to calling
\tcode{basic_ios<>::setstate(badbit)}
on the derived object (which may throw
\tcode{failure}).

\pnum
\returns
On success
\tcode{parray[idx]}.
On failure a valid
\tcode{void*\&}
initialized to 0.

\pnum
\notes
After a subsequent call to
\tcode{pword(int)}
for the same object, the earlier return value may no longer be valid.
\end{itemdescr}

\rSec3[ios.base.callback]{\tcode{ios_base} callbacks}

\indexlibrary{\idxcode{register_callback}!\idxcode{ios_base}}%
\begin{itemdecl}
void register_callback(event_callback fn, int index);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Registers the pair
\tcode{(fn,index)}
such that during calls to
\tcode{imbue()}~(\ref{ios.base.locales}),
\tcode{copyfmt()},
or
\tcode{\~{}ios_base()}~(\ref{ios.base.cons}),
the function
\tcode{fn}
is called with argument
\tcode{index}.
Functions registered are called when an event occurs, in opposite order of
registration.
Functions registered while a callback function is active are not called until the next event.

\pnum
\requires
The function
\tcode{fn}
shall not throw exceptions.

\notes
Identical pairs are not merged.
A function registered twice will be called twice.
\end{itemdescr}

\rSec3[ios.base.cons]{\tcode{ios_base} constructors/destructor}

\indexlibrary{\idxcode{ios_base}!\idxcode{ios_base}}%
\begin{itemdecl}
ios_base();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Each
\tcode{ios_base}
member has an indeterminate value after construction.
The object's members shall be initialized by calling
\tcode{basic_ios::init}
before the object's first use or before it is destroyed, whichever comes first; otherwise
the behavior is undefined.
\end{itemdescr}

\indexlibrary{\idxcode{ios_base}!destructor}%
\begin{itemdecl}
~ios_base()
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys an object of class
\tcode{ios_base}.
Calls each registered callback pair
\tcode{(fn, index)}~(\ref{ios.base.callback}) as
\tcode{(*fn)(\brk{}erase_event, *this, index)}
at such time that any
\tcode{ios_base}
member function called from within
\tcode{fn}
has well defined results.
\end{itemdescr}

\rSec2[fpos]{Class template \tcode{fpos}}

\indexlibrary{\idxcode{fpos}}%
\begin{codeblock}
namespace std {
  template <class stateT> class fpos {
  public:
    // \ref{fpos.members} Members
    stateT state() const;
    void state(stateT);
  private;
    stateT st; // \expos
  };
}
\end{codeblock}

\rSec3[fpos.members]{\tcode{fpos} members}

\indexlibrary{\idxcode{state}!\idxcode{fpos}}%
\begin{itemdecl}
void state(stateT s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Assign \tcode{s} to \tcode{st}.
\end{itemdescr}

\indexlibrary{\idxcode{state}!\idxcode{fpos}}%
\indexlibrary{\idxcode{fpos}!\idxcode{state}}%
\begin{itemdecl}
stateT state() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
Current value of \tcode{st}.
\end{itemdescr}

\rSec3[fpos.operations]{\tcode{fpos} requirements}

\pnum
\indexlibrary{\idxcode{fpos}}%
\indexlibrary{\idxcode{streamoff}}%
Operations specified in Table~\ref{tab:iostreams.position.requirements} are permitted.
In that table,
\begin{itemize}
\item \tcode{P} refers to an instance of \tcode{fpos},
\item \tcode{p} and \tcode{q} refer to values of type \tcode{P},
\item \tcode{O} refers to type \tcode{streamoff},
\item \tcode{o} refers to a value of type \tcode{streamoff},
\item \tcode{sz} refers to a value of type \tcode{streamsize} and
\item \tcode{i} refers to a value of type \tcode{int}.
\end{itemize}

\begin{libreqtab4c}
{Position type requirements}
{tab:iostreams.position.requirements}
\\ \topline
\lhdr{Expression}   & \chdr{Return type}  & \chdr{Operational}  & \rhdr{Assertion/note}   \\
            &           & \chdr{semantics}  & \rhdr{pre-/post-condition} \\ \capsep
\endfirsthead
\continuedcaption\\
\hline
\lhdr{Expression}   & \chdr{Return type}  & \chdr{Operational}  & \rhdr{Assertion/note}   \\
            &           & \chdr{semantics}  & \rhdr{pre-/post-condition} \\ \capsep
\endhead
\tcode{P(i)}      &
            &
            &
 \tcode{p == P(i)}\br
 note: a destructor is assumed. \\ \rowsep
\tcode{P p(i);}\br
\tcode{P p = i;}    &
            &
            &
 post: \tcode{p == P(i)}. \\ \rowsep
\tcode{P(o)}      &
 \tcode{fpos}     &
 converts from \tcode{offset} & \\ \rowsep
\tcode{O(p)}      &
 streamoff      &
 converts to \tcode{offset} &
 \tcode{P(O(p)) == p} \\ \rowsep
\tcode{p == q}      &
 convertible to \tcode{bool}  &
            &
 \tcode{==} is an equivalence relation  \\ \rowsep
\tcode{p != q}      &
 convertible to \tcode{bool}  &
 \tcode{!(p == q)}    & \\ \rowsep
\tcode{q = p + o}\br
\tcode{p += o}      &
 \tcode{fpos}     &
 \tcode{+} offset   &
 \tcode{q - o == p}   \\ \rowsep
\tcode{q = p - o}\br
\tcode{p -= o}      &
 \tcode{fpos}     &
 \tcode{-} offset   &
 \tcode{q + o == p}   \\ \rowsep
\tcode{o = p - q}   &
 streamoff      &
 distance       &
 \tcode{q + o == p}   \\ \rowsep
\tcode{streamsize(o)}\br
\tcode{O(sz)}     &
 \tcode{streamsize}\br
 streamoff      &
 converts\br
 converts       &
 \tcode{streamsize(O(sz)) == sz}\br
 \tcode{streamsize(O(sz)) == sz}  \\
\end{libreqtab4c}

\pnum
\enternote
Every implementation is required to supply overloaded operators on
\tcode{fpos}
objects to satisfy the requirements of~\ref{fpos.operations}.
It is unspecified whether these operators are members of
\tcode{fpos},
global operators,
or provided in some other way.
\exitnote

\pnum
Stream operations that return a value of type
\tcode{traits::pos_type}
return
\tcode{P(O(-1))}
as an invalid value to signal an error.
If this value is used as an argument to any
\tcode{istream},
\tcode{ostream},
or
\tcode{streambuf} member
that accepts a value of type
\tcode{traits::pos_type}
then the behavior of that function is undefined.
\indextext{undefined}%

\rSec2[ios]{Class template \tcode{basic_ios}}

\rSec3[ios.overview]{Overview}

\indexlibrary{\idxcode{basic_ios}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
  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;

    explicit operator bool() const;
    bool operator!() const;
    iostate rdstate() const;
    void clear(iostate state = goodbit);
    void setstate(iostate state);
    bool good() const;
    bool eof()  const;
    bool fail() const;
    bool bad()  const;

    iostate exceptions() const;
    void exceptions(iostate except);

    // \ref{basic.ios.cons} Constructor/destructor:
    explicit basic_ios(basic_streambuf<charT,traits>* sb);
    virtual ~basic_ios();

    // \ref{basic.ios.members} Members:
    basic_ostream<charT,traits>* tie() const;
    basic_ostream<charT,traits>* tie(basic_ostream<charT,traits>* tiestr);

    basic_streambuf<charT,traits>* rdbuf() const;
    basic_streambuf<charT,traits>* rdbuf(basic_streambuf<charT,traits>* sb);

    basic_ios& copyfmt(const basic_ios& rhs);

    char_type fill() const;
    char_type fill(char_type ch);

    locale imbue(const locale& loc);

    char     narrow(char_type c, char dfault) const;
    char_type widen(char c) const;

    basic_ios(const basic_ios& ) = delete;
    basic_ios& operator=(const basic_ios&) = delete;

  protected:
    basic_ios();
    void init(basic_streambuf<charT,traits>* sb);
    void move(basic_ios& rhs);
    void move(basic_ios&& rhs);
    void swap(basic_ios& rhs) noexcept;
    void set_rdbuf(basic_streambuf<charT, traits>* sb);

  };
}
\end{codeblock}

\rSec3[basic.ios.cons]{\tcode{basic_ios} constructors}

\indexlibrary{\idxcode{basic_ios}!\idxcode{basic_ios}}%
\begin{itemdecl}
explicit basic_ios(basic_streambuf<charT,traits>* sb);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ios},
assigning initial values to its member objects by calling
\tcode{init(sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_ios}!constructor}%
\begin{itemdecl}
basic_ios();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ios}~(\ref{ios.base.cons})
leaving its member objects uninitialized. The object
shall be initialized by calling
\tcode{basic_ios::init}
before its first use or before it is destroyed, whichever comes first; otherwise the
behavior is undefined.
\end{itemdescr}

\indexlibrary{\idxcode{basic_ios}!destructor}%
\begin{itemdecl}
~basic_ios();
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
The destructor does not destroy
\tcode{rdbuf()}.
\end{itemdescr}

\indexlibrary{\idxcode{init}!\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_ios}!\idxcode{init}}%
\begin{itemdecl}
void init(basic_streambuf<charT,traits>* sb);
\end{itemdecl}

\begin{itemdescr}
\postconditions
The postconditions of this function are indicated in Table~\ref{tab:iostreams.basicios.init.effects}.

\begin{libefftabvalue}{\tcode{basic_ios::init()} effects}{tab:iostreams.basicios.init.effects}
\tcode{rdbuf()}   &
 \tcode{sb}     \\
\tcode{tie()}   &
 \tcode{0}      \\
\tcode{rdstate()} &
 \tcode{goodbit} if \tcode{sb} is not a null pointer, otherwise \tcode{badbit}. \\
\tcode{exceptions()}  &
 \tcode{goodbit}  \\
\tcode{flags()}   &
 \tcode{skipws | dec} \\
\tcode{width()}   &
 \tcode{0}      \\
\tcode{precision()} &
 \tcode{6}      \\
\tcode{fill()}    &
 \tcode{widen(' ');}  \\
\tcode{getloc()}  &
 a copy of the value returned by \tcode{locale()} \\
\tcode{\textit{iarray}} &
 a null pointer   \\
\tcode{\textit{parray}} &
 a null pointer   \\
\end{libefftabvalue}
\end{itemdescr}

\rSec3[basic.ios.members]{Member functions}

\indexlibrary{\idxcode{tie}!\idxcode{basic_ios}}%
\begin{itemdecl}
basic_ostream<charT,traits>* tie() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An output sequence that is
\textit{tied}
to (synchronized with) the sequence controlled by the stream buffer.
\end{itemdescr}

\indexlibrary{\idxcode{tie}!\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_ios}!\idxcode{tie}}%
\begin{itemdecl}
basic_ostream<charT,traits>* tie(basic_ostream<charT,traits>* tiestr);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
If \tcode{tiestr} is not null, \tcode{tiestr} must not be reachable by
traversing the linked list of tied stream objects starting from
\tcode{tiestr->tie()}.

\pnum
\postcondition
\tcode{tiestr == tie()}.

\pnum
\returns
The previous value of
\tcode{tie()}.
\end{itemdescr}

\indexlibrary{\idxcode{rdbuf}!\idxcode{basic_ios}}%
\begin{itemdecl}
basic_streambuf<charT,traits>* rdbuf() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A pointer to the
\tcode{streambuf}
associated with the stream.
\end{itemdescr}

\indexlibrary{\idxcode{rdbuf}!\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_ios}!\idxcode{rdbuf}}%
\begin{itemdecl}
basic_streambuf<charT,traits>* rdbuf(basic_streambuf<charT,traits>* sb);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postcondition
\tcode{sb == rdbuf()}.

\pnum
\effects
Calls
\tcode{clear()}.

\pnum
\returns
The previous value of
\tcode{rdbuf()}.
\end{itemdescr}

\indexlibrary{\idxcode{imbue}!\idxcode{basic_ios}}%
\begin{itemdecl}
locale imbue(const locale& loc);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{ios_base::imbue(loc)}~(\ref{ios.base.locales})
and
if
\tcode{rdbuf()!=0}
then
\tcode{rdbuf()->pubimbue(loc)} (\ref{streambuf.locales}).

\pnum
\returns
The prior value of
\tcode{ios_base::imbue()}.
\end{itemdescr}

\indexlibrary{\idxcode{narrow}!\idxcode{basic_ios}}%
\begin{itemdecl}
char narrow(char_type c, char dfault) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{use_facet< ctype<char_type> >(getloc()).narrow(c,dfault)}
\end{itemdescr}

\indexlibrary{\idxcode{widen}!\idxcode{basic_ios}}%
\begin{itemdecl}
char_type widen(char c) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{use_facet< ctype<char_type> >(getloc()).widen(c)}
\end{itemdescr}

\indexlibrary{\idxcode{fill}!\idxcode{basic_ios}}%
\begin{itemdecl}
char_type fill() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The character used to pad (fill) an output conversion to the specified
field width.
\end{itemdescr}

\indexlibrary{\idxcode{fill}!\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_ios}!\idxcode{fill}}%
\begin{itemdecl}
char_type fill(char_type fillch);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postcondition
\tcode{traits::eq(fillch, fill())}

\pnum
\returns
The previous value of
\tcode{fill()}.
\end{itemdescr}

\indexlibrary{\idxcode{copyfmt}!\idxcode{basic_ios}}%
\begin{itemdecl}
basic_ios& copyfmt(const basic_ios& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If
\tcode{(this == \&rhs)}
does nothing.
Otherwise assigns to the member objects of
\tcode{*this}
the corresponding member objects of \tcode{rhs} as follows:

\begin{enumerate}
\item calls each registered callback pair \tcode{(fn, index)} as
\tcode{(*fn)(erase_event, *this, index)};

\item assigns to the member objects of \tcode{*this} the corresponding member objects of
\tcode{rhs}, except that

\begin{itemize}
\item \tcode{rdstate()}, \tcode{rdbuf()}, and \tcode{exceptions()} are left unchanged;

\item the contents of arrays pointed at by \tcode{pword} and \tcode{iword} are copied,
not the pointers themselves;\footnote{ This suggests an infinite amount of copying, but the implementation can keep
track of the maximum element of the arrays that is non-zero.}
and

\item if any newly stored pointer values in \tcode{*this} point at objects stored outside
the object \tcode{rhs} and those objects are destroyed when \tcode{rhs} is destroyed, the
newly stored pointer values are altered to point at newly constructed copies of the
objects;
\end{itemize}

\item calls each callback pair that was copied from \tcode{rhs} as
\tcode{(*fn)(copyfmt_event, *this, index)};

\item calls \tcode{exceptions(rhs.except())}.

\end{enumerate}

\pnum
\realnote The second pass through the callback pairs permits a copied \tcode{pword}
value to be zeroed, or to have its referent deep copied or reference counted, or to have
other special action taken.

\pnum
\postconditions
The postconditions of this function are indicated in Table~\ref{tab:iostreams.copyfmt.effects}.


\begin{LibEffTab}{\tcode{basic_ios::copyfmt()} effects}
{tab:iostreams.copyfmt.effects}{Value}{1.2in}
\tcode{rdbuf()}             &
  \textit{unchanged}        \\
\tcode{tie()}               &
  \tcode{rhs.tie()}         \\
\tcode{rdstate()}           &
  \textit{unchanged}        \\
\tcode{exceptions()}        &
  \tcode{rhs.exceptions()}  \\
\tcode{flags()}             &
  \tcode{rhs.flags()}       \\
\tcode{width()}             &
  \tcode{rhs.width()}       \\
\tcode{precision()}         &
  \tcode{rhs.precision()}   \\
\tcode{fill()}              &
  \tcode{rhs.fill()}        \\
\tcode{getloc()}            &
  \tcode{rhs.getloc()}      \\
\end{LibEffTab}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{move}!\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_ios}!\idxcode{move}}%
\begin{itemdecl}
void move(basic_ios& rhs);
void move(basic_ios&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postconditions \tcode{*this} shall have the state that
\tcode{rhs} had before the function call, except that
\tcode{rdbuf()} shall return 0. \tcode{rhs} shall be in a valid but
unspecified state, except that \tcode{rhs.rdbuf()} shall return the
same value as it returned before the function call, and
\tcode{rhs.tie()} shall return 0.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_ios}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_ios& rhs) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects The states of \tcode{*this} and \tcode{rhs}
shall be exchanged, except that \tcode{rdbuf()} shall return the same
value as it returned before the function call, and \tcode{rhs.rdbuf()}
shall return the same value as it returned before the function call.
\end{itemdescr}

\indexlibrary{\idxcode{set_rdbuf}!\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_ios}!\idxcode{set_rdbuf}}%
\begin{itemdecl}
void set_rdbuf(basic_streambuf<charT, traits>* sb);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{sb != nullptr}.

\pnum
\effects Associates the \tcode{basic_streambuf} object
pointed to by \tcode{sb} with this stream without calling
\tcode{clear()}.

\pnum
\postconditions \tcode{rdbuf() == sb}.

\pnum
\throws Nothing.
\end{itemdescr}

\rSec3[iostate.flags]{\tcode{basic_ios} flags functions}

\indexlibrary{\idxcode{operator bool}!\idxcode{basic_ios}}%
\begin{itemdecl}
explicit operator bool() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{!fail()}.
\end{itemdescr}

\indexlibrary{\idxcode{operator"!}!\idxcode{basic_ios}}%
\begin{itemdecl}
bool operator!() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{fail()}.
\end{itemdescr}

\indexlibrary{\idxcode{rdstate}!\idxcode{basic_ios}}%
\begin{itemdecl}
iostate rdstate() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The error state of the stream buffer.
\end{itemdescr}

\indexlibrary{\idxcode{clear}!\idxcode{basic_ios}}%
\begin{itemdecl}
void clear(iostate state = goodbit);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postcondition
If
\tcode{rdbuf()!=0}
then
\tcode{state == rdstate()};
otherwise
\tcode{rdstate()==(state | ios_base\colcol{}badbit)}.

\pnum
\effects
If \tcode{((state | (rdbuf() ? goodbit : badbit)) \& exceptions()) == 0},
returns.
Otherwise, the function throws an object \tcode{fail} of class
\tcode{basic_ios::failure}~(\ref{ios::failure}),
constructed with
\indextext{\idxcode{basic_ios::failure}~argument!implementation-defined}
\impldef{argument values to construct \tcode{basic_ios::failure}}
argument values.%
\end{itemdescr}

\indexlibrary{\idxcode{setstate}!\idxcode{basic_ios}}%
\begin{itemdecl}
void setstate(iostate state);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{clear(rdstate() | state)}
(which may throw
\tcode{basic_ios::failure}~(\ref{ios::failure})).
\end{itemdescr}

\indexlibrary{\idxcode{good}!\idxcode{basic_ios}}%
\begin{itemdecl}
bool good() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rdstate() == 0}
\end{itemdescr}

\indexlibrary{\idxcode{eof}!\idxcode{basic_ios}}%
\begin{itemdecl}
bool eof() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true}
if
\tcode{eofbit}
is set in
\tcode{rdstate()}.
\end{itemdescr}

\indexlibrary{\idxcode{fail}!\idxcode{basic_ios}}%
\begin{itemdecl}
bool fail() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true}
if
\tcode{failbit}
or
\tcode{badbit}
is set in
\tcode{rdstate()}.\footnote{Checking
\tcode{badbit}
also for
\tcode{fail()}
is historical practice.}
\end{itemdescr}

\indexlibrary{\idxcode{bad}!\idxcode{basic_ios}}%
\begin{itemdecl}
bool bad() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true}
if
\tcode{badbit}
is set in
\tcode{rdstate()}.
\end{itemdescr}

\indexlibrary{\idxcode{exceptions}!\idxcode{basic_ios}}%
\begin{itemdecl}
iostate exceptions() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A mask that determines what elements set in
\tcode{rdstate()}
cause exceptions to be thrown.
\end{itemdescr}

\indexlibrary{\idxcode{exceptions}!\idxcode{basic_ios}}%
\indexlibrary{\idxcode{basic_ios}!\idxcode{exceptions}}%
\begin{itemdecl}
void exceptions(iostate except);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postcondition
\tcode{except == exceptions()}.

\pnum
\effects
Calls
\tcode{clear(rdstate())}.
\end{itemdescr}

\rSec2[std.ios.manip]{\tcode{ios_base} manipulators}

\rSec3[fmtflags.manip]{\tcode{fmtflags} manipulators}

\indexlibrary{\idxcode{boolalpha}}%
\begin{itemdecl}
ios_base& boolalpha(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::boolalpha)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{noboolalpha}}%
\begin{itemdecl}
ios_base& noboolalpha(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.unsetf(ios_base::boolalpha)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{showbase}}%
\begin{itemdecl}
ios_base& showbase(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::showbase)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{noshowbase}}%
\begin{itemdecl}
ios_base& noshowbase(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.unsetf(ios_base::showbase)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{showpoint}}%
\begin{itemdecl}
ios_base& showpoint(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::showpoint)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{noshowpoint}}%
\begin{itemdecl}
ios_base& noshowpoint(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.unsetf(ios_base::showpoint)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{showpos}}%
\begin{itemdecl}
ios_base& showpos(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::showpos)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{noshowpos}}%
\begin{itemdecl}
ios_base& noshowpos(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.unsetf(ios_base::showpos)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{skipws}}%
\begin{itemdecl}
ios_base& skipws(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::skipws)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{noskipws}}%
\begin{itemdecl}
ios_base& noskipws(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.unsetf(ios_base::skipws)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{uppercase}}%
\begin{itemdecl}
ios_base& uppercase(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::uppercase)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{nouppercase}}%
\begin{itemdecl}
ios_base& nouppercase(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.unsetf(ios_base::uppercase)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{unitbuf}}%
\begin{itemdecl}
ios_base& unitbuf(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::unitbuf)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{nounitbuf}}%
\begin{itemdecl}
ios_base& nounitbuf(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.unsetf(ios_base::unitbuf)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\rSec3[adjustfield.manip]{\tcode{adjustfield} manipulators}

\indexlibrary{\idxcode{internal}}%
\begin{itemdecl}
ios_base& internal(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::internal, ios_base::adjustfield)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{left}}%
\begin{itemdecl}
ios_base& left(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::left, ios_base::adjustfield)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{right}}%
\begin{itemdecl}
ios_base& right(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::right, ios_base::adjustfield)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\rSec3[basefield.manip]{\tcode{basefield} manipulators}

\indexlibrary{\idxcode{dec}}%
\begin{itemdecl}
ios_base& dec(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::dec, ios_base::basefield)}.

\pnum
\returns
\tcode{str}\footnote{The function signature
\tcode{dec(ios_base\&)}
can be called by
the function signature
\tcode{basic_ostream\& stream::operator\shl(ios_base\& (*)(ios_base\&))}
to permit expressions of the form
\tcode{cout \shl dec}
to change the format flags stored in
\tcode{cout}.}.
\end{itemdescr}

\indexlibrary{\idxcode{hex}}%
\begin{itemdecl}
ios_base& hex(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::hex, ios_base::basefield)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{oct}}%
\begin{itemdecl}
ios_base& oct(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::oct, ios_base::basefield)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\rSec3[floatfield.manip]{\tcode{floatfield} manipulators}

\indexlibrary{\idxcode{fixed}}%
\begin{itemdecl}
ios_base& fixed(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::fixed, ios_base::floatfield)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{scientific}}%
\begin{itemdecl}
ios_base& scientific(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{str.setf(ios_base::scientific, ios_base::floatfield)}.

\pnum
\returns
\tcode{str}.
\end{itemdescr}

\indexlibrary{\idxcode{hexfloat}}%
\begin{itemdecl}
ios_base& hexfloat(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Calls \tcode{str.setf(ios_base::fixed | ios_base::scientific,
        ios_base::floatfield)}.

\pnum\returns \tcode{str}.
\end{itemdescr}

\pnum
\enternote The more obvious use of
\tcode{ios_base::hex} to specify hexadecimal floating-point format would
change the meaning of existing well defined programs. C++2003
gives no meaning to the combination of \tcode{fixed} and
\tcode{scientific}.\exitnote

\indexlibrary{\idxcode{defaultfloat}}%
\begin{itemdecl}
ios_base& defaultfloat(ios_base& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls \tcode{str.unsetf(ios_base::floatfield)}.

\pnum
\returns \tcode{str}.
\end{itemdescr}

\rSec3[error.reporting]{Error reporting}

\indexlibrary{\idxcode{make_error_code}}%
\begin{itemdecl}
error_code make_error_code(io_errc e) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{error_code(static_cast<int>(e), iostream_category())}.
\end{itemdescr}

\indexlibrary{\idxcode{make_error_condition}}%
\begin{itemdecl}
error_condition make_error_condition(io_errc e) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns \tcode{error_condition(static_cast<int>(e), iostream_category())}.
\end{itemdescr}

\indexlibrary{\idxcode{iostream_category}}%
\begin{itemdecl}
const error_category& iostream_category() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns A reference to an object of a type derived from class
\tcode{error_category}.

\pnum
The object's \tcode{default_error_condition} and \tcode{equivalent} virtual functions shall behave as specified for the class \tcode{error_category}. The object's \tcode{name} virtual function shall return a pointer to the string \tcode{"iostream"}.
\end{itemdescr}


\rSec1[stream.buffers]{Stream buffers}

\rSec2[stream.buffers.overview]{Overview}

\synopsis{Header \tcode{<streambuf>} synopsis}
\indexlibrary{\idxhdr{streambuf}}%

\indexlibrary{\idxcode{streambuf}}%
\indexlibrary{\idxcode{basic_streambuf<char>}}%
\indexlibrary{\idxcode{wstreambuf}}%
\indexlibrary{\idxcode{basic_streambuf<wchar_t>}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
    class basic_streambuf;
  typedef basic_streambuf<char>     streambuf;
  typedef basic_streambuf<wchar_t> wstreambuf;
}
\end{codeblock}

\pnum
The header
\tcode{<streambuf>}
defines types that control input from and output to
\textit{character}
sequences.

\rSec2[streambuf.reqts]{Stream buffer requirements}

\pnum
Stream buffers can impose various constraints on the sequences they control.
Some constraints are:
\begin{itemize}
\item
The controlled input sequence can be not readable.
\item
The controlled output sequence can be not writable.
\item
The controlled sequences can be associated with the contents of other
representations for character sequences, such as external files.
\item
The controlled sequences can support operations
\textit{directly}
to or from associated sequences.
\item
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.
\end{itemize}

\pnum
Each sequence is characterized by three pointers which, if non-null,
all point into the same
\tcode{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:
\begin{itemize}
\item
the
\term{beginning pointer},
or lowest element address in the array
(called \tcode{xbeg} here);
\item
the
\term{next pointer},
or next element address that is a current
candidate for reading or writing (called \tcode{xnext} here);
\item
the
\term{end pointer},
or first element address beyond the end of
the array (called \tcode{xend} here).
\end{itemize}

\pnum
The following semantic constraints shall always apply for any set of
three pointers for a sequence, using the pointer names given immediately above:
\begin{itemize}
\item
If \tcode{xnext} is not a null pointer, then
\tcode{xbeg} and \tcode{xend} shall also be non-null pointers
into the same
\tcode{charT}
array, as described above; otherwise, \tcode{xbeg} and
\tcode{xend} shall also be null.
\item
If \tcode{xnext} is not a null pointer and
\tcode{xnext < xend}
for an output sequence, then a
\term{write position}
is available.
In this case,
\tcode{*xnext}
shall be assignable as the
next element to write
(to put, or to store a character value, into the sequence).
\item
If \tcode{xnext} is not a null pointer and
\tcode{xbeg < xnext} for an input sequence,
then a
\term{putback position}
is available.
In this case,
\tcode{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.
\item
If \tcode{xnext} is not a null pointer and
\tcode{xnext < xend} for an input sequence,
then a
\term{read position}
is available.
In this case,
\tcode{*xnext}
shall have a defined value
and is the next element to read
(to get, or to obtain a character value, from the sequence).
\end{itemize}

\rSec2[streambuf]{Class template \tcode{basic_streambuf<charT,traits>}}

\indexlibrary{\idxcode{basic_streambuf}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_streambuf {
  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;

    virtual ~basic_streambuf();

    // \ref{streambuf.locales} locales:
    locale   pubimbue(const locale& loc);
    locale   getloc() const;

    // \ref{streambuf.buffer} buffer and positioning:
    basic_streambuf<char_type,traits>*
       pubsetbuf(char_type* s, streamsize n);
    pos_type pubseekoff(off_type off, ios_base::seekdir way,
      ios_base::openmode which =
          ios_base::in | ios_base::out);
    pos_type pubseekpos(pos_type sp,
      ios_base::openmode which =
          ios_base::in | ios_base::out);
    int      pubsync();

    // Get and put areas:
    // \ref{streambuf.pub.get} Get area:
    streamsize in_avail();
    int_type snextc();
    int_type sbumpc();
    int_type sgetc();
    streamsize sgetn(char_type* s, streamsize n);

    // \ref{streambuf.pub.pback} Putback:
    int_type sputbackc(char_type c);
    int_type sungetc();

    // \ref{streambuf.pub.put} Put area:
    int_type   sputc(char_type c);
    streamsize sputn(const char_type* s, streamsize n);

  protected:
    basic_streambuf();
    basic_streambuf(const basic_streambuf& rhs);
    basic_streambuf& operator=(const basic_streambuf& rhs);

    void swap(basic_streambuf& rhs);

    // \ref{streambuf.get.area} Get area:
    char_type* eback() const;
    char_type* gptr()  const;
    char_type* egptr() const;
    void       gbump(int n);
    void       setg(char_type* gbeg, char_type* gnext, char_type* gend);

    // \ref{streambuf.put.area} Put area:
    char_type* pbase() const;
    char_type* pptr() const;
    char_type* epptr() const;
    void       pbump(int n);
    void       setp(char_type* pbeg, char_type* pend);

    // \ref{streambuf.virtuals} virtual functions:
    // \ref{streambuf.virt.locales} Locales:
    virtual void imbue(const locale& loc);

    // \ref{streambuf.virt.buffer} Buffer management and positioning:
    virtual basic_streambuf<char_type,traits>*
         setbuf(char_type* s, streamsize n);
    virtual pos_type seekoff(off_type off, ios_base::seekdir way,
        ios_base::openmode which = ios_base::in | ios_base::out);
    virtual pos_type seekpos(pos_type sp,
        ios_base::openmode which = ios_base::in | ios_base::out);
    virtual int      sync();

    // \ref{streambuf.virt.get} Get area:
    virtual streamsize showmanyc();
    virtual streamsize xsgetn(char_type* s, streamsize n);
    virtual int_type   underflow();
    virtual int_type   uflow();

    // \ref{streambuf.virt.pback} Putback:
    virtual int_type   pbackfail(int_type c = traits::eof());

    // \ref{streambuf.virt.put} Put area:
    virtual streamsize xsputn(const char_type* s, streamsize n);
    virtual int_type   overflow (int_type c = traits::eof());
  };
}
\end{codeblock}

\pnum
The class template
\tcode{basic_streambuf<charT,traits>}
serves as an abstract base class for deriving various
\term{stream buffers}
whose objects each control two
\term{character sequences}:
\begin{itemize}
\item
a character
\term{input sequence};
\item
a character
\term{output sequence}.
\end{itemize}

\rSec3[streambuf.cons]{\tcode{basic_streambuf} constructors}

\indexlibrary{\idxcode{basic_streambuf}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
basic_streambuf();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_streambuf<charT,traits>}
and initializes:\footnote{The default constructor is protected for class
\tcode{basic_streambuf}
to assure that only objects for classes
derived from this class may be constructed.}
\begin{itemize}
\item
all its pointer member objects to null pointers,
\item
the
\tcode{getloc()}
member to a copy the global locale,
\tcode{locale()},
at the time of construction.
\end{itemize}

\pnum
\notes
Once the
\tcode{getloc()}
member is initialized, results of calling locale member functions,
and of members of facets so obtained, can safely be cached until the
next time the member
\tcode{imbue}
is called.
\end{itemdescr}

\indexlibrary{\idxcode{basic_streambuf}!constructor}%
\begin{itemdecl}
basic_streambuf(const basic_streambuf& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Constructs a copy of \tcode{rhs}.

\pnum
\postconditions

\begin{itemize}
\item \tcode{eback() == rhs.eback()}
\item \tcode{gptr() == rhs.gptr()}
\item \tcode{egptr() == rhs.egptr()}
\item \tcode{pbase() == rhs.pbase()}
\item \tcode{pptr() == rhs.pptr()}
\item \tcode{epptr() == rhs.epptr()}
\item \tcode{getloc() == rhs.getloc()}
\end{itemize}
\end{itemdescr}

\indexlibrary{\idxcode{basic_streambuf}!destructor}%
\begin{itemdecl}
~basic_streambuf();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
None.
\end{itemdescr}

\rSec3[streambuf.members]{\tcode{basic_streambuf} public member functions}

\rSec4[streambuf.locales]{Locales}

\indexlibrary{\idxcode{pubimbue}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
locale pubimbue(const locale& loc);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postcondition
\tcode{loc == getloc()}.

\pnum
\effects
Calls
\tcode{imbue(loc)}.

\pnum
\returns
Previous value of
\tcode{getloc()}.
\end{itemdescr}

\indexlibrary{\idxcode{getloc}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
locale getloc() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If
\tcode{pubimbue()}
has ever been called, then the last value of \tcode{loc} supplied,
otherwise the current global locale,
\tcode{locale()},
in effect at the time of construction.
If called after
\tcode{pubimbue()}
has been called but before
\tcode{pubimbue}
has returned (i.e., from within the call of
\tcode{imbue()})
then it returns the previous value.
\end{itemdescr}

\rSec4[streambuf.buffer]{Buffer management and positioning}

\indexlibrary{\idxcode{pubsetbuf}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
basic_streambuf<char_type,traits>* pubsetbuf(char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{setbuf(s, n)}.
\end{itemdescr}

\indexlibrary{\idxcode{pubseekoff}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
pos_type pubseekoff(off_type off, ios_base::seekdir way,
               ios_base::openmode which = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{seekoff(off, way, which)}.
\end{itemdescr}

\indexlibrary{\idxcode{pubseekpos}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
pos_type pubseekpos(pos_type sp,
               ios_base::openmode which = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{seekpos(sp, which)}.
\end{itemdescr}

\indexlibrary{\idxcode{pubsync}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int pubsync();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{sync()}.
\end{itemdescr}

\rSec4[streambuf.pub.get]{Get area}

\indexlibrary{\idxcode{in_avail}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
streamsize in_avail();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If a read position is available, returns
\tcode{egptr() - gptr()}.
Otherwise returns
\tcode{showmanyc()} (\ref{streambuf.virt.get}).
\end{itemdescr}

\indexlibrary{\idxcode{snextc}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type snextc();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{sbumpc()}.

\pnum
\returns
If that function returns
\tcode{traits::eof()},
returns
\tcode{traits::eof()}.
Otherwise, returns
\tcode{sgetc()}.
\end{itemdescr}

\indexlibrary{\idxcode{sbumpc}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type sbumpc();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If the input sequence read position is not available,
returns
\tcode{uflow()}.
Otherwise, returns
\tcode{traits::to_int_type(*gptr())}
and increments the next pointer for the input sequence.
\end{itemdescr}

\indexlibrary{\idxcode{sgetc}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type sgetc();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If the input sequence read position is not available,
returns
\tcode{underflow()}.
Otherwise, returns
\tcode{traits\colcol{}to_int_type(*gptr())}.
\end{itemdescr}

\indexlibrary{\idxcode{sgetn}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
streamsize sgetn(char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{xsgetn(s, n)}.
\end{itemdescr}

\rSec4[streambuf.pub.pback]{Putback}

\indexlibrary{\idxcode{sputbackc}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type sputbackc(char_type c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If the input sequence putback position is not available, or
if
\tcode{traits::eq(c,gptr()[-1])}
is false, returns
\tcode{pbackfail(traits::to_int_type(c))}.
Otherwise, decrements the next pointer for the input sequence and
returns
\tcode{traits::to_int_type(*gptr())}.
\end{itemdescr}

\indexlibrary{\idxcode{sungetc}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type sungetc();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If the input sequence putback position is not available,
returns
\tcode{pbackfail()}.
Otherwise, decrements the next pointer for the input sequence and
returns
\tcode{traits::to_int_type(*gptr())}.
\end{itemdescr}

\rSec4[streambuf.pub.put]{Put area}

\indexlibrary{\idxcode{sputc}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type sputc(char_type c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If the output sequence write position is not available,
returns
\tcode{overflow(traits::to_int_type(c))}.
Otherwise, stores \tcode{c} at the next pointer for the output sequence,
increments the pointer, and
returns
\tcode{traits::to_int_type(c)}.
\end{itemdescr}

\indexlibrary{\idxcode{sputn}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
streamsize sputn(const char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{xsputn(s,n)}.
\end{itemdescr}

\rSec3[streambuf.protected]{\tcode{basic_streambuf} protected member functions}

\rSec4[streambuf.assign]{Assignment}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_streambuf}}%
\indexlibrary{\idxcode{basic_streambuf}!\idxcode{operator=}}%
\begin{itemdecl}
basic_streambuf& operator=(const basic_streambuf& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Assigns the data members of \tcode{rhs}
to \tcode{*this}.

\pnum
\postconditions

\begin{itemize}
\item \tcode{eback() == rhs.eback()}
\item \tcode{gptr() == rhs.gptr()}
\item \tcode{egptr() == rhs.egptr()}
\item \tcode{pbase() == rhs.pbase()}
\item \tcode{pptr() == rhs.pptr()}
\item \tcode{epptr() == rhs.epptr()}
\item \tcode{getloc() == rhs.getloc()}
\end{itemize}

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_streambuf}}%
\indexlibrary{\idxcode{basic_streambuf}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_streambuf& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Swaps the data members of \tcode{rhs}
and \tcode{*this}.
\end{itemdescr}

\rSec4[streambuf.get.area]{Get area access}

\indexlibrary{\idxcode{eback}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
char_type* eback() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The beginning pointer for the input sequence.
\end{itemdescr}

\indexlibrary{\idxcode{gptr}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
char_type* gptr() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The next pointer for the input sequence.
\end{itemdescr}

\indexlibrary{\idxcode{egptr}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
char_type* egptr() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The end pointer for the input sequence.
\end{itemdescr}

\indexlibrary{\idxcode{gbump}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
void gbump(int n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Adds \tcode{n} to the next pointer for the input sequence.
\end{itemdescr}

\indexlibrary{\idxcode{setg}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
void setg(char_type* gbeg, char_type* gnext, char_type* gend);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postconditions
\tcode{gbeg == eback()},
\tcode{gnext == gptr()},
and
\tcode{gend == egptr()}.
\end{itemdescr}

\rSec4[streambuf.put.area]{Put area access}

\indexlibrary{\idxcode{pbase}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
char_type* pbase() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The beginning pointer for the output sequence.
\end{itemdescr}

\indexlibrary{\idxcode{pptr}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
char_type* pptr() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The next pointer for the output sequence.
\end{itemdescr}

\indexlibrary{\idxcode{epptr}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
char_type* epptr() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The end pointer for the output sequence.
\end{itemdescr}

\indexlibrary{\idxcode{pbump}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
void pbump(int n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Adds \tcode{n} to the next pointer for the output sequence.
\end{itemdescr}

\indexlibrary{\idxcode{setp}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
void setp(char_type* pbeg, char_type* pend);
\end{itemdecl}

\begin{itemdescr}
\pnum
\postconditions
\tcode{pbeg == pbase()},
\tcode{pbeg == pptr()},
and
\tcode{pend == epptr()}.
\end{itemdescr}

\rSec3[streambuf.virtuals]{\tcode{basic_streambuf} virtual functions}

\rSec4[streambuf.virt.locales]{Locales}

\indexlibrary{\idxcode{imbue}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
void imbue(const locale&)
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Change any translations based on locale.

\pnum
\notes
Allows the derived class to be informed of changes in locale at the
time they occur.
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.

\pnum
\default
Does nothing.
\end{itemdescr}

\rSec4[streambuf.virt.buffer]{Buffer management and positioning}

\indexlibrary{\idxcode{setbuf}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
basic_streambuf* setbuf(char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Influences stream buffering in a way that is defined separately for each class
derived from
\tcode{basic_streambuf}
in this Clause~(\ref{stringbuf.virtuals},
\ref{filebuf.virtuals}).

\pnum
\default
Does nothing.
Returns
\tcode{this}.
\end{itemdescr}

\indexlibrary{\idxcode{seekoff}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
pos_type seekoff(off_type off, ios_base::seekdir way,
                 ios_base::openmode which
                  = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Alters the stream positions within one or more of
the controlled sequences in a way that is defined separately for each class
derived from
\tcode{basic_streambuf}
in this Clause~(\ref{stringbuf.virtuals},
\ref{filebuf.virtuals}).

\pnum
\default
Returns
\tcode{pos_type(off_type(-1))}.
\end{itemdescr}

\indexlibrary{\idxcode{seekpos}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
pos_type seekpos(pos_type sp,
                 ios_base::openmode which
                  = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Alters the stream positions within one or more of
the controlled sequences in a way that is defined separately for each class
derived from
\tcode{basic_streambuf}
in this Clause~(\ref{stringbuf},
\ref{filebuf}).

\pnum
\default
Returns
\tcode{pos_type(off_type(-1))}.
\end{itemdescr}

\indexlibrary{\idxcode{sync}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int sync();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Synchronizes the controlled sequences with the arrays.
That is, if
\tcode{pbase()}
is non-null the characters between
\tcode{pbase()}
and
\tcode{pptr()}
are written to the controlled sequence.
The pointers may then be reset as appropriate.

\pnum
\returns
-1 on failure.
What constitutes failure is determined by each derived class~(\ref{filebuf.virtuals}).

\pnum
\default
Returns zero.
\end{itemdescr}

\rSec4[streambuf.virt.get]{Get area}

\indexlibrary{\idxcode{showmanyc}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
streamsize showmanyc();@\footnote{\textrm{The morphemes of \tcode{showmanyc}\
are ``es-how-many-see'', not ``show-manic''.}}@
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An estimate of the number of
characters available in the sequence, or -1.
If it returns
a positive value, then successive calls to
\tcode{underflow()}
will not return
\tcode{traits::eof()}
until at least that number of characters have been
extracted from the stream.
If
\tcode{showmanyc()}
returns -1, then calls to
\tcode{underflow()}
or
\tcode{uflow()}
will fail.\footnote{\tcode{underflow}
or
\tcode{uflow}
might fail by throwing an exception prematurely.
The intention is not only that the calls will not return
\tcode{eof()}
but that they will return ``immediately.''}

\pnum
\default
Returns zero.

\pnum
\notes
Uses
\tcode{traits::eof()}.
\end{itemdescr}

\indexlibrary{\idxcode{xsgetn}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
streamsize xsgetn(char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Assigns up to \tcode{n} characters to successive elements of
the array whose first element is designated by \tcode{s}.
The characters assigned are read from the input sequence as if
by repeated calls to
\tcode{sbumpc()}.
Assigning stops when either \tcode{n} characters
have been assigned or a call to
\tcode{sbumpc()}
would return
\tcode{traits::eof()}.

\pnum
\returns
The number of characters assigned.\footnote{Classes derived from
\tcode{basic_streambuf}
can provide more efficient ways to implement
\tcode{xsgetn()}
and
\tcode{xsputn()}
by overriding these definitions from the base class.}

\pnum
\notes
Uses
\tcode{traits::eof()}.
\end{itemdescr}

\indexlibrary{\idxcode{underflow}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type underflow();
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
The public members of
\tcode{basic_streambuf}
call this virtual function only if
\tcode{gptr()}
is null or
\tcode{gptr() >= egptr()}

\pnum
\returns
\tcode{traits::to_int_type(c)},
where \tcode{c} is the first
\textit{character}
of the
\term{pending sequence},
without moving the input sequence position past it.
If the pending sequence is null then the function returns
\tcode{traits::eof()}
to indicate failure.

\pnum
The
\term{pending sequence}
of characters is defined as the concatenation of:
\begin{enumeratea}
\item
If
\tcode{gptr()}
is non-null, then the
\tcode{egptr() - gptr()}
characters starting at
\tcode{gptr()},
otherwise the empty sequence.
\item
Some sequence (possibly empty) of characters read from the input sequence.
\end{enumeratea}

\pnum
The
\term{result character}
is
\begin{enumeratea}
\item
If the pending sequence is non-empty, the first character of the sequence.
\item
If the pending sequence
is
empty then the next character that would be read from the input sequence.
\end{enumeratea}

\pnum
The
\term{backup sequence}
is defined as the concatenation of:
\begin{enumeratea}
\item
If
\tcode{eback()}
is null then empty,
\item
Otherwise the
\tcode{gptr() - eback()}
characters beginning at
\tcode{eback()}.
\end{enumeratea}

\pnum
\effects
The function sets up the
\tcode{gptr()}
and
\tcode{egptr()}
satisfying one of:
\begin{enumeratea}
\item
If the pending sequence is non-empty,
\tcode{egptr()}
is non-null and
\tcode{egptr() - gptr()}
characters starting at
\tcode{gptr()}
are the characters in the pending sequence
\item
If the pending sequence is empty, either
\tcode{gptr()}
is null or
\tcode{gptr()}
and
\tcode{egptr()}
are set to the same non-null pointer value.
\end{enumeratea}

\pnum
If
\tcode{eback()}
and
\tcode{gptr()}
are non-null then the function is not constrained as to their contents, but the ``usual backup condition'' is that either:
\begin{enumeratea}
\item
If the backup sequence contains at least
\tcode{gptr() - eback()}
characters, then the
\tcode{gptr() - eback()}
characters starting at
\tcode{eback()}
agree with the last
\tcode{gptr() - eback()}
characters of the backup sequence.
\item
Or the \tcode{n} characters starting at
\tcode{gptr() - n}
agree with the backup sequence (where \tcode{n} is the length of the backup sequence)
\end{enumeratea}

\pnum
\default
Returns
\tcode{traits::eof()}.
\end{itemdescr}

\indexlibrary{\idxcode{uflow}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type uflow();
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
The constraints are the same as for
\tcode{underflow()},
except that the result character shall be transferred from the pending
sequence to the backup sequence, and the pending sequence shall not
be empty before the transfer.

\pnum
\default
Calls
\tcode{underflow()}.
If
\tcode{underflow()}
returns
\tcode{traits::eof()},
returns
\tcode{traits::eof()}.
Otherwise, returns the value of
\tcode{traits::to_int_type(*gptr())}
and increment the value of the next pointer for the input sequence.

\pnum
\returns
\tcode{traits::eof()}
to indicate failure.
\end{itemdescr}

\rSec4[streambuf.virt.pback]{Putback}

\indexlibrary{\idxcode{pbackfail}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type pbackfail(int_type c = traits::eof());
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
The public functions of
\tcode{basic_streambuf}
call this virtual function only when
\tcode{gptr()}
is null,
\tcode{gptr() == eback()},
or
\tcode{traits::eq(traits::to_char_type(c),gptr()[-1])}
returns
\tcode{false}.
Other calls shall also satisfy that constraint.

The
\term{pending sequence}
is defined as for
\tcode{underflow()},
with the modifications that
\begin{itemize}
\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{true},
then the input sequence is backed up one character before the pending sequence is determined.
\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns \tcode{false}, then \tcode{c} is prepended.
Whether the input sequence is backed up or modified in any other way is unspecified.
\end{itemize}

\pnum
\postcondition
On return, the constraints of
\tcode{gptr()},
\tcode{eback()},
and
\tcode{pptr()}
are the same as for
\tcode{underflow()}.

\pnum
\returns
\tcode{traits::eof()}
to indicate failure.
Failure may occur because the input sequence could not be backed up, or if for some
other reason the pointers could not be set consistent with the constraints.
\tcode{pbackfail()}
is called only when put back has really failed.

\pnum
Returns some value other than
\tcode{traits::eof()}
to indicate success.

\pnum
\default
Returns
\tcode{traits::eof()}.
\end{itemdescr}

\rSec4[streambuf.virt.put]{Put area}

\indexlibrary{\idxcode{xsputn}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
streamsize xsputn(const char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Writes up to \tcode{n} characters to the output sequence as if
by repeated calls to
\tcode{sputc(c)}.
The characters written are obtained from successive elements of
the array whose first element is designated by \tcode{s}.
Writing stops when either \tcode{n} characters have been written or
a call to
\tcode{sputc(c)}
would return
\tcode{traits::eof()}.
Is is unspecified whether the function calls \tcode{overflow()} when \tcode{pptr() == epptr()} becomes true or whether it achieves the same effects by other means.

\pnum
\returns
The number of characters written.
\end{itemdescr}

\indexlibrary{\idxcode{overflow}!\idxcode{basic_streambuf}}%
\begin{itemdecl}
int_type overflow(int_type c = traits::eof());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Consumes some initial subsequence of the characters of the
\term{pending sequence}.
The pending sequence is defined as the concatenation of
\begin{enumeratea}
\item
if
\tcode{pbase()}
is null then the empty sequence otherwise,
\tcode{pptr() - pbase()}
characters beginning at
\tcode{pbase()}.
\item
if
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{true},
then the empty sequence
otherwise, the sequence consisting of \tcode{c}.
\end{enumeratea}

\pnum
\notes
The member functions
\tcode{sputc()}
and
\tcode{sputn()}
call this function in case that
no room can be found in the put buffer enough to accommodate the
argument character sequence.

\pnum
\requires
Every overriding definition of this virtual function
shall obey the following constraints:
\begin{enumeraten}
\item
The effect of consuming a character on the associated output sequence is
specified\footnote{That is, for each class derived from an instance of
\tcode{basic_streambuf}
in this Clause~(\ref{stringbuf},
\ref{filebuf}),
a specification of how consuming a character effects the associated output sequence is given.
There is no requirement on a program-defined class.}
\item
Let
\tcode{r}
be the number of characters in the pending sequence not consumed.
If
\tcode{r}
is non-zero then
\tcode{pbase()}
and
\tcode{pptr()}
shall be set so that:
\tcode{pptr() - pbase() == r}
and the \tcode{r} characters starting at
\tcode{pbase()}
are the associated output stream.
In case \tcode{r}  is zero (all characters of the pending sequence have been consumed)
then either
\tcode{pbase()}
is set to
\tcode{nullptr},
or
\tcode{pbase()}
and
\tcode{pptr()}
are both set to the same non-null value.
\item
The function may fail if either
appending some character to the associated output stream fails or
if it is unable to establish
\tcode{pbase()}
and
\tcode{pptr()}
according to the above rules.
\end{enumeraten}

\pnum
\returns
\tcode{traits::eof()}
or throws an exception
if the function fails.

Otherwise,
returns some value other than
\tcode{traits::eof()}
to indicate success.\footnote{Typically,
\tcode{overflow}
returns \tcode{c} to indicate success, except when
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{true},
in which case it returns
\tcode{traits::not_eof(c)}.}

\pnum
\default
Returns
\tcode{traits::eof()}.
\end{itemdescr}

\rSec1[iostream.format]{Formatting and manipulators}

\rSec2[iostream.format.overview]{Overview}

\indexlibrary{\idxhdr{istream}}%
\synopsis{Header \tcode{<istream>} synopsis}

\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
    class basic_istream;
  typedef basic_istream<char>     istream;
  typedef basic_istream<wchar_t> wistream;

  template <class charT, class traits = char_traits<charT> >
    class basic_iostream;
  typedef basic_iostream<char>    iostream;
  typedef basic_iostream<wchar_t> wiostream;

  template <class charT, class traits>
    basic_istream<charT,traits>& ws(basic_istream<charT,traits>& is);

  template <class charT, class traits, class T>
    basic_istream<charT, traits>&
    operator>>(basic_istream<charT, traits>&& is, T& x);
}
\end{codeblock}

\indexlibrary{\idxcode{istream}}%
\indexlibrary{\idxcode{basic_istream<char>}}%
\indexlibrary{\idxcode{wistream}}%
\indexlibrary{\idxcode{basic_istream<wchar_t>}}%

\synopsis{Header \tcode{<ostream>} synopsis}
\indexlibrary{\idxhdr{ostream}}%

\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
    class basic_ostream;
  typedef basic_ostream<char>     ostream;
  typedef basic_ostream<wchar_t> wostream;

  template <class charT, class traits>
    basic_ostream<charT,traits>& endl(basic_ostream<charT,traits>& os);
  template <class charT, class traits>
    basic_ostream<charT,traits>& ends(basic_ostream<charT,traits>& os);
  template <class charT, class traits>
    basic_ostream<charT,traits>& flush(basic_ostream<charT,traits>& os);

  template <class charT, class traits, class T>
    basic_ostream<charT, traits>&
    operator<<(basic_ostream<charT, traits>&& os, const T& x);
}
\end{codeblock}

\indexlibrary{\idxcode{ostream}}%
\indexlibrary{\idxcode{basic_ostream<char>}}%
\indexlibrary{\idxcode{wostream}}%
\indexlibrary{\idxcode{basic_ostream<wchar_t>}}%

\synopsis{Header \tcode{<iomanip>} synopsis}
\indexlibrary{\idxhdr{iomanip}}%

\begin{codeblock}
namespace std {
  // types \tcode{T1}, \tcode{T2}, ... are unspecified implementation types
  @\textit{T1}@ resetiosflags(ios_base::fmtflags mask);
  @\textit{T2}@ setiosflags  (ios_base::fmtflags mask);
  @\textit{T3}@ setbase(int base);
  template<charT> @\textit{T4}@ setfill(charT c);
  @\textit{T5}@ setprecision(int n);
  @\textit{T6}@ setw(int n);
  template <class moneyT> @\textit{T7}@ get_money(moneyT& mon, bool intl = false);
  template <class moneyT> @\textit{T8}@ put_money(const moneyT& mon, bool intl = false);
  template <class charT> @\textit{T9}@ get_time(struct tm* tmb, const charT* fmt);
  template <class charT> @\textit{T10}@ put_time(const struct tm* tmb, const charT* fmt);

  template <class charT>
    @\textit{T11}@ quoted(const charT* s, charT delim=charT('"'), charT escape=charT('\\'));

  template <class charT, class traits, class Allocator>
    @\textit{T12}@ quoted(const basic_string<charT, traits, Allocator>& s,
               charT delim=charT('"'), charT escape=charT('\\'));

  template <class charT, class traits, class Allocator>
    @\textit{T13}@ quoted(basic_string<charT, traits, Allocator>& s,
               charT delim=charT('"'), charT escape=charT('\\'));
}
\end{codeblock}

\rSec2[input.streams]{Input streams}

\pnum
The header
\tcode{<istream>}
defines two types
and a function signature that control input from a stream buffer along with a function template that extracts from stream rvalues.

\rSec3[istream]{Class template \tcode{basic_istream}}

\indexlibrary{\idxcode{basic_istream}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_istream : virtual public basic_ios<charT,traits> {
  public:
    // types (inherited from \tcode{basic_ios} (\ref{ios})):
    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;

    // \ref{istream.cons} Constructor/destructor:
    explicit basic_istream(basic_streambuf<charT,traits>* sb);
    virtual ~basic_istream();

    // \ref{istream::sentry} Prefix/suffix:
    class sentry;

    // \ref{istream.formatted} Formatted input:
    basic_istream<charT,traits>& operator>>(
      basic_istream<charT,traits>& (*pf)(basic_istream<charT,traits>&));
    basic_istream<charT,traits>& operator>>(
			basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
    basic_istream<charT,traits>& operator>>(
      ios_base& (*pf)(ios_base&));

    basic_istream<charT,traits>& operator>>(bool& n);
    basic_istream<charT,traits>& operator>>(short& n);
    basic_istream<charT,traits>& operator>>(unsigned short& n);
    basic_istream<charT,traits>& operator>>(int& n);
    basic_istream<charT,traits>& operator>>(unsigned int& n);
    basic_istream<charT,traits>& operator>>(long& n);
    basic_istream<charT,traits>& operator>>(unsigned long& n);
    basic_istream<charT,traits>& operator>>(long long& n);
    basic_istream<charT,traits>& operator>>(unsigned long long& n);
    basic_istream<charT,traits>& operator>>(float& f);
    basic_istream<charT,traits>& operator>>(double& f);
    basic_istream<charT,traits>& operator>>(long double& f);

    basic_istream<charT,traits>& operator>>(void*& p);
    basic_istream<charT,traits>& operator>>(
      basic_streambuf<char_type,traits>* sb);

    // \ref{istream.unformatted} Unformatted input:
    streamsize gcount() const;
    int_type get();
    basic_istream<charT,traits>& get(char_type& c);
    basic_istream<charT,traits>& get(char_type* s, streamsize n);
    basic_istream<charT,traits>& get(char_type* s, streamsize n,
                                     char_type delim);
    basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb);
    basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb,
                                    char_type delim);

    basic_istream<charT,traits>& getline(char_type* s, streamsize n);
    basic_istream<charT,traits>& getline(char_type* s, streamsize n,
                                         char_type delim);

    basic_istream<charT,traits>& ignore(
      streamsize n = 1, int_type delim = traits::eof());
    int_type                     peek();
    basic_istream<charT,traits>& read    (char_type* s, streamsize n);
    streamsize                   readsome(char_type* s, streamsize n);

    basic_istream<charT,traits>& putback(char_type c);
    basic_istream<charT,traits>& unget();
    int sync();

    pos_type tellg();
    basic_istream<charT,traits>& seekg(pos_type);
    basic_istream<charT,traits>& seekg(off_type, ios_base::seekdir);

  protected:
    basic_istream(const basic_istream& rhs) = delete;
    basic_istream(basic_istream&& rhs);

    // \ref{istream.assign} Assign/swap:
    basic_istream& operator=(const basic_istream& rhs) = delete;
    basic_istream& operator=(basic_istream&& rhs);
    void swap(basic_istream& rhs);
  };

  // \ref{istream::extractors} character extraction templates:
  template<class charT, class traits>
    basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>&,
                                            charT&);
  template<class traits>
    basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
                                           unsigned char&);
  template<class traits>
    basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
                                           signed char&);

  template<class charT, class traits>
    basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>&,
                                            charT*);
  template<class traits>
    basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
                                           unsigned char*);
  template<class traits>
    basic_istream<char,traits>& operator>>(basic_istream<char,traits>&,
                                           signed char*);
}
\end{codeblock}

\pnum
The class
\tcode{basic_istream}
defines a number of member function
signatures that assist in reading and interpreting input from sequences
controlled by a stream buffer.

\pnum
Two groups of member function signatures share common properties:
the
\term{formatted input functions}
(or
\term{extractors})
and the
\term{unformatted input functions.}
Both groups of input functions are described as if they obtain (or
\term{extract})
input
\term{characters}
by calling
\tcode{rdbuf()->sbumpc()}
or
\tcode{rdbuf()->sgetc()}.
They may use other public members of
\tcode{istream}.

\pnum
If
\tcode{rdbuf()->sbumpc()}
or
\tcode{rdbuf()->sgetc()}
returns
\tcode{traits::eof()},
then the input function, except as explicitly noted otherwise, completes its actions and does
\tcode{setstate(eofbit)},
which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags}), before returning.

\pnum
If one of these called functions throws an exception, then unless explicitly noted otherwise,
the input function sets
\tcode{badbit}
in error state.
If
\tcode{badbit}
is on in
\tcode{exceptions()},
the input function
rethrows the exception without completing its actions, otherwise
it does not throw anything and proceeds as if the called function had returned
a failure indication.

\rSec4[istream.cons]{\tcode{basic_istream} constructors}

\indexlibrary{\idxcode{basic_istream}!\idxcode{basic_istream}}%
\begin{itemdecl}
explicit basic_istream(basic_streambuf<charT,traits>* sb);
\end{itemdecl}

\indexlibrary{\idxcode{init}!\idxcode{basic_ios}}%
\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_istream},
assigning initial values to the base class by calling
\tcode{basic_ios::init(sb)}~(\ref{basic.ios.cons}).

\pnum
\postcondition
\tcode{gcount() == 0}
\end{itemdescr}


\indexlibrary{\idxcode{basic_istream}!constructor}%
\begin{itemdecl}
basic_istream(basic_istream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}.
This is accomplished by default constructing the base class, copying the
\tcode{gcount()} from \tcode{rhs}, calling
\tcode{basic_ios<charT, traits>::move(rhs)} to initialize the base
class, and setting the \tcode{gcount()} for \tcode{rhs} to 0.
\end{itemdescr}

\indexlibrary{\idxcode{basic_istream}!destructor}%
\begin{itemdecl}
virtual ~basic_istream();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys an object of class
\tcode{basic_istream}.

\pnum
\notes
Does not perform any operations of
\tcode{rdbuf()}.
\end{itemdescr}

\rSec4[istream.assign]{Class \tcode{basic_istream} assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_istream& operator=(basic_istream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{swap(rhs);}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_istream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{basic_ios<charT, traits>::swap(rhs)}.
Exchanges the values returned by \tcode{gcount()} and
\tcode{rhs.gcount()}.
\end{itemdescr}

\rSec4[istream::sentry]{Class \tcode{basic_istream::sentry}}

\indexlibrary{\idxcode{sentry}!\idxcode{basic_istream}}%
\begin{codeblock}
namespace std {
  template <class charT,class traits = char_traits<charT> >
  class basic_istream<charT,traits>::sentry {
    typedef traits traits_type;
    bool ok_; // \expos
  public:
    explicit sentry(basic_istream<charT,traits>& is, bool noskipws = false);
    ~sentry();
    explicit operator bool() const { return ok_; }
    sentry(const sentry&) = delete;
    sentry& operator=(const sentry&) = delete;
  };
}
\end{codeblock}

\begin{itemdescr}
\pnum
The class
\tcode{sentry}
defines a class that is responsible for doing exception safe prefix and suffix
operations.
\end{itemdescr}

\indexlibrary{\idxcode{sentry}!constructor}%
\begin{itemdecl}
explicit sentry(basic_istream<charT,traits>& is, bool noskipws = false);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If
\tcode{is.good()}
is
\tcode{false},
calls \tcode{is.setstate(failbit)}. Otherwise,
prepares for formatted or
unformatted input.
First, if
\tcode{is.tie()}
is not a null pointer, the
function calls
\indexlibrary{\idxcode{flush}}%
\tcode{is.tie()->flush()}
to synchronize the output sequence with any associated external
C stream.
Except that this call can be suppressed if the put area of
\tcode{is.tie()}
is empty.
Further an implementation is allowed to defer the call to
\tcode{flush}
until a
call of
\tcode{is.rdbuf()->underflow()}
occurs.
If no such call occurs before the
\tcode{sentry}
object is destroyed, the call to
\tcode{flush}
may be eliminated entirely.\footnote{This will be possible only in functions
that are part of the library.
The semantics of the constructor used in user code is as specified.}
If \tcode{noskipws} is zero and
\tcode{is.flags() \& ios_base::skipws}
is nonzero, the function extracts and discards each character as long as
the next available input character \tcode{c} is a whitespace character.
If
\tcode{is.rdbuf()->sbumpc()}
or
\tcode{is.rdbuf()->sgetc()}
returns
\tcode{traits::eof()},
the function calls
\tcode{setstate(failbit | eofbit)}
(which may throw
\tcode{ios_base::failure}).

\pnum
\notes
The constructor
\tcode{explicit sentry(basic_istream<charT,traits>\& is, bool noskipws = false)}
uses the currently imbued locale in \tcode{is},
to determine whether the next input character is
whitespace or not.

\pnum
To decide if the character \tcode{c} is a whitespace character,
the constructor performs as if it executes the following code fragment:
\begin{codeblock}
const ctype<charT>& ctype = use_facet<ctype<charT> >(is.getloc());
if (ctype.is(ctype.space,c)!=0)
  // \tcode{c} is a whitespace character.
\end{codeblock}

\pnum
If, after any preparation is completed,
\tcode{is.good()}
is
\tcode{true},
\tcode{ok_ != false}
otherwise,
\tcode{ok_ == false}.
During preparation, the constructor may call
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::\brk{}failure}~(\ref{iostate.flags}))\footnote{The sentry
constructor and destructor
can also perform additional
\indextext{implementation-dependent}%
implementation-dependent operations.}
\end{itemdescr}

\indexlibrary{\idxcode{basic_istream}!destructor}%
\begin{itemdecl}
~sentry();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
None.
\end{itemdescr}

\indexlibrary{\idxcode{operator bool}!\tcode{basic_istream}}%
\begin{itemdecl}
explicit operator bool() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Returns
\tcode{ok_}.
\end{itemdescr}

\rSec3[istream.formatted]{Formatted input functions}

\rSec4[istream.formatted.reqmts]{Common requirements}

\pnum
Each formatted input function begins execution by constructing an object of class
\tcode{sentry}
with the
\tcode{noskipws}
(second) argument
\tcode{false}.
If the
\tcode{sentry}
object returns
\tcode{true},
when converted to a value of type
\tcode{bool},
the function endeavors
to obtain the requested input.
If an exception is thrown during input then
\tcode{ios::badbit}
is turned on\footnote{This is done without causing an
\tcode{ios::failure}
to be thrown.}
in
\tcode{*this}'s
error state.
If
\tcode{(exceptions()\&badbit) != 0}
then the exception is rethrown.
In any case, the formatted input function destroys the
\tcode{sentry}
object.
If no exception has been thrown, it returns
\tcode{*this}.

\rSec4[istream.formatted.arithmetic]{Arithmetic extractors}

\indexlibrary{\idxcode{operator\shr}!\idxcode{istream}}%
\begin{itemdecl}
operator>>(unsigned short& val);
operator>>(unsigned int& val);
operator>>(long& val);
operator>>(unsigned long& val);
operator>>(long long& val);
operator>>(unsigned long long& val);
operator>>(float& val);
operator>>(double& val);
operator>>(long double& val);
operator>>(bool& val);
operator>>(void*& val);
\end{itemdecl}

\begin{itemdescr}
\pnum
As in the case of the inserters, these extractors depend on the
locale's
\tcode{num_get<>}~(\ref{locale.num.get}) object to perform parsing the input
stream data.
These extractors behave as formatted input functions (as described in~\ref{istream.formatted.reqmts}).  After a sentry object is constructed, the
conversion occurs as if performed by the following code fragment:

\begin{codeblock}
typedef num_get< charT,istreambuf_iterator<charT,traits> > numget;
iostate err = iostate::goodbit;
use_facet< numget >(loc).get(*this, 0, *this, err, val);
setstate(err);
\end{codeblock}

In the above fragment,
\tcode{loc}
stands for the private member of the
\tcode{basic_ios}
class.
\enternote
The first argument provides an object of the
\tcode{istreambuf_iterator}
class which is an iterator pointed to an input stream.
It bypasses istreams and uses streambufs directly.
\exitnote
Class
\tcode{locale}
relies on this
type as its interface to
\tcode{istream},
so that it does not need to depend directly on
\tcode{istream}.
\end{itemdescr}

\indexlibrary{\idxcode{operator\shr}!\idxcode{istream}}%
\begin{itemdecl}
operator>>(short& val);
\end{itemdecl}

\begin{itemdescr}
\pnum
The conversion occurs as if performed by the following code fragment
(using the same notation as for the preceding code fragment):
\begin{codeblock}
typedef num_get<charT,istreambuf_iterator<charT,traits> > numget;
iostate err = ios_base::goodbit;
long lval;
use_facet<numget>(loc).get(*this, 0, *this, err, lval);
if (lval < numeric_limits<short>::min()) {
  err |= ios_base::failbit;
  val = numeric_limits<short>::min();
} else if (numeric_limits<short>::max() < lval) {
  err |= ios_base::failbit;
  val = numeric_limits<short>::max();
}  else
  val = static_cast<short>(lval);
setstate(err);
\end{codeblock}
\end{itemdescr}

\indexlibrary{\idxcode{operator\shr}!\idxcode{istream}}%
\begin{itemdecl}
operator>>(int& val);
\end{itemdecl}

\begin{itemdescr}
\pnum
The conversion occurs as if performed by the following code fragment
(using the same notation as for the preceding code fragment):
\begin{codeblock}
typedef num_get<charT,istreambuf_iterator<charT,traits> > numget;
iostate err = ios_base::goodbit;
long lval;
use_facet<numget>(loc).get(*this, 0, *this, err, lval);
if (lval < numeric_limits<int>::min()) {
  err |= ios_base::failbit;
  val = numeric_limits<int>::min();
} else if (numeric_limits<int>::max() < lval) {
  err |= ios_base::failbit;
  val = numeric_limits<int>::max();
}  else
  val = static_cast<int>(lval);
setstate(err);
\end{codeblock}
\end{itemdescr}

\rSec4[istream::extractors]{\tcode{basic_istream::operator\shr}}

\indexlibrary{\idxcode{operator\shr}!\idxcode{basic_istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& operator>>
    (basic_istream<charT,traits>& (*pf)(basic_istream<charT,traits>&))
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
None.
This extractor does not behave as a formatted input function
(as described in~\ref{istream.formatted.reqmts}.)

\pnum
\returns
\tcode{pf(*this)}.\footnote{See, for example, the function signature
\tcode{ws(basic_istream\&)}~(\ref{istream.manip}).%
\indexlibrary{\idxcode{ws}}}
\end{itemdescr}

\indexlibrary{\idxcode{operator\shr}!\idxcode{istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& operator>>
    (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{pf(*this)}.
This extractor does not behave as a formatted input function
(as described in~\ref{istream.formatted.reqmts}).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator\shr}!\idxcode{istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& operator>>
    (ios_base& (*pf)(ios_base&));
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{pf(*this)}.\footnote{See, for example, the function signature
\tcode{dec(ios_base\&)}~(\ref{basefield.manip}).}
This extractor does not behave as a formatted input function
(as described in~\ref{istream.formatted.reqmts}).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator\shr}!\idxcode{istream}}%
\begin{itemdecl}
template<class charT, class traits>
  basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>& in,
                                          charT* s);
template<class traits>
  basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
                                         unsigned char* s);
template<class traits>
  basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
                                         signed char* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves like a formatted input member (as described in~\ref{istream.formatted.reqmts})
of \tcode{in}.
After a
\tcode{sentry}
object is constructed,
\tcode{operator\shr}
extracts characters and stores them into
successive locations of an array whose first element is designated by
\tcode{s}.
If
\tcode{width()}
is greater than zero, \tcode{n} is
\tcode{width()}.
Otherwise \tcode{n} is the number of elements
of the largest array of
\tcode{char_type}
that can store a terminating
\tcode{charT()}.
\tcode{n} is the maximum number of characters stored.

\pnum
Characters are extracted and stored until any of the following occurs:
\begin{itemize}
\item
\tcode{n-1}
characters are stored;
\item
end of file occurs on the input sequence;
\item
\tcode{ct.is(ct.space,c)}
is
\tcode{true}
for the next available input character \tcode{c},
where \tcode{ct} is
\tcode{use_facet<ctype<\brk{}charT> >(in.getloc())}.
\end{itemize}

\pnum
\tcode{operator\shr}
then stores a null byte
(\tcode{charT()})
in the next position, which may be the first position if no characters
were extracted.
\tcode{operator\shr}
then calls
\tcode{width(0)}.

\pnum
If the function extracted no characters, it calls
\tcode{setstate(failbit)},
which may throw
\tcode{ios_base::\brk{}failure}~(\ref{iostate.flags}).

\pnum
\returns
\tcode{in}.
\end{itemdescr}

\indexlibrary{\idxcode{operator\shr}!\idxcode{istream}}%
\begin{itemdecl}
template<class charT, class traits>
  basic_istream<charT,traits>& operator>>(basic_istream<charT,traits>& in,
                                          charT& c);
template<class traits>
  basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
                                         unsigned char& c);
template<class traits>
  basic_istream<char,traits>& operator>>(basic_istream<char,traits>& in,
                                         signed char& c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves like a formatted input member (as described in~\ref{istream.formatted.reqmts})
of \tcode{in}.
After a
\tcode{sentry}
object is constructed
a character is extracted from \tcode{in}, if one is available, and stored in \tcode{c}.
Otherwise, the function calls
\tcode{in.setstate(fail\-bit)}.

\pnum
\returns
\tcode{in}.
\end{itemdescr}

\indexlibrary{\idxcode{operator\shr}!\idxcode{istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& operator>>
  (basic_streambuf<charT,traits>* sb);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described
in~\ref{istream.unformatted}, paragraph 1).
If \tcode{sb} is null, calls
\tcode{setstate(fail\-bit)},
which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags}).
After a sentry object is constructed, extracts
characters from
\tcode{*this}
and inserts them in the output sequence controlled by \tcode{sb}.
Characters are extracted and inserted until any of the following occurs:
\begin{itemize}
\item
end-of-file occurs on the input sequence;
\item
inserting in the output sequence fails
(in which case the character to be inserted is not extracted);
\item
an exception occurs (in which case the exception is caught).
\end{itemize}

\pnum
If the function inserts no characters, it calls
\tcode{setstate(failbit)},
which may throw
\tcode{ios_base::\brk{}failure}~(\ref{iostate.flags}).
If it inserted no characters because it caught
an exception thrown while extracting characters from
\tcode{*this}
and
\tcode{failbit}
is on in
\tcode{exceptions()}~(\ref{iostate.flags}),
then the caught exception is rethrown.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\rSec3[istream.unformatted]{Unformatted input functions}

\pnum
Each unformatted input function begins execution by constructing an object of class
\tcode{sentry}
with the default argument
\tcode{noskipws}
(second) argument
\tcode{true}.
If the
\tcode{sentry}
object returns
\tcode{true},
when converted to a value of type
\tcode{bool},
the function endeavors
to obtain the requested input.
Otherwise, if the sentry constructor exits by throwing an exception or if
the sentry object returns false, when converted to a value of type
\tcode{bool},
the function returns without attempting to obtain any input.
In either case the number of extracted characters is set to 0;
unformatted input functions taking a character array of non-zero size as
an argument shall also store a null character (using
\tcode{charT()})
in the first location of the array.
If an exception is thrown during input then
\tcode{ios::badbit}
is turned on\footnote{This is done without causing an
\tcode{ios::failure}
to be thrown.}
in
\tcode{*this}'s
error state.
(Exceptions thrown from
\tcode{basic_ios<>::clear()}
are not caught or rethrown.)
If
\tcode{(exceptions()\&badbit) != 0}
then the exception is rethrown.
It also counts the number of characters extracted.
If no exception has been thrown it ends
by storing the count in a member object
and returning the value specified.
In any event the
\tcode{sentry}
object
is destroyed before leaving the unformatted input function.

\indexlibrary{\idxcode{gcount}!\idxcode{basic_istream}}%
\begin{itemdecl}
streamsize gcount() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
None.
This member function does not behave as an unformatted
input function (as described in~\ref{istream.unformatted}, paragraph 1).

\pnum
\returns
The number of characters
extracted by the last unformatted input member function called for the object.
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{basic_istream}}%
\begin{itemdecl}
int_type get();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function
(as described in~\ref{istream.unformatted}, paragraph 1).
After constructing a sentry object, extracts
a character \tcode{c}, if one is available.
Otherwise, the function calls
\tcode{setstate(failbit)},
which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags}),

\pnum
\returns
\tcode{c} if available,
otherwise
\tcode{traits::eof()}.
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{get}}%
\begin{itemdecl}
basic_istream<charT,traits>& get(char_type& c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function
(as described in~\ref{istream.unformatted}, paragraph 1).
After constructing a sentry object, extracts
a character, if one is available, and assigns it to \tcode{c}.\footnote{Note
that this function is not overloaded on types
\tcode{signed char}
and
\tcode{unsigned char}.}
Otherwise, the function calls
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{get}}%
\begin{itemdecl}
basic_istream<charT,traits>& get(char_type* s, streamsize n,
                  char_type delim );
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function
(as described in~\ref{istream.unformatted}, paragraph 1).
After constructing a sentry object, extracts
characters and stores them
into successive locations of an array whose first element is designated by
\tcode{s}.\footnote{Note that this function is not overloaded on types
\tcode{signed char}
and
\tcode{unsigned char}.}
Characters are extracted and stored until any of the following occurs:
\begin{itemize}
\item
\tcode{n} is less than one or \tcode{n - 1}
characters are stored;
\item
end-of-file occurs on the input sequence
(in which case the function calls
\tcode{setstate(eofbit)});
\item
\tcode{traits::eq(c, delim)}
for the next available input
character \tcode{c}
(in which case \tcode{c} is not extracted).
\end{itemize}

\pnum
If the function stores no characters, it calls
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::\brk{}failure}~(\ref{iostate.flags})).
In any case, if \tcode{n} is greater than zero it then stores a null character
into the next successive location of the array.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{get}}%
\begin{itemdecl}
basic_istream<charT,traits>& get(char_type* s, streamsize n)
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{get(s,n,widen('\textbackslash n'))}

\pnum
\returns
Value returned by the call.
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{get}}%
\begin{itemdecl}
basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb,
                  char_type delim );
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function
(as described in~\ref{istream.unformatted}, paragraph 1).
After constructing a sentry object, extracts
characters and inserts them
in the output sequence controlled by
\tcode{sb}.
Characters are extracted and inserted until any of the following occurs:
\begin{itemize}
\item
end-of-file occurs on the input sequence;
\item
inserting in the output sequence fails
(in which case the character to be inserted is not extracted);
\item
\tcode{traits::eq(c, delim)} for the next available input
character \tcode{c}
(in which case \tcode{c} is not extracted);
\item
an exception occurs
(in which case, the exception is caught but not rethrown).
\end{itemize}

\pnum
If the function inserts no characters, it calls
\tcode{setstate(failbit)},
which may throw
\tcode{ios_base::\brk{}failure}~(\ref{iostate.flags}).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{get}}%
\begin{itemdecl}
basic_istream<charT,traits>& get(basic_streambuf<char_type,traits>& sb);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{get(sb, widen('\textbackslash n'))}

\pnum
\returns
Value returned by the call.
\end{itemdescr}

\indexlibrary{\idxcode{getline}!\idxcode{basic_istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& getline(char_type* s, streamsize n,
                      char_type delim);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function
(as described in~\ref{istream.unformatted}, paragraph 1).
After constructing a sentry object, extracts
characters and stores them
into successive locations of an array whose first element is designated by
\tcode{s}.\footnote{Note that this function is not overloaded on types
\tcode{signed char}
and
\tcode{unsigned char}.}
Characters are extracted and stored until one of the following occurs:
\begin{enumerate}
\item
end-of-file occurs on the input sequence
(in which case the function calls
\tcode{setstate(eofbit)});
\item
\tcode{traits::eq(c, delim)}
for the next available input
character \tcode{c}
(in which case the input character is extracted but not stored);\footnote{Since
the final input character is ``extracted,''
it is counted in the
\tcode{gcount()},
even though it is not stored.}
\item
\tcode{n} is less than one or \tcode{n - 1}
characters are stored
(in which case the function calls
\tcode{setstate(\brk{}failbit)}).
\end{enumerate}

\pnum
These conditions are tested in the order shown.\footnote{This allows an input
line which exactly fills the buffer, without setting
\tcode{failbit}.
This is different behavior than the historical AT\&T implementation.}

\pnum
If the function extracts no characters, it calls
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::\brk{}failure}~(\ref{iostate.flags})).\footnote{This implies an
empty input line will not cause
\tcode{failbit}
to be set.}

\pnum
In any case, if \tcode{n} is greater than zero, it then stores a null character
(using
\tcode{charT()})
into the next successive location of the array.

\pnum
\returns
\tcode{*this}.

\pnum
\enterexample
\begin{codeblock}
#include <iostream>

int main() {
  using namespace std;
  const int line_buffer_size = 100;

  char buffer[line_buffer_size];
  int line_number = 0;
  while (cin.getline(buffer, line_buffer_size, '@\textbackslash@n') || cin.gcount()) {
    int count = cin.gcount();
    if (cin.eof())
      cout << "Partial final line";   // \tcode{cin.fail()} is false
    else if (cin.fail()) {
      cout << "Partial long line";
      cin.clear(cin.rdstate() & ~ios_base::failbit);
    } else {
      count--;                        // Don't include newline in \tcode{count}
      cout << "Line " << ++line_number;
    }
    cout << " (" << count << " chars): " << buffer << endl;
  }
}
\end{codeblock}
\exitexample
\end{itemdescr}

\indexlibrary{\idxcode{getline}!\idxcode{basic_istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& getline(char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{getline(s,n,widen('\textbackslash n'))}
\end{itemdescr}

\indexlibrary{\idxcode{ignore}!\idxcode{basic_istream}}%
\begin{itemdecl}
basic_istream<charT,traits>&
    ignore(streamsize n = 1, int_type delim = traits::eof());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function
(as described in~\ref{istream.unformatted}, paragraph 1).
After constructing a sentry object, extracts
characters and discards them.
Characters are extracted until any of the following occurs:
\begin{itemize}
\item
\tcode{n != numeric_limits<streamsize>::max()}~(\ref{limits})
and
\tcode{n} characters have been extracted so far
\item
end-of-file occurs on the input sequence
(in which case the function calls
\tcode{setstate(eofbit)},
which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags}));
\item
\tcode{traits::eq_int_type(traits::to_int_type(c), delim)}
for the next available input character \tcode{c}
(in which case \tcode{c} is extracted).
\end{itemize}

\pnum
\notes
The last condition will never occur if
\tcode{traits::eq_int_type(delim, traits::eof())}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{peek}!\idxcode{basic_istream}}%
\begin{itemdecl}
int_type peek();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function
(as described in~\ref{istream.unformatted}, paragraph 1).
After constructing a sentry object, reads but does not extract
the current input character.

\pnum
\returns
\tcode{traits::eof()}
if
\tcode{good()}
is
\tcode{false}.
Otherwise, returns
\tcode{rdbuf()->sgetc()}.
\end{itemdescr}

\indexlibrary{\idxcode{read}!\idxcode{basic_istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& read(char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted}, paragraph 1).
After constructing
a sentry object, if
\tcode{!good()}
calls
\tcode{setstate(failbit)}
which may throw an exception,
and return.
Otherwise extracts characters and stores them
into successive locations of an array whose first element is designated by
\tcode{s}.\footnote{Note that this function is not overloaded on types
\tcode{signed char}
and
\tcode{unsigned char}.}
Characters are extracted and stored until either of the following occurs:
\begin{itemize}
\item
\tcode{n} characters are stored;
\item
end-of-file occurs on the input sequence
(in which case the function calls
\tcode{setstate(failbit | eofbit)},
which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).
\end{itemize}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{readsome}!\idxcode{basic_istream}}%
\begin{itemdecl}
streamsize readsome(char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted}, paragraph 1).
After constructing
a sentry object, if
\tcode{!good()}
calls
\tcode{setstate(failbit)}
which may throw an exception,
and return.
Otherwise extracts characters and stores them
into successive locations of an array whose first element is designated by
\tcode{s}.
If
\tcode{rdbuf()->in_avail() == -1},
calls
\tcode{setstate(eofbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})),
and extracts no characters;
\begin{itemize}
\item
If
\tcode{rdbuf()->in_avail() == 0},
extracts no characters
\item
If
\tcode{rdbuf()->in_avail() > 0},
extracts
\tcode{min(rdbuf()->in_avail(),n))}.
\end{itemize}

\pnum
\returns
The number of characters extracted.
\end{itemdescr}

\indexlibrary{\idxcode{putback}!\idxcode{basic_istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& putback(char_type c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted}, paragraph
1), except that the function first clears \tcode{eofbit}.
After constructing
a sentry object, if
\tcode{!good()}
calls
\tcode{setstate(failbit)}
which may throw an exception,
and return.
If
\tcode{rdbuf()}
is not null, calls
\tcode{rdbuf->sputbackc()}.
If
\tcode{rdbuf()}
is null, or if
\tcode{sputbackc()}
returns
\tcode{traits::eof()},
calls
\tcode{setstate(badbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).
\enternote
This
function extracts no characters, so the value returned by the next call to
\tcode{gcount()}
is 0.
\exitnote

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{unget}!\idxcode{basic_istream}}%
\begin{itemdecl}
basic_istream<charT,traits>& unget();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted}, paragraph
1), except that the function first clears \tcode{eofbit}.
After constructing
a sentry object, if
\tcode{!good()}
calls
\tcode{setstate(failbit)}
which may throw an exception,
and return.
If
\tcode{rdbuf()}
is not null, calls
\tcode{rdbuf()->sungetc()}.
If
\tcode{rdbuf()}
is null, or if
\tcode{sungetc()}
returns
\tcode{traits::eof()},
calls
\tcode{setstate(badbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).
\enternote
This
function extracts no characters, so the value returned by the next call to
\tcode{gcount()}
is 0.
\exitnote

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{sync}!\idxcode{basic_istream}}%
\begin{itemdecl}
int sync();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted}, paragraph 1), except that it does not
count the number of characters extracted and does not affect the
value returned by subsequent calls to
\tcode{gcount()}.
After constructing
a sentry object, if
\tcode{rdbuf()}
is a null pointer, returns -1 .
Otherwise, calls
\tcode{rdbuf()->pubsync()}
and, if that function returns -1
calls
\tcode{setstate(badbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags}),
and returns
\tcode{-1}.
Otherwise, returns zero.
\end{itemdescr}

\indexlibrary{\idxcode{tellg}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{tellg}}%
\begin{itemdecl}
pos_type tellg();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted}, paragraph 1), except that it does not count
the number of characters extracted and does not affect the value
returned by subsequent calls to
\tcode{gcount()}.

\pnum
\returns
After constructing a sentry object, if
\tcode{fail() != false},
returns
\tcode{pos_type(-1)}
to indicate failure.
Otherwise, returns
\tcode{rdbuf()->pubseekoff(0, cur, in)}.
\end{itemdescr}

\indexlibrary{\idxcode{seekg}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{seekg}}%
\begin{itemdecl}
basic_istream<charT,traits>& seekg(pos_type pos);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted}, paragraph 1), except that
the function first clears \tcode{eofbit},
it does not count
the number of characters extracted, and it does not affect the value
returned by subsequent calls to
\tcode{gcount()}.
After constructing a sentry object, if
\tcode{fail() != true},
executes
\tcode{rdbuf()->pubseekpos(pos, ios_base::in)}.
In case of failure, the function calls
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::failure}).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{get}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{get}}%
\begin{itemdecl}
basic_istream<charT,traits>& seekg(off_type off, ios_base::seekdir dir);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted}, paragraph
1), except that it does not count
the number of characters extracted and does not affect the value
returned by subsequent calls to
\tcode{gcount()}.
After constructing a sentry object, if
\tcode{fail() != true},
executes
\tcode{rdbuf()->pubseekoff(off, dir, ios_base::in)}.
In case of failure, the function calls \tcode{setstate(\brk{}failbit)} (which may throw
\tcode{ios_base::failure}).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\rSec3[istream.manip]{Standard \tcode{basic_istream} manipulators}

\indexlibrary{\idxcode{ws}}%
\begin{itemdecl}
namespace std {
  template <class charT, class traits>
    basic_istream<charT,traits>& ws(basic_istream<charT,traits>& is);
}
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted input function (as described in~\ref{istream.unformatted},
paragraph 1), except that it does not count the number of characters extracted and
does not affect the value returned by subsequent calls to is.gcount(). After
constructing a sentry object extracts characters as long as the next available
character \tcode{c} is whitespace or until there are no more characters in the sequence.
Whitespace characters are distinguished with the same criterion as used by
\tcode{sentry::sentry}~(\ref{istream::sentry}).
If
\tcode{ws}
stops extracting characters because there are no more available it sets
\tcode{eofbit},
but not
\tcode{failbit}.

\pnum
\returns
\tcode{is}.
\end{itemdescr}

\rSec3[iostreamclass]{Class template \tcode{basic_iostream}}

\indexlibrary{\idxcode{basic_iostream}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_iostream :
    public basic_istream<charT,traits>,
    public basic_ostream<charT,traits> {
  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;

    // constructor/destructor
    explicit basic_iostream(basic_streambuf<charT,traits>* sb);
    virtual ~basic_iostream();

  protected:
    basic_iostream(const basic_iostream& rhs) = delete;
    basic_iostream(basic_iostream&& rhs);

    // assign/swap
    basic_iostream& operator=(const basic_iostream& rhs) = delete;
    basic_iostream& operator=(basic_iostream&& rhs);
    void swap(basic_iostream& rhs);
  };
}
\end{codeblock}

\pnum
The class
\tcode{basic_iostream}
inherits a number of functions that allow reading input and writing output to
sequences controlled by a stream buffer.
\indexlibrary{\idxcode{basic_iostream}!\idxcode{basic_iostream}}%

\rSec4[iostream.cons]{\tcode{basic_iostream} constructors}

\indexlibrary{\idxcode{basic_iostream}!constructor}%
\begin{itemdecl}
explicit basic_iostream(basic_streambuf<charT,traits>* sb);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_iostream},
assigning initial values to the base classes by calling
\tcode{basic_istream<charT,traits>(sb)}~(\ref{istream})
and
\tcode{basic_ostream<charT,traits>(sb)} (\ref{ostream})

\pnum
\postcondition
\tcode{rdbuf()==sb}
and
\tcode{gcount()==0}.
\indexlibrary{\idxcode{basic_iostream}!destructor}%
\end{itemdescr}

\indexlibrary{\idxcode{basic_iostream}!constructor}%
\begin{itemdecl}
basic_iostream(basic_iostream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs} by
constructing the \tcode{basic_istream} base class with
\tcode{move(rhs)}.
\end{itemdescr}

\rSec4[iostream.dest]{\tcode{basic_iostream} destructor}

\indexlibrary{\idxcode{basic_iostream}!destructor}%
\begin{itemdecl}
virtual ~basic_iostream();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys an object of class
\tcode{basic_iostream}.

\pnum
\notes
Does not perform any operations on
\tcode{rdbuf()}.
\end{itemdescr}

\rSec4[iostream.assign]{\tcode{basic_iostream} assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_iostream}}%
\indexlibrary{\idxcode{basic_iostream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_iostream& operator=(basic_iostream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{swap(rhs)}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_iostream}}%
\indexlibrary{\idxcode{basic_iostream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_iostream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{basic_istream<charT, traits>::swap(rhs)}.
\end{itemdescr}

\rSec3[istream.rvalue]{Rvalue stream extraction}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_istream}}%
\indexlibrary{\idxcode{basic_istream}!\idxcode{operator\shl}}%
\begin{itemdecl}
template <class charT, class traits, class T>
  basic_istream<charT, traits>&
  operator>>(basic_istream<charT, traits>&& is, T& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{is \shr x}

\pnum
\returns \tcode{is}
\end{itemdescr}


\rSec2[output.streams]{Output streams}

\pnum
The header
\tcode{<ostream>}
defines a type
and several function signatures that control output to a
stream buffer along with a function template that inserts into stream rvalues.

\rSec3[ostream]{Class template \tcode{basic_ostream}}
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_ostream : virtual public basic_ios<charT,traits> {
  public:
    // types (inherited from \tcode{basic_ios} (\ref{ios})):
    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;

    // \ref{ostream.cons} Constructor/destructor:
    explicit basic_ostream(basic_streambuf<char_type,traits>* sb);
    virtual ~basic_ostream();

    // \ref{ostream::sentry} Prefix/suffix:
    class sentry;

    // \ref{ostream.formatted} Formatted output:
    basic_ostream<charT,traits>& operator<<(
      basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&));
    basic_ostream<charT,traits>& operator<<(
      basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&));
    basic_ostream<charT,traits>& operator<<(
      ios_base& (*pf)(ios_base&));

    basic_ostream<charT,traits>& operator<<(bool n);
    basic_ostream<charT,traits>& operator<<(short n);
    basic_ostream<charT,traits>& operator<<(unsigned short n);
    basic_ostream<charT,traits>& operator<<(int n);
    basic_ostream<charT,traits>& operator<<(unsigned int n);
    basic_ostream<charT,traits>& operator<<(long n);
    basic_ostream<charT,traits>& operator<<(unsigned long n);
    basic_ostream<charT,traits>& operator<<(long long n);
    basic_ostream<charT,traits>& operator<<(unsigned long long n);
    basic_ostream<charT,traits>& operator<<(float f);
    basic_ostream<charT,traits>& operator<<(double f);
    basic_ostream<charT,traits>& operator<<(long double f);

    basic_ostream<charT,traits>& operator<<(const void* p);
    basic_ostream<charT,traits>& operator<<(
      basic_streambuf<char_type,traits>* sb);

    // \ref{ostream.unformatted} Unformatted output:
    basic_ostream<charT,traits>& put(char_type c);
    basic_ostream<charT,traits>& write(const char_type* s, streamsize n);

    basic_ostream<charT,traits>& flush();

    // \ref{ostream.seeks} seeks:
    pos_type tellp();
    basic_ostream<charT,traits>& seekp(pos_type);
    basic_ostream<charT,traits>& seekp(off_type, ios_base::seekdir);
  protected:
    basic_ostream(const basic_ostream& rhs) = delete;
    basic_ostream(basic_ostream&& rhs);

    // \ref{ostream.assign} Assign/swap
    basic_ostream& operator=(const basic_ostream& rhs) = delete;
    basic_ostream& operator=(basic_ostream&& rhs);
    void swap(basic_ostream& rhs);
  };

  // \ref{ostream.inserters.character} character inserters
  template<class charT, class traits>
    basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
                                            charT);
  template<class charT, class traits>
    basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
                                            char);
  template<class traits>
    basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
                                           char);

  // signed and unsigned
  template<class traits>
    basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
                                           signed char);
  template<class traits>
    basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
                                           unsigned char);

  template<class charT, class traits>
    basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
                                            const charT*);
  template<class charT, class traits>
    basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&,
                                            const char*);
  template<class traits>
    basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
                                           const char*);

  // signed and unsigned
  template<class traits>
    basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
                                           const signed char*);
  template<class traits>
    basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>&,
                                           const unsigned char*);
}
\end{codeblock}

\pnum
The class
\tcode{basic_ostream}
defines a number of member function
signatures that assist in formatting and writing output to output sequences
controlled by a stream buffer.

\pnum
Two groups of member function signatures share common properties:
the
\term{formatted output functions}
(or
\term{inserters})
and the
\term{unformatted output functions.}
Both groups of output functions generate (or
\term{insert})
output
\term{characters}
by actions equivalent to calling
\tcode{rdbuf()->sputc(int_type)}.
They may use other public members of
\tcode{basic_ostream}
except that they shall not invoke any virtual members of
\tcode{rdbuf()}
except
\tcode{overflow()},
\tcode{xsputn()},
and
\tcode{sync()}.

\pnum
If one of these called functions throws an exception, then unless explicitly noted otherwise
the output function sets
\tcode{badbit}
in error state.
If
\tcode{badbit}
is on in
\tcode{exceptions()},
the output function
rethrows the exception without completing its actions, otherwise
it does not throw anything and treat as an error.

\rSec3[ostream.cons]{\tcode{basic_ostream} constructors}

\indexlibrary{\idxcode{basic_ostream}!\idxcode{basic_ostream}}%
\begin{itemdecl}
explicit basic_ostream(basic_streambuf<charT,traits>* sb);
\end{itemdecl}

\indexlibrary{\idxcode{init}!\idxcode{basic_ios}}%
\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ostream},
assigning initial values to the base class by calling
\tcode{basic_ios<charT,traits>::init(sb)}~(\ref{basic.ios.cons}).

\pnum
\postcondition
\tcode{rdbuf() == sb}.

\indexlibrary{\idxcode{basic_ostream}!destructor}%
\begin{itemdecl}
virtual ~basic_ostream();
\end{itemdecl}

\pnum
\effects
Destroys an object of class
\tcode{basic_ostream}.

\pnum
\notes
Does not perform any operations on
\tcode{rdbuf()}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_ostream}!constructor}%
\begin{itemdecl}
basic_ostream(basic_ostream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}.
This is accomplished by default constructing the base class and calling
\tcode{basic_ios<charT, traits>::move(rhs)} to initialize the
base class.
\end{itemdescr}

\rSec3[ostream.assign]{Class \tcode{basic_ostream} assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_ostream& operator=(basic_ostream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{swap(rhs)}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_ostream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{basic_ios<charT, traits>::swap(rhs)}.
\end{itemdescr}

\rSec3[ostream::sentry]{Class \tcode{basic_ostream::sentry}}

\indexlibrary{\idxcode{sentry}!\idxcode{basic_ostream}}%
\begin{codeblock}
namespace std {
  template <class charT,class traits = char_traits<charT> >
  class basic_ostream<charT,traits>::sentry {
    bool ok_; // \expos
  public:
    explicit sentry(basic_ostream<charT,traits>& os);
    ~sentry();
    explicit operator bool() const { return ok_; }

    sentry(const sentry&) = delete;
    sentry& operator=(const sentry&) = delete;
  };
}
\end{codeblock}

\pnum
The class
\tcode{sentry}
defines a class that is responsible for doing exception safe prefix and suffix
operations.

\indexlibrary{\idxcode{sentry}!constructor}%
\begin{itemdecl}
explicit sentry(basic_ostream<charT,traits>& os);
\end{itemdecl}

\begin{itemdescr}
\pnum
If
\tcode{os.good()}
is nonzero, prepares for formatted or unformatted output.
If
\tcode{os.tie()}
is not a null pointer, calls
\indexlibrary{\idxcode{flush}}%
\tcode{os.tie()->flush()}.\footnote{The call
\tcode{os.tie()->flush()}
does not necessarily occur if the function can determine that no
synchronization is necessary.}

\pnum
If, after any preparation is completed,
\tcode{os.good()}
is
\tcode{true},
\tcode{ok_ == true}
otherwise,
\tcode{ok_ == false}.
During preparation, the constructor may call
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::\brk{}failure}~(\ref{iostate.flags}))\footnote{The
\tcode{sentry}
constructor and destructor
can also perform additional
implementation-dependent operations.}
\end{itemdescr}

\indexlibrary{\idxcode{basic_ostream}!destructor}%
\begin{itemdecl}
~sentry();
\end{itemdecl}

\begin{itemdescr}
\pnum
If
\tcode{((os.flags() \& ios_base::unitbuf) \&\& !uncaught_exception()
\&\& os.good())}
is
\tcode{true},
calls
\tcode{os.rdbuf()->pubsync()}. If that function returns -1, sets \tcode{badbit} in
\tcode{os.rdstate()} without propagating an exception.
\end{itemdescr}

\indexlibrary{\idxcode{flush}}%
\indexlibrary{\idxcode{operator bool}!\idxcode{basic_ostream}}%
\begin{itemdecl}
explicit operator bool() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Returns
\tcode{ok_}.
\end{itemdescr}

\rSec3[ostream.seeks]{\tcode{basic_ostream} seek members}

\pnum
Each seek member function begins execution by constructing an object of class \tcode{sentry}.
It returns by destroying the \tcode{sentry} object.

\indexlibrary{\idxcode{tellp}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{seekp}!\idxcode{basic_ostream}}%
\begin{itemdecl}
pos_type tellp();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If
\tcode{fail() != false},
returns
\tcode{pos_type(-1)}
to indicate failure.
Otherwise, returns
\tcode{rdbuf()->\brk{}pub\-seek\-off(\brk0, cur, out)}.
\begin{itemdecl}
basic_ostream<charT,traits>& seekp(pos_type pos);
\end{itemdecl}

\pnum
\effects
If
\tcode{fail() != true},
executes
\tcode{rdbuf()->pubseekpos(pos, ios_base::out)}.
In case of failure, the function calls
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::failure}).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{seekp}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{seekp}}%
\begin{itemdecl}
basic_ostream<charT,traits>& seekp(off_type off, ios_base::seekdir dir);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If
\tcode{fail() != true},
executes
\tcode{rdbuf()->pubseekoff(off, dir, ios_base::out)}.
In case of failure, the function calls \tcode{setstate(failbit)}
(which may throw \tcode{ios_base::failure}).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\rSec3[ostream.formatted]{Formatted output functions}

\rSec4[ostream.formatted.reqmts]{Common requirements}

\pnum
Each formatted output function begins execution by constructing an object of class
\tcode{sentry}.
If this object returns
\tcode{true}
when converted to a value of type
\tcode{bool},
the function endeavors
to generate the requested output.
If the generation fails, then the formatted output function does
\tcode{setstate(ios_base::failbit)},
which might throw an exception.
If an exception is thrown during output, then
\tcode{ios::badbit}
is turned on\footnote{without causing an
\tcode{ios::failure}
to be thrown.}
in
\tcode{*this}'s
error state.
If
\tcode{(exceptions()\&badbit) != 0}
then the exception is rethrown.
Whether or not an exception is thrown, the
\tcode{sentry}
object is destroyed before leaving the formatted output function.
If no exception is thrown, the result of the formatted output function
is
\tcode{*this}.

\pnum
The descriptions of the individual formatted output functions
describe how they perform
output and do not mention the
\tcode{sentry}
object.

\pnum
If a formatted output function of a stream \tcode{os} determines
padding, it does so as
follows. Given a \tcode{charT} character sequence \tcode{seq} where
\tcode{charT} is the character type of the stream, if
the length of \tcode{seq} is less than \tcode{os.width()}, then enough copies of
\tcode{os.fill()} are added to this sequence as necessary to pad to a
width of \tcode{os.width()} characters. If
\tcode{(os.flags() \& ios_base::adjustfield) == ios_base::left} is
\tcode{true}, the fill characters are placed
after the character sequence; otherwise, they are placed before the
character sequence.

\rSec4[ostream.inserters.arithmetic]{Arithmetic inserters}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_ostream}}%
\begin{itemdecl}
operator<<(bool val);
operator<<(short val);
operator<<(unsigned short val);
operator<<(int val);
operator<<(unsigned int val);
operator<<(long val);
operator<<(unsigned long val);
operator<<(long long val);
operator<<(unsigned long long val);
operator<<(float val);
operator<<(double val);
operator<<(long double val);
operator<<(const void* val);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The classes
\tcode{num_get<>}
and
\tcode{num_put<>}
handle locale-dependent numeric formatting and
parsing.
These inserter functions use the imbued
\tcode{locale}
value to perform numeric formatting.
When \tcode{val}
is of type
\tcode{bool},
\tcode{long},
\tcode{unsigned long},
\tcode{long long}, \tcode{unsigned long long},
\tcode{double},
\tcode{long double},
or
\tcode{const void*},
the formatting conversion occurs as if it performed the following code fragment:
\begin{codeblock}
bool failed = use_facet<
  num_put<charT,ostreambuf_iterator<charT,traits> >
    >(getloc()).put(*this, *this, fill(), val).failed();
\end{codeblock}

When \tcode{val} is of type
\tcode{short}
the formatting conversion occurs as if it performed the following code fragment:
\begin{codeblock}
ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
bool failed = use_facet<
  num_put<charT,ostreambuf_iterator<charT,traits> >
    >(getloc()).put(*this, *this, fill(),
    baseflags == ios_base::oct || baseflags == ios_base::hex
      ? static_cast<long>(static_cast<unsigned short>(val))
      : static_cast<long>(val)).failed();
\end{codeblock}

When \tcode{val} is of type
\tcode{int}
the formatting conversion occurs as if it performed the following code fragment:
\begin{codeblock}
ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
bool failed = use_facet<
  num_put<charT,ostreambuf_iterator<charT,traits> >
    >(getloc()).put(*this, *this, fill(),
    baseflags == ios_base::oct || baseflags == ios_base::hex
      ? static_cast<long>(static_cast<unsigned int>(val))
      : static_cast<long>(val)).failed();
\end{codeblock}

When \tcode{val} is of type
\tcode{unsigned short}
or
\tcode{unsigned int}
the formatting conversion occurs as if it performed the following code fragment:
\begin{codeblock}
bool failed = use_facet<
  num_put<charT,ostreambuf_iterator<charT,traits> >
    >(getloc()).put(*this, *this, fill(),
      static_cast<unsigned long>(val)).failed();
\end{codeblock}

When \tcode{val} is of type
\tcode{float}
the formatting conversion occurs as if it performed the following code fragment:
\begin{codeblock}
bool failed = use_facet<
  num_put<charT,ostreambuf_iterator<charT,traits> >
    >(getloc()).put(*this, *this, fill(),
      static_cast<double>(val)).failed();
\end{codeblock}

\pnum
The first argument provides an object of the
\tcode{ostreambuf_iterator<>}
class which is an iterator for class \tcode{basic_ostream<>}.
It bypasses
\tcode{ostream}s
and uses
\tcode{streambuf}s
directly.
Class
\tcode{locale}
relies on these types as its
interface to iostreams, since for flexibility it has been abstracted
away from direct dependence on
\tcode{ostream}.
The second parameter is a reference to the base subobject of type
\tcode{ios_base}.
It provides formatting specifications such as field width, and
a locale from which to obtain other facets.
If
\tcode{failed}
is
\tcode{true}
then does
\tcode{setstate(badbit)},
which may throw an exception, and returns.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\rSec4[ostream.inserters]{\tcode{basic_ostream::operator\shl}}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_ostream}}%
\begin{itemdecl}
basic_ostream<charT,traits>& operator<<
    (basic_ostream<charT,traits>& (*pf)(basic_ostream<charT,traits>&))
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
None.
Does not behave as a formatted output function (as described
in~\ref{ostream.formatted.reqmts}).

\pnum
\returns
\tcode{pf(*this)}.\footnote{See, for example, the function signature
\indexlibrary{\idxcode{endl}}%
\tcode{endl(basic_ostream\&)}~(\ref{ostream.manip}).}
\end{itemdescr}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{operator\shl}}%
\begin{itemdecl}
basic_ostream<charT,traits>& operator<<
    (basic_ios<charT,traits>& (*pf)(basic_ios<charT,traits>&))
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{pf(*this)}.
This inserter does not
behave as a formatted output function (as described in~\ref{ostream.formatted.reqmts}).

\pnum
\returns
\tcode{*this}.\footnote{See, for example, the function signature
\indexlibrary{\idxcode{dec}}%
\tcode{dec(ios_base\&)}~(\ref{basefield.manip}).}
\end{itemdescr}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{operator\shl}}%
\begin{itemdecl}
basic_ostream<charT,traits>& operator<<
    (ios_base& (*pf)(ios_base&))
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{pf(*this)}.
This inserter does not
behave as a formatted output function (as described in~\ref{ostream.formatted.reqmts}).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{operator\shl}}%
\begin{itemdecl}
basic_ostream<charT,traits>& operator<<
    (basic_streambuf<charT,traits>* sb);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted output function (as described in~\ref{ostream.unformatted}, paragraph 1).
After the sentry object is
constructed, if
\tcode{sb} is null calls
\tcode{setstate(badbit)}
(which may throw
\tcode{ios_base::failure}).

\pnum
Gets characters from \tcode{sb}
and inserts them in
\tcode{*this}.
Characters are read from \tcode{sb}
and inserted until any of the following occurs:
\begin{itemize}
\item
end-of-file occurs on the input sequence;
\item
inserting in the output sequence fails
(in which case the character to be inserted is not extracted);
\item
an exception occurs while getting a character from \tcode{sb}.
\end{itemize}

\pnum
If the function inserts no characters, it calls
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::\brk{}failure}~(\ref{iostate.flags})).
If an exception was thrown while extracting a character,
the function sets
\tcode{failbit}
in error state, and if
\tcode{failbit}
is on in
\tcode{exceptions()}
the caught exception is rethrown.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\rSec4[ostream.inserters.character]{Character inserter function templates}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{operator\shl}}%
\begin{itemdecl}
template<class charT, class traits>
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
                                          charT c);
template<class charT, class traits>
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
                                          char c);
  // specialization
template<class traits>
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
                                         char c);
  // signed and unsigned
template<class traits>
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
                                         signed char c);
template<class traits>
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
                                         unsigned char c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as a formatted output function
(~\ref{ostream.formatted.reqmts}) of \tcode{out}. 
Constructs a character sequence \tcode{seq}. 
If \tcode{c} has type
\tcode{char}
and the character type of the stream is not
\tcode{char},
then \tcode{seq} consists of
\tcode{out.widen(c)};
otherwise \tcode{seq} consists of
\tcode{c}. Determines padding for \tcode{seq} as described
in~\ref{ostream.formatted.reqmts}. Inserts \tcode{seq} into
\tcode{out}. Calls \tcode{os.width(0)}.

\pnum
\returns
\tcode{out}.
\end{itemdescr}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{operator\shl}}%
\begin{itemdecl}
template<class charT, class traits>
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
                                          const charT* s);
template<class charT, class traits>
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
                                          const char* s);
template<class traits>
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
                                         const char* s);
template<class traits>
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
                                         const signed char* s);
template<class traits>
  basic_ostream<char,traits>& operator<<(basic_ostream<char,traits>& out,
                                         const unsigned char* s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires
\tcode{s} shall not be a null pointer.

\pnum
\effects
Behaves like a formatted inserter (as described in~\ref{ostream.formatted.reqmts}) of \tcode{out}.
Creates a character sequence \tcode{seq} of \tcode{n} characters
starting at \tcode{s}, each widened using
\tcode{out.widen()}~(\ref{basic.ios.members}),
where \tcode{n} is the number that would be computed as if by:
\begin{itemize}
\item
\tcode{traits::length(s)}
for the overload where the first argument is of type
\tcode{basic_ostream<charT, traits>\&}
and the second is of type
\tcode{const charT*},
and also for the overload where the first argument is of type
\tcode{basic_ostream<char, traits>\&}
and the second is of type
\tcode{const char*},
\item
\tcode{std::char_traits<char>::length(s)}
for the overload where the first argument is of type
\tcode{basic_ostream<\brk{}charT, traits>\&}
and the second is of type
\tcode{const char*},
\item
\tcode{traits::length(reinterpret_cast<const char*>(s))}
for the other two overloads.
\end{itemize}
Determines padding for \tcode{seq} as described
in~\ref{ostream.formatted.reqmts}. Inserts \tcode{seq} into
\tcode{out}. Calls \tcode{width(0)}.

\pnum
\returns
\tcode{out}.
\end{itemdescr}

\rSec3[ostream.unformatted]{Unformatted output functions}

\pnum
Each
unformatted
output function begins execution by constructing an object of class
\tcode{sentry}.
If this object returns
\tcode{true},
while converting to a value of type
\tcode{bool},
the function endeavors
to generate the requested output.
If an exception is thrown during output, then
\tcode{ios::badbit}
% .Fs new
is turned on\footnote{without causing an
\tcode{ios::failure}
to be thrown.}
in
\tcode{*this}'s
error state.
If
\tcode{(exceptions() \& badbit) != 0}
then the exception is rethrown.
In any case, the unformatted output function ends by destroying the
sentry object, then, if no exception was thrown, returning the value
specified for the unformatted output function.

\indexlibrary{\idxcode{put}!\idxcode{basic_ostream}}%
\begin{itemdecl}
basic_ostream<charT,traits>& put(char_type c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted output function (as described in~\ref{ostream.unformatted}, paragraph 1).
After constructing a sentry
object, inserts
the character \tcode{c}, if possible.\footnote{Note that this function is not overloaded on types
\tcode{signed char}
and
\tcode{unsigned char}.}

\pnum
Otherwise, calls
\tcode{setstate(badbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{write}!\idxcode{basic_ostream}}%
\begin{itemdecl}
basic_ostream& write(const char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves as an unformatted output function (as described in~\ref{ostream.unformatted}, paragraph 1).  After constructing a sentry
object, obtains
characters to insert from
successive locations of an array whose first element is designated by
\tcode{s}.\footnote{Note that this function is not overloaded on types
\tcode{signed char}
and
\tcode{unsigned char}.}
Characters are inserted until either of the following occurs:
\begin{itemize}
\item
\tcode{n} characters are inserted;
\item
inserting in the output sequence fails
(in which case the function calls
\tcode{setstate(badbit)},
which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).
\end{itemize}

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{flush}!\idxcode{basic_ostream}}%
\begin{itemdecl}
basic_ostream& flush();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Behaves as an unformatted output function (as described in~\ref{ostream.formatted.reqmts}, paragraph 1).
If
\tcode{rdbuf()}
is not a null pointer,
constructs a sentry object. If this object returns \tcode{true} when converted to a value of type \tcode{bool} the function
calls
\tcode{rdbuf()->pubsync()}.
If that function returns -1
calls
\tcode{setstate(badbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).
Otherwise, if the sentry object returns \tcode{false}, does nothing.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\rSec3[ostream.manip]{Standard \tcode{basic_ostream} manipulators}

\indexlibrary{\idxcode{endl}}%
\begin{itemdecl}
namespace std {
  template <class charT, class traits>
    basic_ostream<charT,traits>& endl(basic_ostream<charT,traits>& os);
}
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{os.put(os.widen('\textbackslash n'))},
then
\tcode{os.flush()}.

\pnum
\returns
\tcode{os}.
\end{itemdescr}

\indexlibrary{\idxcode{ends}}%
\begin{itemdecl}
namespace std {
  template <class charT, class traits>
    basic_ostream<charT,traits>& ends(basic_ostream<charT,traits>& os);
}
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Inserts a null character into the output sequence:
calls
\tcode{os.put(charT())}.

\pnum
\returns
\tcode{os}.
\end{itemdescr}

\indexlibrary{\idxcode{flush}}%
\begin{itemdecl}
namespace std {
  template <class charT, class traits>
    basic_ostream<charT,traits>& flush(basic_ostream<charT,traits>& os);
}
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{os.flush()}.

\pnum
\returns
\tcode{os}.
\end{itemdescr}

\rSec3[ostream.rvalue]{Rvalue stream insertion}

\indexlibrary{\idxcode{operator\shl}!\idxcode{basic_ostream}}%
\indexlibrary{\idxcode{basic_ostream}!\idxcode{operator\shl}}%
\begin{itemdecl}
template <class charT, class traits, class T>
  basic_ostream<charT, traits>&
  operator<<(basic_ostream<charT, traits>&& os, const T& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{os \shl{} x}

\pnum
\returns \tcode{os}
\end{itemdescr}


\rSec2[std.manip]{Standard manipulators}

\pnum The header \tcode{<iomanip>} defines several functions that support
extractors and inserters that alter information maintained by class
\tcode{ios_base} and its derived classes.

\indexlibrary{\idxcode{resetiosflags}}%
\begin{itemdecl}
@\unspec@ resetiosflags(ios_base::fmtflags mask);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object of
unspecified type such that if \tcode{out} is an object of type
\tcode{basic_ostream<charT, traits>} then the expression \tcode{out \shl\
resetiosflags(mask)} behaves as if it called \tcode{f(out,
mask)}, or if \tcode{in} is an object of type
\tcode{basic_istream<charT, traits>} then the expression \tcode{in \shr\
resetiosflags(\brk{}mask)} behaves as if it called \tcode{f(in,
mask)}, where the function \tcode{f}
is defined as:\footnote{ The expression \tcode{cin \shr resetiosflags(ios_base::skipws)}
clears \tcode{ios_base::skipws} in the format flags stored in the
\tcode{basic_istream<charT,traits>} object \tcode{cin} (the same as
\tcode{cin \shr noskipws}), and the expression \tcode{cout \shl
resetiosflags(ios_base::showbase)} clears \tcode{ios_base::showbase} in the
format flags stored in the \tcode{basic_ostream<charT,traits>} object
\tcode{cout} (the same as \tcode{cout \shl noshowbase}). }

\begin{codeblock}
void f(ios_base& str, ios_base::fmtflags mask) {
  // reset specified flags
  str.setf(ios_base::fmtflags(0), mask);
}
\end{codeblock}

The expression \tcode{out \shl\ resetiosflags(mask)} shall have
type \tcode{basic_ostream<charT,traits>\&} and value \tcode{out}. The
expression \tcode{in \shr\ resetiosflags(mask)} shall have type
\tcode{basic_istream<charT, traits>\&} and value \tcode{in}. \end{itemdescr}

\indexlibrary{\idxcode{setiosflags}}%
\begin{itemdecl}
@\unspec@ setiosflags(ios_base::fmtflags mask);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An object of unspecified type such that if
\tcode{out}
is an object of type
\tcode{basic_ostream<charT, traits>}
then the expression
\tcode{out \shl\ setiosflags(mask)}
behaves as if it called
\tcode{f(out, mask)},
or if
\tcode{in}
is an object of type
\tcode{basic_istream<charT, traits>}
then the expression
\tcode{in \shr\ setiosflags(mask)}
behaves as if it called
\tcode{f(in, mask)}, where the function \tcode{f} is defined as:
\indexlibrary{\idxcode{fmtflags}!\idxcode{ios}}%

\begin{codeblock}
void f(ios_base& str, ios_base::fmtflags mask) {
  // set specified flags
  str.setf(mask);
}
\end{codeblock}

The expression
\tcode{out \shl\ setiosflags(mask)}
shall have type
\tcode{basic_ostream<charT, traits>\&}
and value
\tcode{out}.
The expression
\tcode{in \shr\ setiosflags(mask)}
shall have type
\tcode{basic_istream<charT, \\traits>\&}
and value
\tcode{in}.
\end{itemdescr}

\indexlibrary{\idxcode{setbase}}%
\begin{itemdecl}
@\unspec@ setbase(int base);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An object of unspecified type such that if
\tcode{out}
is an object of type
\tcode{basic_ostream<charT, traits>}
then the expression
\tcode{out \shl\ setbase(base)}
behaves as if it called
\tcode{f(out, base)},
or if
\tcode{in}
is an object of type
\tcode{basic_istream<charT, traits>}
then the expression
\tcode{in \shr\ setbase(base)}
behaves as if it called
\tcode{f(in, base)}, where the function \tcode{f} is defined as:

\begin{codeblock}
void f(ios_base& str, int base) {
  // set \tcode{basefield}
  str.setf(base ==  8 ? ios_base::oct :
      base == 10 ? ios_base::dec :
      base == 16 ? ios_base::hex :
      ios_base::fmtflags(0), ios_base::basefield);
}
\end{codeblock}

The expression
\tcode{out \shl\ setbase(base)}
shall have type
\tcode{basic_ostream<charT, traits>\&}
and value
\tcode{out}.
The expression
\tcode{in \shr\ setbase(base)}
shall have type
\tcode{basic_istream<charT, traits>\&}
and value
\tcode{in}.
\end{itemdescr}

\indexlibrary{\idxcode{setfill}}%
\begin{itemdecl}
@\unspec@ setfill(char_type c);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An object of unspecified type such that if
\tcode{out}
is an object of type
\tcode{basic_ostream<charT, traits>}
and \tcode{c} has type
\tcode{charT}
then the expression
\tcode{out \shl\ setfill(c)}
behaves as if it called
\tcode{f(out, c)}, where the function \tcode{f} is defined as:

\begin{codeblock}
template<class charT, class traits>
void f(basic_ios<charT,traits>& str, charT c) {
  // set fill character
  str.fill(c);
}
\end{codeblock}

The expression
\tcode{out \shl\ setfill(c)}
shall have type
\tcode{basic_ostream<charT, traits>\&}
and value
\tcode{out}.
\end{itemdescr}

\indexlibrary{\idxcode{setprecision}}%
\begin{itemdecl}
@\unspec@ setprecision(int n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An object of unspecified type such that if
\tcode{out}
is an object of type
\tcode{basic_ostream<charT, traits>}
then the expression
\tcode{out \shl\ setprecision(n)}
behaves as if it called
\tcode{f(out, n)},
or if
\tcode{in}
is an object of type
\tcode{basic_istream<charT, traits>}
then the expression
\tcode{in \shr\ setprecision(n)}
behaves as if it called
\tcode{f(in, n)}, where the function \tcode{f} is defined as:

\begin{codeblock}
void f(ios_base& str, int n) {
  // set precision
  str.precision(n);
}
\end{codeblock}

The expression
\tcode{out \shl\ setprecision(n)}
shall have type
\tcode{basic_ostream<charT, traits>\&}
and value
\tcode{out}.
The expression
\tcode{in \shr\ setprecision(n)}
shall have type
\tcode{basic_istream<charT, traits>\&}
and value
\tcode{in}.
\end{itemdescr}

\indexlibrary{\idxcode{setw}}%
\begin{itemdecl}
@\unspec@ setw(int n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
An object of unspecified type such that if
\tcode{out}
is an instance of
\tcode{basic_ostream<charT, traits>}
then the expression
\tcode{out \shl\ setw(n)}
behaves as if it called
\tcode{f(out, n)},
or if
\tcode{in}
is an object of type
\tcode{basic_istream<charT, traits>}
then the expression
\tcode{in \shr\ setw(n)}
behaves as if it called
\tcode{f(in, n)}, where the function \tcode{f} is defined as:

\begin{codeblock}
void f(ios_base& str, int n) {
  // set width
  str.width(n);
}
\end{codeblock}

The expression
\tcode{out \shl\ setw(n)}
shall have type
\tcode{basic_ostream<charT, traits>\&}
and value
\tcode{out}.
The expression
\tcode{in \shr\ setw(n)}
shall have type
\tcode{basic_istream<charT, traits>\&}
and value
\tcode{in}.
\end{itemdescr}

\rSec2[ext.manip]{Extended manipulators}

\pnum
The header \tcode{<iomanip>} defines several functions that support extractors and inserters that allow for the
parsing and formatting of sequences and values for money and time.

\indexlibrary{\idxcode{get_money}}%
\begin{itemdecl}
template <class moneyT> @\unspec@ get_money(moneyT& mon, bool intl = false);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires The type \tcode{moneyT} shall be either \tcode{long double} or a
specialization of the \tcode{basic_string} template (Clause~\ref{strings}).

\pnum
\effects The expression \tcode{in \shr get_money(mon, intl)} described below
behaves as a formatted input function~(\ref{istream.formatted.reqmts}).

\pnum
\returns An object of unspecified type such that if
\tcode{in} is an object of type \tcode{basic_istream<charT, traits>}
then the expression \tcode{in \shr\ get_money(mon, intl)} behaves as if it called
\tcode{f(in, mon, intl)}, where the function \tcode{f} is defined as:

\begin{codeblock}
template <class charT, class traits, class moneyT>
void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
  typedef istreambuf_iterator<charT, traits> Iter;
  typedef money_get<charT, Iter> MoneyGet;

  ios_base::iostate err = ios_base::goodbit;
  const MoneyGet &mg = use_facet<MoneyGet>(str.getloc());

  mg.get(Iter(str.rdbuf()), Iter(), intl, str, err, mon);

  if (ios_base::goodbit != err)
    str.setstate(err);
}
\end{codeblock}

The expression \tcode{in \shr\ get_money(mon, intl)} shall have type
\tcode{basic_istream<charT, traits>\&} and value \tcode{in}.
\end{itemdescr}

\indexlibrary{\idxcode{put_money}}%
\begin{itemdecl}
template <class moneyT> @\unspec@ put_money(const moneyT& mon, bool intl = false);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires The type \tcode{moneyT} shall be either \tcode{long double} or a
specialization of the \tcode{basic_string} template (Clause~\ref{strings}).

\pnum
\returns An object of unspecified type such that if
\tcode{out} is an object of type \tcode{basic_ostream<charT, traits>}
then the expression \tcode{out \shl\ put_money(mon, intl)} behaves as a formatted input function that calls
\tcode{f(out, mon, intl)}, where the function \tcode{f} is defined as:

\begin{codeblock}
template <class charT, class traits, class moneyT>
void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
  typedef ostreambuf_iterator<charT, traits> Iter;
  typedef money_put<charT, Iter> MoneyPut;

  const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
  const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);

  if (end.failed())
    str.setstate(ios::badbit);
}
\end{codeblock}

The expression \tcode{out \shl\ put_money(mon, intl)} shall have type
\tcode{basic_ostream<charT, traits>\&} and value \tcode{out}.

\end{itemdescr}

\indexlibrary{\idxcode{get_time}}%
\begin{itemdecl}
template <class charT> @\unspec@ get_time(struct tm* tmb, const charT* fmt);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires The argument \tcode{tmb} shall be a valid pointer to an object of type \tcode{struct tm}, and the argument \tcode{fmt} shall be a valid pointer to an array of objects of type \tcode{charT} with \tcode{char_traits<charT>::length(fmt)} elements.

\pnum
\returns An object of unspecified type such that if \tcode{in} is an object of type
\tcode{basic_istream<charT, traits>} then the expression \tcode{in \shr\ get_time(tmb,
fmt)} behaves as if it called \tcode{f(in, tmb, fmt)}, where the function \tcode{f} is
defined as:

\begin{codeblock}
template <class charT, class traits>
void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
  typedef istreambuf_iterator<charT, traits> Iter;
  typedef time_get<charT, Iter> TimeGet;

  ios_base::iostate err = ios_base::goodbit;
  const TimeGet& tg = use_facet<TimeGet>(str.getloc());

  tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb,
    fmt, fmt + traits::length(fmt));

  if (err != ios_base::goodbit)
    str.setstate(err):
}
\end{codeblock}

The expression \tcode{in \shr\ get_time(tmb, fmt)} shall have type
\tcode{basic_istream<charT, traits>\&} and value \tcode{in}.
\end{itemdescr}

\indexlibrary{\idxcode{put_time}}%
\begin{itemdecl}
template <class charT> @\unspec@ put_time(const struct tm* tmb, const charT* fmt);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires The argument \tcode{tmb} shall be a valid pointer to an object of type
\tcode{struct tm}, and the argument \tcode{fmt} shall be a valid pointer to an
array of objects of type \tcode{charT} with
\tcode{char_traits<charT>::length(\brk{}fmt)} elements.

\pnum
\returns An object of unspecified type such that if \tcode{out} is an object of
type \tcode{basic_ostream<charT, traits>} then the expression \tcode{out \shl\
put_time(tmb, fmt)} behaves as if it called \tcode{f(out, tmb, fmt)}, where the
function \tcode{f} is defined as:

\begin{codeblock}
template <class charT, class traits>
void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
  typedef ostreambuf_iterator<charT, traits> Iter;
  typedef time_put<charT, Iter> TimePut;

  const TimePut& tp = use_facet<TimePut>(str.getloc());
  const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
    fmt, fmt + traits::length(fmt));

  if (end.failed())
    str.setstate(ios_base::badbit);
}
\end{codeblock}

The expression \tcode{out \shl\ put_time(tmb, fmt)} shall have type
\tcode{basic_ostream<charT, traits>\&} and value \tcode{out}.
\end{itemdescr}

\rSec2[quoted.manip]{Quoted manipulators}

\pnum
\enternote Quoted manipulators provide string insertion and extraction of quoted strings (for example, XML and CSV formats). Quoted manipulators are useful in ensuring that the content of a string with embedded spaces remains unchanged if inserted and then extracted via stream I/O. \exitnote

\indexlibrary{\idxcode{quoted}}%
\begin{itemdecl}
template <class charT>
  @\unspec@ quoted(const charT* s, charT delim=charT('"'), charT escape=charT('\\'));
template <class charT, class traits, class Allocator>
  @\unspec@ quoted(const basic_string<charT, traits, Allocator>& s,
                      charT delim=charT('"'), charT escape=charT('\\'));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object of unspecified type such that if \tcode{out} is an instance
of \tcode{basic_ostream} with member type \tcode{char_type} the same as
\tcode{charT} and with member type \tcode{traits_type}, which in the second
form is the same as \tcode{traits}, then the expression
\tcode{out \shl\ quoted(s, delim, escape)}
behaves as a formatted output function~(\ref{ostream.formatted.reqmts})
of \tcode{out}. This forms a character sequence \tcode{seq}, initially
consisting of the following elements:
\begin{itemize}
\item \tcode{delim}.
\item Each character in \tcode{s}. If the character to be output is equal to
\tcode{escape} or \tcode{delim}, as determined by \tcode{traits_type::eq}, first
output \tcode{escape}.
\item \tcode{delim}.
\end{itemize}
Let \tcode{x} be the number of elements initially in \tcode{seq}.
Then padding is determined for \tcode{seq} as described
in~\ref{ostream.formatted.reqmts}, \tcode{seq} is inserted as if by calling
\tcode{out.rdbuf()->sputn(seq, n)}, where \tcode{n} is the larger of
\tcode{out.width()} and \tcode{x}, and \tcode{out.width(0)} is called.
The expression \tcode{out \shl\ quoted(s, delim, escape)} shall have type
\tcode{basic_ostream<charT, traits>\&} and value \tcode{out}.
\end{itemdescr}

\indexlibrary{\idxcode{quoted}}%
\begin{itemdecl}
template <class charT, class traits, class Allocator>
  @\unspec@ quoted(basic_string<charT, traits, Allocator>& s,
                      charT delim=charT('"'), charT escape=charT('\\'));
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object of unspecified type such that:
\begin{itemize}
\item If \tcode{in} is an instance of \tcode{basic_istream} with member types
\tcode{char_type} and \tcode{traits_type} the same as \tcode{charT}
and \tcode{traits}, respectively, then the expression
\tcode{in \shr\ quoted(s, delim, escape)} behaves as if it extracts the following
characters from \tcode{in} using
\tcode{basic_istream::operator\shr}~(\ref{istream::extractors})
which may throw \tcode{ios_base::failure}\brk{}~(\ref{ios::failure}):
\begin{itemize}
\item If the first character extracted is equal to \tcode{delim}, as
determined by \tcode{traits_type::eq}, then:
\begin{itemize}
\item Turn off the \tcode{skipws} flag.
\item \tcode{s.clear()}
\item Until an unescaped \tcode{delim} character is reached or \tcode{!in},
extract characters from \tcode{in} and append them to \tcode{s}, except that
if an \tcode{escape} is reached, ignore it and append the next character to
\tcode{s}.
\item Discard the final \tcode{delim} character.
\item Restore the \tcode{skipws} flag to its original value.
\end{itemize}
\item Otherwise, \tcode{in \shr\ s}.
\end{itemize}
\item If \tcode{out} is an instance of \tcode{basic_ostream} with member types
\tcode{char_type} and \tcode{traits_type} the same as \tcode{charT} and
\tcode{traits}, respectively, then the expression
\tcode{out \shl\ quoted(s, delim, escape)} behaves as specified for the
\tcode{const basic_string<charT, traits, Allocator>\&} overload of the
\tcode{quoted} function.
\end{itemize}
The expression \tcode{in \shr\ quoted(s, delim, escape)} shall have type
\tcode{basic_istream<charT, traits>\&} and value \tcode{in}. The expression
\tcode{out \shl\ quoted(s, delim, escape)} shall have type
\tcode{basic_ostream\brk{}<charT, traits>\&} and value \tcode{out}.
\end{itemdescr}

\rSec1[string.streams]{String-based streams}

\rSec2[string.streams.overview]{Overview}

\pnum
The header
\tcode{<sstream>}
defines four
class templates
and eight types that associate stream buffers with objects of class
\tcode{basic_string},
\indexlibrary{\idxcode{basic_string}}%
as described in~\ref{string.classes}.

\synopsis{Header \tcode{<sstream>} synopsis}
\indexlibrary{\idxhdr{sstream}}%

\indexlibrary{\idxcode{stringbuf}}%
\indexlibrary{\idxcode{basic_stringbuf<char>}}%
\indexlibrary{\idxcode{wstringbuf}}%
\indexlibrary{\idxcode{basic_stringbuf<wchar_t>}}%
\indexlibrary{\idxcode{istringstream}}%
\indexlibrary{\idxcode{basic_istringstream<char>}}%
\indexlibrary{\idxcode{wistringstream}}%
\indexlibrary{\idxcode{basic_istringstream<wchar_t>}}%
\indexlibrary{\idxcode{ostringstream}}%
\indexlibrary{\idxcode{basic_ostringstream<char>}}%
\indexlibrary{\idxcode{wostringstream}}%
\indexlibrary{\idxcode{basic_ostringstream<wchar_t>}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT>,
        class Allocator = allocator<charT> >
    class basic_stringbuf;

  typedef basic_stringbuf<char>     stringbuf;
  typedef basic_stringbuf<wchar_t> wstringbuf;

  template <class charT, class traits = char_traits<charT>,
        class Allocator = allocator<charT> >
    class basic_istringstream;

  typedef basic_istringstream<char>     istringstream;
  typedef basic_istringstream<wchar_t> wistringstream;

  template <class charT, class traits = char_traits<charT>,
        class Allocator = allocator<charT> >
    class basic_ostringstream;
  typedef basic_ostringstream<char>     ostringstream;
  typedef basic_ostringstream<wchar_t> wostringstream;

  template <class charT, class traits = char_traits<charT>,
        class Allocator = allocator<charT> >
    class basic_stringstream;
  typedef basic_stringstream<char>     stringstream;
  typedef basic_stringstream<wchar_t> wstringstream;
}
\end{codeblock}

\rSec2[stringbuf]{Class template \tcode{basic_stringbuf}}
\indexlibrary{\idxcode{basic_stringbuf}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT> >
  class basic_stringbuf : public basic_streambuf<charT,traits> {
  public:
    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;
    typedef Allocator                 allocator_type;

    // \ref{stringbuf.cons} Constructors:
    explicit basic_stringbuf(ios_base::openmode which
                               = ios_base::in | ios_base::out);
    explicit basic_stringbuf
    (const basic_string<charT,traits,Allocator>& str,
     ios_base::openmode which = ios_base::in | ios_base::out);
    basic_stringbuf(const basic_stringbuf& rhs) = delete;
    basic_stringbuf(basic_stringbuf&& rhs);

    // \ref{stringbuf.assign} Assign and swap:
    basic_stringbuf& operator=(const basic_stringbuf& rhs) = delete;
    basic_stringbuf& operator=(basic_stringbuf&& rhs);
    void swap(basic_stringbuf& rhs);

    // \ref{stringbuf.members} Get and set:
    basic_string<charT,traits,Allocator> str() const;
    void str(const basic_string<charT,traits,Allocator>& s);

  protected:
    // \ref{stringbuf.virtuals} Overridden virtual functions:
    virtual int_type   underflow();
    virtual int_type   pbackfail(int_type c = traits::eof());
    virtual int_type   overflow (int_type c = traits::eof());
    virtual  basic_streambuf<charT,traits>* setbuf(charT*, streamsize);


    virtual pos_type seekoff(off_type off, ios_base::seekdir way,
                             ios_base::openmode which
                               = ios_base::in | ios_base::out);
    virtual pos_type seekpos(pos_type sp,
                             ios_base::openmode which
                               = ios_base::in | ios_base::out);

  private:
    ios_base::openmode mode;  // \expos
  };

  template <class charT, class traits, class Allocator>
  void swap(basic_stringbuf<charT, traits, Allocator>& x,
            basic_stringbuf<charT, traits, Allocator>& y);
}
\end{codeblock}

\pnum
The class
\tcode{basic_stringbuf}
is derived from
\tcode{basic_streambuf}
to associate possibly the input sequence and possibly
the output sequence with a sequence of arbitrary
\term{characters}.
The sequence can be initialized from, or made available as, an object of class
\tcode{basic_string}.

\pnum
For the sake of exposition, the maintained data is presented here as:
\begin{itemize}
\item
\tcode{ios_base::openmode mode},
has
\tcode{in}
set if the input sequence can be read, and
\tcode{out}
set if the output sequence can be written.
\end{itemize}

\rSec3[stringbuf.cons]{\tcode{basic_stringbuf}  constructors}

\indexlibrary{\idxcode{basic_stringbuf}!\idxcode{basic_stringbuf}}%
\begin{itemdecl}
explicit basic_stringbuf(ios_base::openmode which =
                         ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_stringbuf},
initializing the base class with
\tcode{basic_streambuf()}~(\ref{streambuf.cons}), and initializing
\tcode{mode}
with \tcode{which}.

\pnum
\postcondition
\tcode{str() == ""}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_stringbuf}!constructor}%
\begin{itemdecl}
explicit basic_stringbuf(const basic_string<charT,traits,Allocator>& s,
                         ios_base::openmode which = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_stringbuf},
initializing the base class with
\tcode{basic_streambuf()}~(\ref{streambuf.cons}), and initializing
\tcode{mode}
with \tcode{which}.
Then calls \tcode{str(s)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_stringbuf}!constructor}%
\begin{itemdecl}
basic_stringbuf(basic_stringbuf&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}. It
is
\impldef{whether sequence pointers are copied by \tcode{basic_stringbuf} move
constructor} whether the sequence pointers in \tcode{*this}
(\tcode{eback()}, \tcode{gptr()}, \tcode{egptr()},
\tcode{pbase()}, \tcode{pptr()}, \tcode{epptr()}) obtain
the values which \tcode{rhs} had. Whether they do or not, \tcode{*this}
and \tcode{rhs} reference separate buffers (if any at all) after the
construction. The openmode, locale and any other state of \tcode{rhs} is
also copied.

\pnum
\postconditions Let \tcode{rhs_p} refer to the state of
\tcode{rhs} just prior to this construction and let \tcode{rhs_a}
refer to the state of \tcode{rhs} just after this construction.

\begin{itemize}
\item \tcode{str() == rhs_p.str()}
\item \tcode{gptr() - eback() == rhs_p.gptr() - rhs_p.eback()}
\item \tcode{egptr() - eback() == rhs_p.egptr() - rhs_p.eback()}
\item \tcode{pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()}
\item \tcode{epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase()}
\item \tcode{if (eback()) eback() != rhs_a.eback()}
\item \tcode{if (gptr()) gptr() != rhs_a.gptr()}
\item \tcode{if (egptr()) egptr() != rhs_a.egptr()}
\item \tcode{if (pbase()) pbase() != rhs_a.pbase()}
\item \tcode{if (pptr()) pptr() != rhs_a.pptr()}
\item \tcode{if (epptr()) epptr() != rhs_a.epptr()}
\end{itemize}
\end{itemdescr}

\rSec3[stringbuf.assign]{Assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_stringbuf}}%
\indexlibrary{\idxcode{basic_stringbuf}!\idxcode{operator=}}%
\begin{itemdecl}
basic_stringbuf& operator=(basic_stringbuf&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects After the move assignment \tcode{*this} has the observable state it would
have had if it had been move constructed from \tcode{rhs} (see~\ref{stringbuf.cons}).

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_stringbuf}}%
\indexlibrary{\idxcode{basic_stringbuf}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_stringbuf& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Exchanges the state of \tcode{*this}
and \tcode{rhs}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_stringbuf}}%
\indexlibrary{\idxcode{basic_stringbuf}!\idxcode{swap}}%
\begin{itemdecl}
template <class charT, class traits, class Allocator>
void swap(basic_stringbuf<charT, traits, Allocator>& x,
          basic_stringbuf<charT, traits, Allocator>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[stringbuf.members]{Member functions}

\indexlibrary{\idxcode{str}!\idxcode{basic_stringbuf}}%
\begin{itemdecl}
basic_string<charT,traits,Allocator> str() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A
\tcode{basic_string}
object whose content is equal to the
\tcode{basic_stringbuf}
underlying character sequence.
If the \tcode{basic_stringbuf} was created only in input mode, the resultant
\tcode{basic_string} contains the character sequence in the range
\range{eback()}{egptr()}. If the \tcode{basic_stringbuf} was created with
\tcode{which \& ios_base::out} being true then the resultant \tcode{basic_string}
contains the character sequence in the range \range{pbase()}{high_mark}, where
\tcode{high_mark} represents the position one past the highest initialized character
in the buffer. Characters can be initialized by writing to the stream, by constructing
the \tcode{basic_stringbuf} with a \tcode{basic_string}, or by calling the
\tcode{str(basic_string)} member function. In the case of calling the
\tcode{str(basic_string)} member function, all characters initialized prior to
the call are now considered uninitialized (except for those characters re-initialized
by the new \tcode{basic_string}). Otherwise the \tcode{basic_stringbuf} has been created
in neither input nor output mode and a zero length \tcode{basic_string} is returned. 
\end{itemdescr}

\indexlibrary{\idxcode{str}!\idxcode{basic_stringbuf}}%
\indexlibrary{\idxcode{basic_stringbuf}!\idxcode{str}}%
\begin{itemdecl}
void str(const basic_string<charT,traits,Allocator>& s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Copies the content of \tcode{s} into the \tcode{basic_stringbuf} underlying character
sequence and initializes the input and output sequences according to \tcode{mode}.

\pnum
\postconditions If \tcode{mode \& ios_base::out} is true, \tcode{pbase()} points to the
first underlying character and \tcode{epptr()} \tcode{>= pbase() + s.size()} holds; in
addition, if \tcode{mode \& ios_base::ate} is true,
\tcode{pptr() == pbase() + s.size()}
holds, otherwise \tcode{pptr() == pbase()} is true. If \tcode{mode \& ios_base::in} is
true, \tcode{eback()} points to the first underlying character, and both \tcode{gptr()
== eback()} and \tcode{egptr() == eback() + s.size()} hold.
\end{itemdescr}

\rSec3[stringbuf.virtuals]{Overridden virtual functions}

\indexlibrary{\idxcode{underflow}!\idxcode{basic_stringbuf}}%
\begin{itemdecl}
int_type underflow();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
If the input sequence has a read position available,
returns
\tcode{traits::to_int_type(*gptr())}.
Otherwise, returns
\tcode{traits::eof()}.
Any character in the underlying buffer which has been initialized is considered
to be part of the input sequence. 
\end{itemdescr}

\indexlibrary{\idxcode{pbackfail}!\idxcode{basic_stringbuf}}%
\begin{itemdecl}
int_type pbackfail(int_type c = traits::eof());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Puts back the character designated by \tcode{c} to the input
sequence, if possible, in one of three ways:
\begin{itemize}
\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{false}
and
if the input sequence has a putback position available, and
if
\tcode{traits::eq(to_char_type(c),gptr()[-1])}
returns
\tcode{true},
assigns
\tcode{gptr() - 1}
to
\tcode{gptr()}.

Returns:
\tcode{c}.
\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{false}
and if the input sequence
has a putback position available, and
if \tcode{mode}
\tcode{\&}
\tcode{ios_base::out} is
nonzero,
assigns \tcode{c} to
\tcode{*\dcr gptr()}.

Returns:
\tcode{c}.
\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{true}
and if the input sequence has a putback position available,
assigns
\tcode{gptr() - 1}
to
\tcode{gptr()}.

Returns:
\tcode{traits::not_eof(c)}.
\end{itemize}

\pnum
\returns
\tcode{traits::eof()}
to indicate failure.

\pnum
\notes
If the function can succeed in more than one of these ways, it is
unspecified which way is chosen.
\indextext{unspecified}%
\end{itemdescr}

\indexlibrary{\idxcode{overflow}!\idxcode{basic_stringbuf}}%
\begin{itemdecl}
int_type overflow(int_type c = traits::eof());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Appends the character designated by \tcode{c} to the output
sequence, if possible, in one of two ways:
\begin{itemize}
\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{false}
and if either
the output sequence has a write position available or
the function makes a write position available
(as described below),
the function calls
\tcode{sputc(c )}.

Signals success by returning \tcode{c}.

\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{true},
there is no character to append.

Signals success by returning a value other than
\tcode{traits::eof()}.
\end{itemize}

\pnum
\notes
The function can alter the number of write positions available as a
result of any call.

\pnum
\returns
\tcode{traits::eof()}
to indicate failure.

\pnum
The function can make a write position available only if
\tcode{(mode \& ios_base::out) != 0}.
To make a write position available,
the function reallocates (or initially allocates) an array object
with a sufficient number of elements to hold
the current array object (if any), plus
at least
one additional write position.
If
\tcode{(mode \& ios_base::in) != 0},
the function alters the read end pointer
\tcode{egptr()}
to point just past the new write position.
\end{itemdescr}

\indexlibrary{\idxcode{seekoff}!\idxcode{basic_stringbuf}}%
\begin{itemdecl}
pos_type seekoff(off_type off, ios_base::seekdir way,
                 ios_base::openmode which
                   = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Alters the stream position within one of the
controlled sequences, if possible, as indicated in Table~\ref{tab:iostreams.seekoff.positioning}.

\begin{libtab2}{\tcode{seekoff} positioning}{tab:iostreams.seekoff.positioning}
{p{2.5in}l}{Conditions}{Result}
\tcode{(which \& ios_base\colcol{}in)}\tcode{ == ios_base::in}  &
 positions the input sequence \\ \rowsep
\tcode{(which \& ios_base\colcol{}out)}\tcode{ == ios_base::out}  &
 positions the output sequence  \\ \rowsep
\tcode{(which \& (ios_base::in |}\br
\tcode{ios_base::out)) ==}\br
\tcode{(ios_base::in) |}\br
\tcode{ios_base::out))}\br
and \tcode{way ==} either\br
\tcode{ios_base::beg} or\br
\tcode{ios_base::end}     &
 positions both the input and the output sequences  \\ \rowsep
Otherwise &
 the positioning operation fails. \\
\end{libtab2}

\pnum
For a sequence to be positioned, if its next pointer
(either
\tcode{gptr()}
or
\tcode{pptr()})
is a null pointer and the new offset \tcode{newoff} is nonzero, the positioning
operation fails. Otherwise, the function determines \tcode{newoff} as indicated in
Table~\ref{tab:iostreams.newoff.values}.

\begin{libtab2}{\tcode{newoff} values}{tab:iostreams.newoff.values}
{lp{2.0in}}{Condition}{\tcode{newoff} Value}
\tcode{way == ios_base::beg}  &
 0  \\ \rowsep
\tcode{way == ios_base::cur}  &
 the next pointer minus the beginning pointer (\tcode{xnext - xbeg}). \\ \rowsep
\tcode{way == ios_base::end}  &
 the high mark pointer minus the beginning pointer (\tcode{high_mark - xbeg}).   \\
\end{libtab2}

\pnum
If
\tcode{(newoff + off) < 0},
or if \tcode{newoff + off} refers to an uninitialized
character (as defined in~\ref{stringbuf.members} paragraph 1),
the positioning operation fails.
Otherwise, the function assigns
\tcode{xbeg + newoff + off}
to the next pointer \tcode{xnext}.

\pnum
\returns
\tcode{pos_type(newoff)},
constructed from the resultant offset \tcode{newoff}
(of type
\tcode{off_type}),
that stores the resultant stream position, if possible.
If the positioning operation fails, or
if the constructed object cannot represent the resultant stream position,
the return value is
\tcode{pos_type(off_type(-1))}.
\end{itemdescr}

\indexlibrary{\idxcode{seekpos}!\idxcode{basic_stringbuf}}%
\begin{itemdecl}
pos_type seekpos(pos_type sp, ios_base::openmode which
                   = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{seekoff(off_type(sp), ios_base::beg, which)}.

\pnum
\returns
\tcode{sp}
to indicate success, or
\tcode{pos_type(off_type(-1))}
to indicate failure.
\end{itemdescr}

\indexlibrary{\idxcode{setbuf}!\idxcode{basic_streambuf}}%
\indexlibrary{\idxcode{basic_streambuf}!\idxcode{setbuf}}%
\begin{itemdecl}
basic_streambuf<charT,traits>* setbuf(charT* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
\indextext{implementation-defined}%
\impldef{effect of calling \tcode{basic_streambuf::setbuf} with non-zero arguments},
except that
\tcode{setbuf(0,0)}
has no effect.

\pnum
\returns
\tcode{this}.
\end{itemdescr}

\rSec2[istringstream]{Class template \tcode{basic_istringstream}}

\indexlibrary{\idxcode{basic_istringstream}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT>,
        class Allocator = allocator<charT> >
  class basic_istringstream : public basic_istream<charT,traits> {
  public:
    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;
    typedef Allocator                 allocator_type;

    // \ref{istringstream.cons} Constructors:
    explicit basic_istringstream(ios_base::openmode which = ios_base::in);
    explicit basic_istringstream(
               const basic_string<charT,traits,Allocator>& str,
               ios_base::openmode which = ios_base::in);
    basic_istringstream(const basic_istringstream& rhs) = delete;
    basic_istringstream(basic_istringstream&& rhs);

    // \ref{istringstream.assign} Assign and swap:
    basic_istringstream& operator=(const basic_istringstream& rhs) = delete;
    basic_istringstream& operator=(basic_istringstream&& rhs);
    void swap(basic_istringstream& rhs);

    // \ref{istringstream.members} Members:
    basic_stringbuf<charT,traits,Allocator>* rdbuf() const;

    basic_string<charT,traits,Allocator> str() const;
    void str(const basic_string<charT,traits,Allocator>& s);
  private:
    basic_stringbuf<charT,traits,Allocator> sb; // \expos
  };

  template <class charT, class traits, class Allocator>
  void swap(basic_istringstream<charT, traits, Allocator>& x,
            basic_istringstream<charT, traits, Allocator>& y);
}
\end{codeblock}

\pnum
The class
\tcode{basic_istringstream<charT, traits, Allocator>}
supports reading objects of class
\tcode{basic_string<\brk{}charT, traits, Allocator>}.
It uses a
\tcode{basic_stringbuf<charT, traits, Allocator>}
object to control the associated storage.
For the sake of exposition, the maintained data is presented here as:
\begin{itemize}
\item
\tcode{sb}, the \tcode{stringbuf} object.
\end{itemize}

\rSec3[istringstream.cons]{\tcode{basic_istringstream} constructors}

\indexlibrary{\idxcode{basic_istringstream}!\idxcode{basic_istringstream}}%
\begin{itemdecl}
explicit basic_istringstream(ios_base::openmode which = ios_base::in);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_istringstream<charT, traits>},
initializing the base class with
\tcode{basic_istream(\&sb)}
and initializing \tcode{sb} with
\tcode{basic_stringbuf<charT, traits, Alloca\-tor>(which | ios_base::in))}~(\ref{stringbuf.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{basic_istringstream}!constructor}%
\begin{itemdecl}
explicit basic_istringstream(
                const basic_string<charT, traits, Allocator>& str,
                ios_base::openmode which = ios_base::in);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_istringstream<charT, traits>},
initializing the base class with
\tcode{basic_istream(\&sb)}
and initializing \tcode{sb} with
\tcode{basic_stringbuf<charT, traits, Alloca\-tor>(str, which | ios_base::in))}~(\ref{stringbuf.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{basic_istringstream}!constructor}%
\begin{itemdecl}
basic_istringstream(basic_istringstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}. This
is accomplished by move constructing the base class, and the contained
\tcode{basic_stringbuf}.
Next \tcode{basic_istream<charT,traits>::set_rdbuf(\&sb)} is called to
install the contained \tcode{basic_stringbuf}.
\end{itemdescr}

\rSec3[istringstream.assign]{Assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_istringstream}}%
\indexlibrary{\idxcode{basic_istringstream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_istringstream& operator=(basic_istringstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move assigns the base and members of \tcode{*this} from the base and corresponding
members of \tcode{rhs}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_istringstream}}%
\indexlibrary{\idxcode{basic_istringstream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_istringstream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Exchanges the state of \tcode{*this} and
\tcode{rhs} by calling
\tcode{basic_istream<charT,traits>::swap(rhs)} and
\tcode{sb.swap(rhs.sb)}.
\end{itemdescr}


\indexlibrary{\idxcode{swap}!\idxcode{basic_istringstream}}%
\indexlibrary{\idxcode{basic_istringstream}!\idxcode{swap}}%
\begin{itemdecl}
template <class charT, class traits, class Allocator>
void swap(basic_istringstream<charT, traits, Allocator>& x,
          basic_istringstream<charT, traits, Allocator>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[istringstream.members]{Member functions}

\indexlibrary{\idxcode{rdbuf}!\idxcode{basic_istringstream}}%
\begin{itemdecl}
basic_stringbuf<charT,traits,Allocator>* rdbuf() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{const_cast<basic_stringbuf<charT,traits,Allocator>*>(\&sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{str}!\idxcode{basic_istringstream}}%
\begin{itemdecl}
basic_string<charT,traits,Allocator> str() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rdbuf()->str()}.
\end{itemdescr}

\indexlibrary{\idxcode{str}!\idxcode{basic_istringstream}}%
\indexlibrary{\idxcode{basic_istringstream}!\idxcode{str}}%
\begin{itemdecl}
void str(const basic_string<charT,traits,Allocator>& s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->str(s)}.
\end{itemdescr}

\rSec2[ostringstream]{Class template \tcode{basic_ostringstream}}

\indexlibrary{\idxcode{basic_ostringstream}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT>,
        class Allocator = allocator<charT> >
  class basic_ostringstream : public basic_ostream<charT,traits> {
  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;
    typedef Allocator                 allocator_type;

    // \ref{ostringstream.cons} Constructors/destructor:
    explicit basic_ostringstream(ios_base::openmode which = ios_base::out);
    explicit basic_ostringstream(
             const basic_string<charT,traits,Allocator>& str,
             ios_base::openmode which = ios_base::out);
    basic_ostringstream(const basic_ostringstream& rhs) = delete;
    basic_ostringstream(basic_ostringstream&& rhs);

    // \ref{ostringstream.assign} Assign/swap:
    basic_ostringstream& operator=(const basic_ostringstream& rhs) = delete;
    basic_ostringstream& operator=(basic_ostringstream&& rhs);
    void swap(basic_ostringstream& rhs);

    // \ref{ostringstream.members} Members:
    basic_stringbuf<charT,traits,Allocator>* rdbuf() const;

    basic_string<charT,traits,Allocator> str() const;
    void    str(const basic_string<charT,traits,Allocator>& s);
   private:
    basic_stringbuf<charT,traits,Allocator> sb; // \expos
  };

  template <class charT, class traits, class Allocator>
  void swap(basic_ostringstream<charT, traits, Allocator>& x,
            basic_ostringstream<charT, traits, Allocator>& y);
}
\end{codeblock}

\pnum
The class
\tcode{basic_ostringstream<charT, traits, Allocator>}
supports writing objects of class
\tcode{basic_string<\brk{}charT, traits, Allocator>}.
It uses a
\tcode{basic_stringbuf}
object to control the associated storage.
For the sake of exposition, the maintained data is presented here as:
\begin{itemize}
\item
\tcode{sb}, the \tcode{stringbuf} object.
\end{itemize}

\rSec3[ostringstream.cons]{\tcode{basic_ostringstream} constructors}

\indexlibrary{\idxcode{basic_ostringstream}!\idxcode{basic_ostringstream}}%
\begin{itemdecl}
explicit basic_ostringstream(ios_base::openmode which = ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ostringstream},
initializing the base class with
\tcode{basic_ostream(\brk{}\&sb)}
and initializing \tcode{sb} with
\tcode{basic_stringbuf<charT, traits, Allocator>(which | \brk{}ios_base::out))}~(\ref{stringbuf.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{basic_ostringstream}!constructor}%
\begin{itemdecl}
explicit basic_ostringstream(
  const basic_string<charT,traits,Allocator>& str,
  ios_base::openmode which = ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ostringstream<charT, traits>},
initializing the base class with
\tcode{basic_ostream(\&sb)}
and initializing \tcode{sb} with
\tcode{basic_stringbuf<charT, traits, Alloca\-tor>(str, which | ios_base::out))}~(\ref{stringbuf.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{basic_ostringstream}!constructor}%
\begin{itemdecl}
basic_ostringstream(basic_ostringstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}. This
is accomplished by move constructing the base class, and the contained
\tcode{basic_stringbuf}.
Next \tcode{basic_ostream<charT,traits>::set_rdbuf(\&sb)} is called to
install the contained \tcode{basic_stringbuf}.
\end{itemdescr}

\rSec3[ostringstream.assign]{Assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_ostringstream}}%
\indexlibrary{\idxcode{basic_ostringstream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_ostringstream& operator=(basic_ostringstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move assigns the base and members of \tcode{*this} from the base and corresponding
members of \tcode{rhs}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_ostringstream}}%
\indexlibrary{\idxcode{basic_ostringstream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_ostringstream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Exchanges the state of \tcode{*this} and
\tcode{rhs} by calling
\tcode{basic_ostream<charT,traits>::swap(rhs)} and
\tcode{sb.swap(rhs.sb)}.
\end{itemdescr}


\indexlibrary{\idxcode{swap}!\idxcode{basic_ostringstream}}%
\indexlibrary{\idxcode{basic_ostringstream}!\idxcode{swap}}%
\begin{itemdecl}
template <class charT, class traits, class Allocator>
void swap(basic_ostringstream<charT, traits, Allocator>& x,
          basic_ostringstream<charT, traits, Allocator>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[ostringstream.members]{Member functions}

\indexlibrary{\idxcode{rdbuf}!\idxcode{basic_ostringstream}}%
\begin{itemdecl}
basic_stringbuf<charT,traits,Allocator>* rdbuf() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{const_cast<basic_stringbuf<charT,traits,Allocator>*>(\&sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{str}!\idxcode{basic_ostringstream}}%
\begin{itemdecl}
basic_string<charT,traits,Allocator> str() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rdbuf()->str()}.
\end{itemdescr}

\indexlibrary{\idxcode{str}!\idxcode{basic_ostringstream}}%
\indexlibrary{\idxcode{basic_ostringstream}!\idxcode{str}}%
\begin{itemdecl}
void str(const basic_string<charT,traits,Allocator>& s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->str(s)}.
\end{itemdescr}

\rSec2[stringstream]{Class template \tcode{basic_stringstream}}

\indexlibrary{\idxcode{basic_stringstream}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT>,
        class Allocator = allocator<charT> >
  class basic_stringstream
    : public basic_iostream<charT,traits> {
  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;
    typedef Allocator                 allocator_type;

    // constructors/destructor
    explicit basic_stringstream(
    ios_base::openmode which = ios_base::out|ios_base::in);
    explicit basic_stringstream(
    const basic_string<charT,traits,Allocator>& str,
    ios_base::openmode which = ios_base::out|ios_base::in);
    basic_stringstream(const basic_stringstream& rhs) = delete;
    basic_stringstream(basic_stringstream&& rhs);

    // \ref{stringstream.assign} Assign/swap:
    basic_stringstream& operator=(const basic_stringstream& rhs) = delete;
    basic_stringstream& operator=(basic_stringstream&& rhs);
    void swap(basic_stringstream& rhs);

    // Members:
    basic_stringbuf<charT,traits,Allocator>* rdbuf() const;
    basic_string<charT,traits,Allocator> str() const;
    void str(const basic_string<charT,traits,Allocator>& str);

  private:
    basic_stringbuf<charT, traits> sb;  // \expos
  };

  template <class charT, class traits, class Allocator>
  void swap(basic_stringstream<charT, traits, Allocator>& x,
            basic_stringstream<charT, traits, Allocator>& y);
}
\end{codeblock}

\pnum
The
class template
\tcode{basic_stringstream<charT, traits>}
supports reading and writing from objects of class
\tcode{basic_string<charT, traits, Allocator>}.
It uses a
\tcode{basic_stringbuf<charT, traits, Alloca\-tor>}
object to control the associated sequence.
For the sake of exposition, the maintained data is presented here as
\begin{itemize}
\item
\tcode{sb}, the \tcode{stringbuf} object.
\end{itemize}

\rSec2[stringstream.cons]{basic_stringstream constructors}

\indexlibrary{\idxcode{basic_stringstream}!\idxcode{basic_stringstream}}%
\begin{itemdecl}
explicit basic_stringstream(
    ios_base::openmode which = ios_base::out|ios_base::in);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_stringstream<charT,traits>},
initializing the base class with
\tcode{basic_iostream(\&sb)}
and initializing
\tcode{sb}
with
\tcode{basic_stringbuf<charT,traits,Alloca\-tor>(which)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_stringstream}!constructor}%
\begin{itemdecl}
explicit basic_stringstream(
    const basic_string<charT,traits,Allocator>& str,
    ios_base::openmode which = ios_base::out|ios_base::in);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_stringstream<charT, traits>},
initializing the base class with
\tcode{basic_iostream(\&sb)}
and initializing
\tcode{sb}
with
\tcode{basic_stringbuf<charT, traits, Alloca\-tor>(str, which)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_stringstream}!constructor}%
\begin{itemdecl}
basic_stringstream(basic_stringstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}. This
is accomplished by move constructing the base class, and the contained
\tcode{basic_stringbuf}.
Next \tcode{basic_istream<charT,traits>::set_rdbuf(\&sb)} is called to
install the contained \tcode{basic_stringbuf}.
\end{itemdescr}

\rSec3[stringstream.assign]{Assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_stringstream}}%
\indexlibrary{\idxcode{basic_stringstream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_stringstream& operator=(basic_stringstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move assigns the base and members of \tcode{*this} from the base and corresponding
members of \tcode{rhs}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_stringstream}}%
\indexlibrary{\idxcode{basic_stringstream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_stringstream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Exchanges the state of \tcode{*this} and
\tcode{rhs} by calling
\tcode{basic_iostream<charT,traits>::swap(rhs)} and
\tcode{sb.swap(rhs.sb)}.
\end{itemdescr}


\indexlibrary{\idxcode{swap}!\idxcode{basic_stringstream}}%
\indexlibrary{\idxcode{basic_stringstream}!\idxcode{swap}}%
\begin{itemdecl}
template <class charT, class traits, class Allocator>
void swap(basic_stringstream<charT, traits, Allocator>& x,
          basic_stringstream<charT, traits, Allocator>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec2[stringstream.members]{Member functions}

\indexlibrary{\idxcode{rdbuf}!\idxcode{basic_stringstream}}%
\begin{itemdecl}
basic_stringbuf<charT,traits,Allocator>* rdbuf() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{const_cast<basic_stringbuf<charT,traits,Allocator>*>(\&sb)}
\end{itemdescr}

\indexlibrary{\idxcode{str}!\idxcode{basic_stringstream}}%
\begin{itemdecl}
basic_string<charT,traits,Allocator> str() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rdbuf()->str()}.
\end{itemdescr}

\indexlibrary{\idxcode{str}!\idxcode{basic_stringstream}}%
\indexlibrary{\idxcode{basic_stringstream}!\idxcode{str}}%
\begin{itemdecl}
void str(const basic_string<charT,traits,Allocator>& str);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->str(str)}.
\end{itemdescr}

\rSec1[file.streams]{File-based streams}

\rSec2[fstreams]{File streams}

\pnum
The header
\tcode{<fstream>}
defines four class templates and eight types
that associate stream buffers with files and assist
reading and writing files.

\synopsis{Header \tcode{<fstream>} synopsis}
\indexlibrary{\idxhdr{fstream}}%
\indexlibrary{\idxcode{filebuf}}%
\indexlibrary{\idxcode{basic_filebuf<char>}}%
\indexlibrary{\idxcode{wfilebuf}}%
\indexlibrary{\idxcode{basic_filebuf<wchar_t>}}%
\indexlibrary{\idxcode{ifstream}}%
\indexlibrary{\idxcode{basic_ifstream<char>}}%
\indexlibrary{\idxcode{wifstream}}%
\indexlibrary{\idxcode{basic_ifstream<wchar_t>}}%
\indexlibrary{\idxcode{ofstream}}%
\indexlibrary{\idxcode{basic_ofstream<char>}}%
\indexlibrary{\idxcode{wofstream}}%
\indexlibrary{\idxcode{basic_ofstream<wchar_t>}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
    class basic_filebuf;
  typedef basic_filebuf<char>    filebuf;
  typedef basic_filebuf<wchar_t> wfilebuf;

  template <class charT, class traits = char_traits<charT> >
    class basic_ifstream;
  typedef basic_ifstream<char>    ifstream;
  typedef basic_ifstream<wchar_t> wifstream;

  template <class charT, class traits = char_traits<charT> >
    class basic_ofstream;
  typedef basic_ofstream<char>    ofstream;
  typedef basic_ofstream<wchar_t> wofstream;

  template <class charT, class traits = char_traits<charT> >
    class basic_fstream;
  typedef basic_fstream<char>     fstream;
  typedef basic_fstream<wchar_t> wfstream;
}
\end{codeblock}

\pnum
In this subclause, the type name \tcode{FILE} refers to
the type
\tcode{FILE}
declared in
\tcode{<cstdio>}
\indexlibrary{\idxhdr{cstdio}}%
(\ref{c.files}).

\pnum
\enternote The class template \tcode{basic_filebuf} treats a file as a source or
sink of bytes. In an environment that uses a large character set, the file
typically holds multibyte character sequences and the \tcode{basic_filebuf}
object converts those multibyte sequences into wide character sequences.
\exitnote

\rSec3[filebuf]{Class template \tcode{basic_filebuf}}

\indexlibrary{\idxcode{basic_filebuf}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_filebuf : public basic_streambuf<charT,traits> {
  public:
    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;

    // \ref{filebuf.cons} Constructors/destructor:
    basic_filebuf();
    basic_filebuf(const basic_filebuf& rhs) = delete;
    basic_filebuf(basic_filebuf&& rhs);
    virtual ~basic_filebuf();

    // \ref{filebuf.assign} Assign/swap:
    basic_filebuf& operator=(const basic_filebuf& rhs) = delete;
    basic_filebuf& operator=(basic_filebuf&& rhs);
    void swap(basic_filebuf& rhs);

     // \ref{filebuf.members} Members:
    bool is_open() const;
    basic_filebuf<charT,traits>* open(const char* s,
        ios_base::openmode mode);
    basic_filebuf<charT,traits>* open(const string& s,
        ios_base::openmode mode);
    basic_filebuf<charT,traits>* close();

  protected:
    // \ref{filebuf.virtuals} Overridden virtual functions:
    virtual streamsize showmanyc();
    virtual int_type underflow();
    virtual int_type uflow();
    virtual int_type pbackfail(int_type c = traits::eof());
    virtual int_type overflow (int_type c = traits::eof());

    virtual basic_streambuf<charT,traits>*
        setbuf(char_type* s, streamsize n);
    virtual pos_type seekoff(off_type off, ios_base::seekdir way,
        ios_base::openmode which = ios_base::in | ios_base::out);
    virtual pos_type seekpos(pos_type sp,
        ios_base::openmode which = ios_base::in | ios_base::out);
    virtual int      sync();
    virtual void     imbue(const locale& loc);
  };

  template <class charT, class traits>
  void swap(basic_filebuf<charT, traits>& x,
            basic_filebuf<charT, traits>& y);
}
\end{codeblock}

\pnum
The class
\tcode{basic_filebuf<charT,traits>}
associates both the input sequence and the output
sequence with a file.

\pnum
The restrictions on reading and writing a sequence controlled by an
object of class
\tcode{basic_filebuf<charT, traits>}
are the same as for reading and writing with the Standard C library
\tcode{FILE}s.

\pnum
In particular:
\begin{itemize}
\item
If the file is not open for reading the input sequence
cannot be read.
\item
If the file is not open for writing the output
sequence cannot be written.
\item
A joint file position is maintained for both the input sequence and
the output sequence.
\end{itemize}

\pnum
An instance of
\tcode{basic_filebuf}
behaves as described in~\ref{filebuf} provided
\tcode{traits::pos_type}
is
\tcode{fpos<traits\colcol{}state_type>}.
Otherwise the behavior is undefined.

\pnum
In order to support file I/O and multibyte/wide character conversion,
conversions are performed using members of a facet, referred to as
\tcode{a_codecvt} in following sections, obtained as if by

\begin{codeblock}
const codecvt<charT,char,typename traits::state_type>& a_codecvt =
  use_facet<codecvt<charT,char,typename traits::state_type> >(getloc());
\end{codeblock}

\rSec3[filebuf.cons]{\tcode{basic_filebuf} constructors}

\indexlibrary{\idxcode{basic_filebuf}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
basic_filebuf();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_filebuf<charT,traits>},
initializing the base class with
\tcode{basic_streambuf<charT,traits>()}~(\ref{streambuf.cons}).

\pnum
\postcondition
\tcode{is_open() == false}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_filebuf}!constructor}%
\begin{itemdecl}
basic_filebuf(basic_filebuf&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}. It
is \impldef{whether sequence pointers are copied by \tcode{basic_filebuf} move
constructor} whether the sequence pointers in \tcode{*this}
(\tcode{eback()}, \tcode{gptr()}, \tcode{egptr()},
\tcode{pbase()}, \tcode{pptr()}, \tcode{epptr()}) obtain
the values which \tcode{rhs} had. Whether they do or not, \tcode{*this}
and \tcode{rhs} reference separate buffers (if any at all) after the
construction. Additionally \tcode{*this} references the file
which \tcode{rhs} did before the construction, and
\tcode{rhs} references no file after the construction. The
openmode, locale and any other state of \tcode{rhs} is also
copied.

\pnum
\postconditions Let \tcode{rhs_p} refer to the state of
\tcode{rhs} just prior to this construction and let \tcode{rhs_a}
refer to the state of \tcode{rhs} just after this construction.

\begin{itemize}
\item \tcode{is_open() == rhs_p.is_open()}
\item \tcode{rhs_a.is_open() == false}
\item \tcode{gptr() - eback() == rhs_p.gptr() - rhs_p.eback()}
\item \tcode{egptr() - eback() == rhs_p.egptr() - rhs_p.eback()}
\item \tcode{pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()}
\item \tcode{epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase()}
\item \tcode{if (eback()) eback() != rhs_a.eback()}
\item \tcode{if (gptr()) gptr() != rhs_a.gptr()}
\item \tcode{if (egptr()) egptr() != rhs_a.egptr()}
\item \tcode{if (pbase()) pbase() != rhs_a.pbase()}
\item \tcode{if (pptr()) pptr() != rhs_a.pptr()}
\item \tcode{if (epptr()) epptr() != rhs_a.epptr()}
\end{itemize}
\end{itemdescr}

\indexlibrary{\idxcode{basic_filebuf}!destructor}%
\begin{itemdecl}
virtual ~basic_filebuf();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Destroys an object of class
\tcode{basic_filebuf<charT,traits>}.
Calls
\tcode{close()}.
If an exception occurs during the destruction of the object, including the call to \tcode{close()}, the exception is caught but not rethrown (see~\ref{res.on.exception.handling}).
\end{itemdescr}

\rSec3[filebuf.assign]{Assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_filebuf}}%
\indexlibrary{\idxcode{basic_filebuf}!\idxcode{operator=}}%
\begin{itemdecl}
basic_filebuf& operator=(basic_filebuf&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Calls \tcode{this->close()} then move assigns from \tcode{rhs}. After the
move assignment \tcode{*this} has the observable state it would have had if it
had been move constructed from \tcode{rhs} (see~\ref{filebuf.cons}).

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_filebuf}}%
\indexlibrary{\idxcode{basic_filebuf}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_filebuf& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Exchanges the state of \tcode{*this}
and \tcode{rhs}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_filebuf}}%
\indexlibrary{\idxcode{basic_filebuf}!\idxcode{swap}}%
\begin{itemdecl}
template <class charT, class traits>
void swap(basic_filebuf<charT, traits>& x,
          basic_filebuf<charT, traits>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[filebuf.members]{Member functions}

\indexlibrary{\idxcode{is_open}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
bool is_open() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{true}
if a previous call to
\tcode{open}
succeeded (returned a non-null value) and there has been no intervening
call to close.
\end{itemdescr}

\indexlibrary{\idxcode{open}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
basic_filebuf<charT,traits>* open(const char* s,
    ios_base::openmode mode);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If
\tcode{is_open() != false},
returns a null pointer.
Otherwise,
initializes the
\tcode{filebuf}
as required.
It then opens a file, if possible, whose name is the
\ntbs \tcode{s}
(as if by calling
\tcode{std::fopen(s,modstr)}).
\indextext{NTBS}%
\indexlibrary{\idxcode{fopen}}%
The \ntbs \tcode{modstr} is determined from
\tcode{mode \& $\sim$ios_base::ate}
as indicated in Table~\ref{tab:iostreams.file.open.modes}.
If \tcode{mode} is not some combination of flags shown in the table then
the open fails.

\begin{floattable}{File open modes}{tab:iostreams.file.open.modes}
{cccccl}
\topline
\multicolumn{5}{|c}{\tcode{ios_base} flag combination} & \tcode{stdio} equivalent \\
\tcode{binary}  & \tcode{in}  & \tcode{out} & \tcode{trunc} & \tcode{app} &     \\ \capsep
    &   & + &   &   & \tcode{"w"}   \\ \rowsep
    &   & + &   & + & \tcode{"a"}   \\ \rowsep
    &   &   &   & + & \tcode{"a"}   \\ \rowsep
    &   & + & + &   & \tcode{"w"}   \\ \rowsep
    & + &   &   &   & \tcode{"r"}   \\ \rowsep
    & + & + &   &   & \tcode{"r+"}  \\ \rowsep
    & + & + & + &   & \tcode{"w+"}  \\ \rowsep
    & + & + &   & + & \tcode{"a+"}  \\ \rowsep
    & + &   &   & + & \tcode{"a+"}  \\ \capsep
  + &   & + &   &   & \tcode{"wb"}  \\ \rowsep
  + &   & + &   & + & \tcode{"ab"}  \\ \rowsep
  + &   &   &   & + & \tcode{"ab"}  \\ \rowsep
  + &   & + & + &   & \tcode{"wb"}  \\ \rowsep
  + & + &   &   &   & \tcode{"rb"}  \\ \rowsep
  + & + & + &   &   & \tcode{"r+b"} \\ \rowsep
  + & + & + & + &   & \tcode{"w+b"} \\ \rowsep
  + & + & + &   & + & \tcode{"a+b"} \\ \rowsep
  + & + &   &   & + & \tcode{"a+b"} \\
\end{floattable}

\pnum
If the open operation succeeds and
\tcode{(mode \& ios_base::ate) != 0},
positions the file to the end
(as if by calling
\tcode{std::fseek(file,0,SEEK_END)}).\footnote{The macro
\tcode{SEEK_END}
is defined, and the function signatures
\indexlibrary{\idxcode{fopen}}%
\tcode{fopen(const char*, const char*)}
and
\tcode{fseek(FILE*, long, int)}
\indexlibrary{\idxcode{fseek}}%
are declared, in
\indexlibrary{\idxhdr{cstdio}}%
\tcode{<cstdio>}~(\ref{c.files}).}

\pnum
If the repositioning operation fails, calls
\tcode{close()}
and returns a null pointer to indicate failure.

\pnum
\returns
\tcode{this}
if successful, a null pointer otherwise.
\end{itemdescr}

\indexlibrary{\idxcode{open}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
basic_filebuf<charT,traits>* open(const string& s,
    ios_base::openmode mode);
\end{itemdecl}

\begin{itemdescr}
\returns
\tcode{open(s.c_str(), mode);}
\end{itemdescr}

\indexlibrary{\idxcode{close}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
basic_filebuf<charT,traits>* close();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If
\tcode{is_open() == false},
returns a null pointer.
If a put area exists, calls
\tcode{overflow(traits::\brk{}eof())}
to flush characters.
If the last virtual member function called on
\tcode{*this}
(between
\tcode{underflow},
\tcode{overflow},
\tcode{seekoff},
and
\tcode{seekpos})
was
\tcode{overflow}
then calls
\tcode{a_codecvt.unshift}
(possibly several times) to determine a termination sequence, inserts those
characters and calls
\tcode{overflow(traits::\brk{}eof())}
again.
Finally, regardless of whether any of the preceding calls fails or throws an
exception, the function closes the file
(as if by calling
\indexlibrary{\idxcode{fclose}}%
\tcode{std::fclose(file)}).\footnote{The function signature
\tcode{fclose(FILE*)}
is declared in
\tcode{<cstdio>}
\indexlibrary{\idxhdr{cstdio}}%
\indexlibrary{\idxcode{fclose}}%
(\ref{c.files}).}
If any of the calls made by the function, including \tcode{std::fclose}, fails,
\tcode{close} fails by returning a null pointer. If one of these calls throws an
exception, the exception is caught and rethrown after closing the file.

\pnum
\returns
\tcode{this}
on success, a null pointer otherwise.

\pnum
\postcondition
\tcode{is_open() == false}.
\end{itemdescr}

\rSec3[filebuf.virtuals]{Overridden virtual functions}

\indexlibrary{\idxcode{showmanyc}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
streamsize showmanyc();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves the same as
\tcode{basic_streambuf::showmanyc()}~(\ref{streambuf.virtuals}).
\indexlibrary{\idxcode{showmanyc}!\idxcode{basic_streambuf}}%

\pnum
\notes
An
implementation might well provide an overriding definition for this function
signature if it can determine that more characters can be read from the input
sequence.
\end{itemdescr}

\indexlibrary{\idxcode{underflow}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
int_type underflow();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves according to the description of
\tcode{basic_streambuf<charT,traits>::underflow()},
with the specialization that a sequence of characters is read from the input
sequence as if by reading from the associated file
into an internal buffer (
\tcode{extern_buf})
and then as if by doing

\begin{codeblock}
char   extern_buf[XSIZE];
char*  extern_end;
charT  intern_buf[ISIZE];
charT* intern_end;
codecvt_base::result r =
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
               intern_buf, intern_buf+ISIZE, intern_end);
\end{codeblock}

This shall be done in such a way that the class can recover the
position
(\tcode{fpos_t})
corresponding to each character between
\tcode{intern_buf}
and
\tcode{intern_end}.
If the value of
\tcode{r}
indicates that
\tcode{a_codecvt.in()}
ran out of space in
\tcode{intern_buf},
retry with a larger
\tcode{intern_buf}.
\end{itemdescr}

\indexlibrary{\idxcode{uflow}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
int_type uflow();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves according to the description of
\tcode{basic_streambuf<charT,traits>::uflow()},
with the specialization that a sequence of characters is read from the input
with the same method as used by
\tcode{underflow}.
\end{itemdescr}

\indexlibrary{\idxcode{pbackfail}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
int_type pbackfail(int_type c = traits::eof());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Puts back the character designated by \tcode{c} to the input
sequence, if possible, in one of three ways:
\begin{itemize}
\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{false}
and
if the function makes a putback position available
and if
\tcode{traits::eq(to_char_type(c),gptr()[-1])}
returns
\tcode{true},
decrements the next pointer for the input sequence,
\tcode{gptr()}.

Returns:
\tcode{c}.

\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{false}
and
if the function makes a putback position available
and if the function is permitted to assign to the putback position,
decrements the next pointer for the input sequence,
and stores \tcode{c} there.

Returns:
\tcode{c}.

\item
If
\tcode{traits::eq_int_type(c,traits::eof())}
returns
\tcode{true},
and if either the input sequence has a putback position available or
the function makes a putback position available,
decrements the next pointer for the input sequence,
\tcode{gptr()}.

Returns:
\tcode{traits::not_eof(c)}.
\end{itemize}

\pnum
\returns
\tcode{traits::eof()}
to indicate failure.

\pnum
\notes
If
\tcode{is_open() == false},
the function always fails.

\pnum
The function does not put back a character directly to the input sequence.

\pnum
If the function can succeed in more than one of these ways, it is
unspecified which way is chosen.
The function can alter the number of putback positions available as a result of any call.
\end{itemdescr}

\indexlibrary{\idxcode{overflow}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
int_type overflow(int_type c = traits::eof());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Behaves according to the description of
\tcode{basic_streambuf<charT,traits>::overflow(c)},
except that the behavior of ``consuming characters'' is performed by first
converting as if by:

\begin{codeblock}
charT* b = pbase();
charT* p = pptr();
charT* end;
char   xbuf[XSIZE];
char*  xbuf_end;
codecvt_base::result r =
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);
\end{codeblock}

and then
\begin{itemize}
\item If \tcode{r == codecvt_base::error} then fail.
\item If \tcode{r == codecvt_base::noconv} then output characters from
\tcode{b} up to (and not including) \tcode{p}.
\item If \tcode{r == codecvt_base::partial} then output to the file characters from
\tcode{xbuf} up to \tcode{xbuf_end}, and repeat using characters from
\tcode{end} to \tcode{p}. If output fails, fail (without repeating).
\item Otherwise output from \tcode{xbuf} to \tcode{xbuf_end}, and fail if output fails.
At this point if \tcode{b != p} and \tcode{b == end} (\tcode{xbuf} isn't large
enough) then increase \tcode{XSIZE} and repeat from the beginning.
\end{itemize}

\pnum
\returns
\tcode{traits::not_eof(c)}
to indicate success, and
\tcode{traits::eof()}
to indicate failure.
If
\tcode{is_open() == false},
the function always fails.
\end{itemdescr}

\indexlibrary{\idxcode{setbuf}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
basic_streambuf* setbuf(char_type* s, streamsize n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If
\tcode{setbuf(0,0)}
is called on a stream before any I/O has occurred on that stream, the
stream becomes unbuffered.
Otherwise the results are \impldef{effect of calling \tcode{basic_filebuf::setbuf} with
non-zero arguments}.
``Unbuffered'' means that
\tcode{pbase()}
and
\tcode{pptr()}
always return null
and output to the file should appear as soon as possible.
\end{itemdescr}

\indexlibrary{\idxcode{seekoff}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
pos_type seekoff(off_type off, ios_base::seekdir way,
    ios_base::openmode which = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Let
\tcode{width}
denote
\tcode{a_codecvt.encoding()}.
If
\tcode{is_open() == false},
or
\tcode{off != 0 \&\& width <= 0},
then the positioning operation fails.
Otherwise, if
\tcode{way != basic_ios::cur}
or
\tcode{off != 0},
and if the last operation was output,
then update the output sequence and write any unshift sequence.
Next, seek to the new position: if
\tcode{width > 0},
call
\tcode{std::fseek(file, width * off, whence)},
otherwise call
\tcode{std::fseek(file, 0, whence)}.

\pnum
\notes
``The last operation was output'' means either
the last virtual operation was overflow or
the put buffer is non-empty.
``Write any unshift sequence'' means,
if
\tcode{width}
if less than zero then call
\tcode{a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)}
and output the resulting unshift sequence.
The function determines one of three values for the
argument \tcode{whence}, of type
\tcode{int},
as indicated in Table~\ref{tab:iostreams.seekoff.effects}.

\begin{libtab2}{\tcode{seekoff} effects}{tab:iostreams.seekoff.effects}
{ll}{\tcode{way} Value}{\tcode{stdio} Equivalent}
\tcode{basic_ios::beg}  & \tcode{SEEK_SET}  \\
\tcode{basic_ios::cur}  & \tcode{SEEK_CUR}  \\
\tcode{basic_ios::end}  & \tcode{SEEK_END}  \\
\end{libtab2}

\pnum
\returns
A newly constructed
\tcode{pos_type}
object that stores the resultant
stream position, if possible.
If the positioning operation fails, or
if the object cannot represent the resultant stream position,
returns
\tcode{pos_type(off_type(-1))}.
\end{itemdescr}

\indexlibrary{\idxcode{seekpos}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
pos_type seekpos(pos_type sp,
    ios_base::openmode which = ios_base::in | ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
Alters the file position, if possible, to correspond to the position
stored in \tcode{sp} (as described below).
Altering the file position performs as follows:
\begin{enumerate}
\item
if
\tcode{(om \& ios_base::out) != 0},
then update the output sequence and
write any unshift sequence;
\item
set the file position to \tcode{sp};
\item
if
\tcode{(om \& ios_base::in) != 0},
then update the input sequence;
\end{enumerate}
where \tcode{om} is the open mode passed to the last call to
\tcode{open()}.
The operation fails if
\tcode{is_open()}
returns false.

\pnum
If \tcode{sp} is an invalid stream position, or if the function positions
neither sequence, the positioning operation fails.
If \tcode{sp} has not been obtained by a previous successful call to one of
the positioning functions
(\tcode{seekoff}
or
\tcode{seekpos})
on the same file the effects are undefined.

\pnum
\returns
\tcode{sp}
on success.
Otherwise returns
\tcode{pos_type(off_type(-1))}.
\end{itemdescr}

\indexlibrary{\idxcode{sync}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
int sync();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
If a put area exists, calls
\tcode{filebuf::overflow}
to write the characters to the file.
If a get area exists, the effect is \impldef{effect of calling
\tcode{basic_filebuf::sync} when a get area exists}.
\end{itemdescr}

\indexlibrary{\idxcode{imbue}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
void imbue(const locale& loc);
\end{itemdecl}

\begin{itemdescr}
\pnum
\precondition
If the file is not positioned at its beginning and the encoding of the current
locale as determined by
\tcode{a_codecvt.encoding()}
is state-dependent~(\ref{locale.codecvt.virtuals})
then that facet is the same as
the corresponding facet of \tcode{loc}.

\pnum
\effects
Causes characters inserted or extracted after this call
to be converted according to \tcode{loc} until another call of
\tcode{imbue}.

\pnum
\note
This may require reconversion of previously converted characters.
This in turn may require the implementation to be able to reconstruct
the original contents of the file.
\end{itemdescr}

\rSec3[ifstream]{Class template \tcode{basic_ifstream}}

\indexlibrary{\idxcode{basic_ifstream}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_ifstream : public basic_istream<charT,traits> {
  public:
    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;

    // \ref{ifstream.cons} Constructors:
    basic_ifstream();
    explicit basic_ifstream(const char* s,
        ios_base::openmode mode = ios_base::in);
    explicit basic_ifstream(const string& s,
        ios_base::openmode mode = ios_base::in);
    basic_ifstream(const basic_ifstream& rhs) = delete;
    basic_ifstream(basic_ifstream&& rhs);

    // \ref{ifstream.assign} Assign/swap:
    basic_ifstream& operator=(const basic_ifstream& rhs) = delete;
    basic_ifstream& operator=(basic_ifstream&& rhs);
    void swap(basic_ifstream& rhs);

    // \ref{ifstream.members} Members:
    basic_filebuf<charT,traits>* rdbuf() const;

    bool is_open() const;
    void open(const char* s, ios_base::openmode mode = ios_base::in);
    void open(const string& s, ios_base::openmode mode = ios_base::in);
    void close();
  private:
    basic_filebuf<charT,traits> sb; // \expos
  };

  template <class charT, class traits>
  void swap(basic_ifstream<charT, traits>& x,
            basic_ifstream<charT, traits>& y);
}
\end{codeblock}

\pnum
The class
\tcode{basic_ifstream<charT, traits>}
supports reading from named files.
It uses a
\tcode{basic_filebuf<\brk{}charT, traits>}
object to control the associated
sequence.
For the sake of exposition, the maintained data is presented here as:

\begin{itemize}
\item
\tcode{sb}, the \tcode{filebuf} object.
\end{itemize}

\rSec3[ifstream.cons]{\tcode{basic_ifstream} constructors}

\indexlibrary{\idxcode{basic_ifstream}!\idxcode{basic_ifstream}}%
\begin{itemdecl}
basic_ifstream();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ifstream<charT,traits>},
initializing the base class with
\tcode{basic_istream(\&sb)}
and initializing \tcode{sb} with
\tcode{basic_filebuf<charT,traits>())}~(\ref{istream.cons},
\ref{filebuf.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{basic_ifstream}!constructor}%
\begin{itemdecl}
explicit basic_ifstream(const char* s,
    ios_base::openmode mode = ios_base::in);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ifstream},
initializing the base class with
\tcode{basic_istream(\&sb)}
and initializing \tcode{sb} with
\tcode{basic_filebuf<charT, traits>())}~(\ref{istream.cons},
\ref{filebuf.cons}),
then calls
\tcode{rdbuf()->open(s, mode | ios_base::in)}.
If that function returns a null pointer, calls
\tcode{setstate(failbit)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_ifstream}!constructor}%
\begin{itemdecl}
explicit basic_ifstream(const string& s,
    ios_base::openmode mode = ios_base::in);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects the same as \tcode{basic_ifstream(s.c_str(), mode)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_ifstream}!constructor}%
\begin{itemdecl}
basic_ifstream(basic_ifstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}. This
is accomplished by move constructing the base class, and the contained
\tcode{basic_filebuf}. Next
\tcode{basic_istream<charT,traits>::set_rdbuf(\&sb)} is called to install
the contained \tcode{basic_filebuf}.
\end{itemdescr}

\rSec3[ifstream.assign]{Assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_ifstream}}%
\indexlibrary{\idxcode{basic_ifstream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_ifstream& operator=(basic_ifstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move assigns the base and members of \tcode{*this} from the base and corresponding
members of \tcode{rhs}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_ifstream}}%
\indexlibrary{\idxcode{basic_ifstream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_ifstream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Exchanges the state of \tcode{*this}
and \tcode{rhs} by calling
\tcode{basic_istream<charT,traits>::swap(rhs)} and
\tcode{sb.swap(rhs.sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_ifstream}}%
\indexlibrary{\idxcode{basic_ifstream}!\idxcode{swap}}%
\begin{itemdecl}
template <class charT, class traits>
void swap(basic_ifstream<charT, traits>& x,
          basic_ifstream<charT, traits>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[ifstream.members]{Member functions}

\indexlibrary{\idxcode{rdbuf}!\idxcode{basic_ifstream}}%
\begin{itemdecl}
basic_filebuf<charT,traits>* rdbuf() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{const_cast<basic_filebuf<charT,traits>*>(\&sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{is_open}!\idxcode{basic_ifstream}}%
\begin{itemdecl}
bool is_open() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rdbuf()->is_open()}.
\end{itemdescr}

\indexlibrary{\idxcode{open}!\idxcode{basic_ifstream}}%
\begin{itemdecl}
void open(const char* s, ios_base::openmode mode = ios_base::in);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->open(s, mode | ios_base::in)}.
If that function does not return a null pointer
calls \tcode{clear()},
otherwise calls
\tcode{setstate(\brk{}fail\-bit)}
(which may throw
\tcode{ios_base::failure} (\ref{iostate.flags})).
\end{itemdescr}

\indexlibrary{\idxcode{open}!\idxcode{basic_ifstream}}%
\begin{itemdecl}
void open(const string& s, ios_base::openmode mode = ios_base::in);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects  calls \tcode{open(s.c_str(), mode)}.
\end{itemdescr}

\indexlibrary{\idxcode{close}!\idxcode{basic_ifstream}}%
\begin{itemdecl}
void close();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->close()}
and, if that function returns
a null pointer,
calls
\tcode{setstate(failbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).
\end{itemdescr}

\rSec3[ofstream]{Class template \tcode{basic_ofstream}}

\indexlibrary{\idxcode{basic_ofstream}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits = char_traits<charT> >
  class basic_ofstream : public basic_ostream<charT,traits> {
  public:
    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;

    // \ref{ofstream.cons} Constructors:
    basic_ofstream();
    explicit basic_ofstream(const char* s,
        ios_base::openmode mode = ios_base::out);
    explicit basic_ofstream(const string& s,
        ios_base::openmode mode = ios_base::out);
    basic_ofstream(const basic_ofstream& rhs) = delete;
    basic_ofstream(basic_ofstream&& rhs);

    // \ref{ofstream.assign} Assign/swap:
    basic_ofstream& operator=(const basic_ofstream& rhs) = delete;
    basic_ofstream& operator=(basic_ofstream&& rhs);
    void swap(basic_ofstream& rhs);

    // \ref{ofstream.members} Members:
    basic_filebuf<charT,traits>* rdbuf() const;

    bool is_open() const;
    void open(const char* s, ios_base::openmode mode = ios_base::out);
    void open(const string& s, ios_base::openmode mode = ios_base::out);
    void close();
  private:
    basic_filebuf<charT,traits> sb; // \expos
  };

  template <class charT, class traits>
  void swap(basic_ofstream<charT, traits>& x,
            basic_ofstream<charT, traits>& y);
}
\end{codeblock}

\pnum
The class
\tcode{basic_ofstream<charT, traits>}
supports writing to named files.
It uses a
\tcode{basic_filebuf<\brk{}charT, traits>}
object to control the associated
sequence.
For the sake of exposition, the maintained data is presented here as:
\begin{itemize}
\item
\tcode{sb}, the \tcode{filebuf} object.
\end{itemize}

\rSec3[ofstream.cons]{\tcode{basic_ofstream} constructors}

\indexlibrary{\idxcode{basic_ofstream}!\idxcode{basic_ofstream}}%
\begin{itemdecl}
basic_ofstream();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ofstream<charT,traits>},
initializing the base class with
\tcode{basic_ostream(\&sb)}
and initializing \tcode{sb} with
\tcode{basic_filebuf<charT,traits>())}~(\ref{ostream.cons},
\ref{filebuf.cons}).
\end{itemdescr}

\indexlibrary{\idxcode{basic_ofstream}!constructor}%
\begin{itemdecl}
explicit basic_ofstream(const char* s,
    ios_base::openmode mode = ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_ofstream<charT,traits>},
initializing the base class with
\tcode{basic_ostream(\&sb)}
and initializing \tcode{sb} with
\tcode{basic_filebuf<charT,traits>())}~(\ref{ostream.cons},
\ref{filebuf.cons}),
then calls
\tcode{rdbuf()->open(s, mode|ios_base::out)}.
If that function returns a null pointer, calls
\tcode{setstate(\brk{}fail\-bit)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_ofstream}!constructor}%
\begin{itemdecl}
explicit basic_ofstream(const string& s,
    ios_base::openmode mode = ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects the same as \tcode{basic_ofstream(s.c_str(), mode);}
\end{itemdescr}

\indexlibrary{\idxcode{basic_ofstream}!constructor}%
\begin{itemdecl}
basic_ofstream(basic_ofstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}. This
is accomplished by move constructing the base class, and the contained
\tcode{basic_filebuf}. Next
\tcode{basic_ostream<charT,traits>::set_rdbuf(\&sb)} is called to install
the contained \tcode{basic_filebuf}.
\end{itemdescr}

\rSec3[ofstream.assign]{Assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_ofstream}}%
\indexlibrary{\idxcode{basic_ofstream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_ofstream& operator=(basic_ofstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move assigns the base and members of \tcode{*this} from the base and corresponding
members of \tcode{rhs}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_ofstream}}%
\indexlibrary{\idxcode{basic_ofstream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_ofstream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Exchanges the state of \tcode{*this}
and \tcode{rhs} by calling
\tcode{basic_ostream<charT,traits>::swap(rhs)} and
\tcode{sb.swap(rhs.sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_ofstream}}%
\indexlibrary{\idxcode{basic_ofstream}!\idxcode{swap}}%
\begin{itemdecl}
template <class charT, class traits>
void swap(basic_ofstream<charT, traits>& x,
          basic_ofstream<charT, traits>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[ofstream.members]{Member functions}

\indexlibrary{\idxcode{rdbuf}!\idxcode{basic_ofstream}}%
\begin{itemdecl}
basic_filebuf<charT,traits>* rdbuf() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{const_cast<basic_filebuf<charT,traits>*>(\&sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{is_open}!\idxcode{basic_ofstream}}%
\begin{itemdecl}
bool is_open() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rdbuf()->is_open()}.
\end{itemdescr}

\indexlibrary{\idxcode{open}!\idxcode{basic_ofstream}}%
\begin{itemdecl}
void open(const char* s, ios_base::openmode mode = ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->open(s, mode | ios_base::out)}.
If that function does not return a null pointer
calls \tcode{clear()},
otherwise calls
\tcode{setstate(\brk{}fail\-bit)}
(which may throw
\tcode{ios_base::failure} (\ref{iostate.flags})).
\end{itemdescr}

\indexlibrary{\idxcode{close}!\idxcode{basic_ofstream}}%
\begin{itemdecl}
void close();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->close()}
and, if that function fails (returns a null pointer), calls
\tcode{setstate(\brk{}failbit)}
(which may throw
\tcode{ios_base::failure}~(\ref{iostate.flags})).
\end{itemdescr}

\indexlibrary{\idxcode{open}!\idxcode{basic_ofstream}}%
\begin{itemdecl}
void open(const string& s, ios_base::openmode mode = ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects calls \tcode{open(s.c_str(), mode);}
\end{itemdescr}

\rSec3[fstream]{Class template \tcode{basic_fstream}}

\indexlibrary{\idxcode{basic_fstream}}%
\begin{codeblock}
namespace std {
  template <class charT, class traits=char_traits<charT> >
  class basic_fstream
    : public basic_iostream<charT,traits> {

  public:
    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;

    // constructors/destructor
    basic_fstream();
    explicit basic_fstream(const char* s,
        ios_base::openmode mode = ios_base::in|ios_base::out);
    explicit basic_fstream(const string& s,
        ios_base::openmode mode = ios_base::in|ios_base::out);
    basic_fstream(const basic_fstream& rhs) = delete;
    basic_fstream(basic_fstream&& rhs);

    // \ref{fstream.assign} Assign/swap:
    basic_fstream& operator=(const basic_fstream& rhs) = delete;
    basic_fstream& operator=(basic_fstream&& rhs);
    void swap(basic_fstream& rhs);

    // Members:
    basic_filebuf<charT,traits>* rdbuf() const;
    bool is_open() const;
    void open(const char* s,
        ios_base::openmode mode = ios_base::in|ios_base::out);
    void open(const string& s,
        ios_base::openmode mode = ios_base::in|ios_base::out);
    void close();

  private:
    basic_filebuf<charT,traits> sb; // \expos
  };

  template <class charT, class traits>
  void swap(basic_fstream<charT, traits>& x,
            basic_fstream<charT, traits>& y);
}
\end{codeblock}

\pnum
The
class template
\tcode{basic_fstream<charT,traits>}
supports reading and writing from named files.
It uses a
\tcode{basic_filebuf<charT,traits>}
object to control the associated sequences.
For the sake of exposition, the maintained data is presented here as:
\begin{itemize}
\item
\tcode{sb}, the \tcode{basic_filebuf} object.
\end{itemize}

\rSec3[fstream.cons]{\tcode{basic_fstream} constructors}

\indexlibrary{\idxcode{basic_fstream}!\idxcode{basic_fstream}}%
\begin{itemdecl}
basic_fstream();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_fstream<charT,traits>},
initializing the base class with
\tcode{basic_iostream(\&sb)}
and initializing
\tcode{sb}
with
\tcode{basic_filebuf<charT,traits>()}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_fstream}!constructor}%
\begin{itemdecl}
explicit basic_fstream(const char* s,
    ios_base::openmode mode = ios_base::in|ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{basic_fstream<charT, traits>},
initializing the base class with
\tcode{basic_iostream(\&sb)}
and initializing
\tcode{sb}
with
\tcode{basic_filebuf<charT, traits>()}.
Then calls
\tcode{rdbuf()->open(s, mode)}.
If that function returns a null pointer, calls
\tcode{setstate(failbit)}.
\end{itemdescr}

\indexlibrary{\idxcode{basic_fstream}!constructor}%
\begin{itemdecl}
explicit basic_fstream(const string& s,
    ios_base::openmode mode = ios_base::in|ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects the same as \tcode{basic_fstream(s.c_str(), mode);}
\end{itemdescr}

\indexlibrary{\idxcode{basic_fstream}!constructor}%
\begin{itemdecl}
basic_fstream(basic_fstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move constructs from the rvalue \tcode{rhs}. This
is accomplished by move constructing the base class, and the contained
\tcode{basic_filebuf}. Next
\tcode{basic_istream<charT,traits>::set_rdbuf(\&sb)} is called to install
the contained \tcode{basic_filebuf}.
\end{itemdescr}

\rSec3[fstream.assign]{Assign and swap}

\indexlibrary{\idxcode{operator=}!\idxcode{basic_fstream}}%
\indexlibrary{\idxcode{basic_fstream}!\idxcode{operator=}}%
\begin{itemdecl}
basic_fstream& operator=(basic_fstream&& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Move assigns the base and members of \tcode{*this} from the base and corresponding
members of \tcode{rhs}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_fstream}}%
\indexlibrary{\idxcode{basic_fstream}!\idxcode{swap}}%
\begin{itemdecl}
void swap(basic_fstream& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Exchanges the state of \tcode{*this}
and \tcode{rhs} by calling
\tcode{basic_iostream<charT,traits>::swap(rhs)} and
\tcode{sb.swap(rhs.sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{swap}!\idxcode{basic_fstream}}%
\indexlibrary{\idxcode{basic_fstream}!\idxcode{swap}}%
\begin{itemdecl}
template <class charT, class traits>
void swap(basic_fstream<charT, traits>& x,
          basic_fstream<charT, traits>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}

\rSec3[fstream.members]{Member functions}

\indexlibrary{\idxcode{rdbuf}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
basic_filebuf<charT,traits>* rdbuf() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{const_cast<basic_filebuf<charT,traits>*>(\&sb)}.
\end{itemdescr}

\indexlibrary{\idxcode{is_open}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
bool is_open() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rdbuf()->is_open()}.
\end{itemdescr}

\indexlibrary{\idxcode{open}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
void open(const char* s,
    ios_base::openmode mode = ios_base::in|ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->open(s,mode)}.
If that function does not return a null pointer calls \tcode{clear()},
otherwise calls
\tcode{setstate(failbit)},
(which may throw
\tcode{ios_base::failure})~(\ref{iostate.flags}).
\end{itemdescr}

\indexlibrary{\idxcode{open}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
void open(const string& s,
    ios_base::openmode mode = ios_base::in|ios_base::out);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects calls \tcode{open(s.c_str(), mode);}
\end{itemdescr}

\indexlibrary{\idxcode{close}!\idxcode{basic_filebuf}}%
\begin{itemdecl}
void close();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Calls
\tcode{rdbuf()->close()}
and, if that function returns
returns a null pointer,
calls
\tcode{setstate(\brk{}failbit)}~(\ref{iostate.flags})
(which may throw
\tcode{ios_base::failure}).
\end{itemdescr}

\rSec2[c.files]{C library files}

\pnum
Table~\ref{tab:iostreams.hdr.cstdio} describes header \tcode{<cstdio>}.
\enternote \Cpp does not define the function \tcode{gets}. \exitnote

\begin{libsyntab6}{cstdio}{tab:iostreams.hdr.cstdio}
\cspan{\macros}   \\
\tcode{BUFSIZ}    &
\tcode{FOPEN_MAX} &
\tcode{SEEK_CUR}  &
\tcode{TMP_MAX} &
\tcode{_IONBF}    &
\tcode{stdout}    \\
\tcode{EOF}     &
\tcode{L_tmpnam}  &
\tcode{SEEK_END}  &
\tcode{_IOFBF}    &
\tcode{stderr}    & \\
\tcode{FILENAME_MAX}  &
\tcode{NULL <cstdio>} &
\tcode{SEEK_SET}  &
\tcode{_IOLBF}    &
\tcode{stdin}   & \\ \rowsep
\types        &
 \tcode{FILE}   &
 \tcode{fpos_t}   &
 \tcode{size_t <cstdio>}  &&  \\ \rowsep

\cspan{\functions}  \\

\tcode{clearerr} &
\tcode{fopen} &
\tcode{fsetpos} &
\tcode{putchar} &
\tcode{snprintf} &
\tcode{vscanf} \\

\tcode{fclose} &
\tcode{fprintf} &
\tcode{ftell} &
\tcode{puts} &
\tcode{sprintf} &
\tcode{vsnprintf} \\

\tcode{feof} &
\tcode{fputc} &
\tcode{fwrite} &
\tcode{remove} &
\tcode{sscanf} &
\tcode{vsprintf} \\

\tcode{ferror} &
\tcode{fputs} &
\tcode{getc} &
\tcode{rename} &
\tcode{tmpfile} &
\tcode{vsscanf} \\

\tcode{fflush} &
\tcode{fread} &
\tcode{getchar} &
\tcode{rewind} &
\tcode{tmpnam} &\\

\tcode{fgetc} &
\tcode{freopen} &
\tcode{perror} &
\tcode{scanf} &
\tcode{ungetc} &\\

\tcode{fgetpos} &
\tcode{fscanf} &
\tcode{printf} &
\tcode{setbuf} &
\tcode{vfprintf} &\\

\tcode{fgets} &
\tcode{fseek} &
\tcode{putc} &
\tcode{setvbuf} &
\tcode{vprintf} &\\

\end{libsyntab6}

\pnum
Calls to the function \tcode{tmpnam} with an argument of \tcode{NULL} may
introduce a data race~(\ref{res.on.data.races}) with other calls to \tcode{tmpnam} with
an argument of \tcode{NULL}.

\xref
ISO C 7.9, Amendment 1 4.6.2.

\pnum
Table~\ref{tab:iostreams.hdr.cinttypes} describes header \tcode{<cinttypes>}. \enternote The
macros defined by \tcode{<cinttypes>} are provided unconditionally. In particular, the symbol
\tcode{__STDC_FORMAT_MACROS}, mentioned in footnote 182 of the C standard, plays no role in
\Cpp. \exitnote

\begin{libsyntab4}{cinttypes}{tab:iostreams.hdr.cinttypes}
\cspan{\macros}   \\
\cspan{\tcode{PRI\{d i o u x X\}[FAST LEAST]\{8 16 32 64\}}} \\
\cspan{\tcode{PRI\{d i o u x X\}\{MAX PTR\}}} \\
\cspan{\tcode{SCN\{d i o u x X\}[FAST LEAST]\{8 16 32 64\}}} \\
\cspan{\tcode{SCN\{d i o u x X\}\{MAX PTR\}}} \\ \rowsep
\types  & \tcode{imaxdiv_t} &&\\ \rowsep
\cspan{\functions}  \\
\tcode{abs} &
\tcode{imaxabs} &
\tcode{strtoimax} &
\tcode{wcstoimax} \\
\tcode{div} &
\tcode{imaxdiv} &
\tcode{strtoumax} &
\tcode{wcstoumax}\\
\end{libsyntab4}

\pnum
The contents of header \tcode{<cinttypes>} are the same as the Standard C Library header
\tcode{<inttypes.h>}, with the following changes:

\begin{itemize}
\item
the header \tcode{<cinttypes>} includes the header \tcode{<cstdint>} instead
of \tcode{<stdint.h>}, and

\item
if and only if the type \tcode{intmax_t} designates an extended integer 
type~(\ref{basic.fundamental}), the following function signatures are added:
\begin{codeblock}
intmax_t abs(intmax_t);
imaxdiv_t div(intmax_t, intmax_t);
\end{codeblock}
which shall have the same semantics as the function signatures
\tcode{intmax_t imaxabs(intmax_t)} and
\tcode{imaxdiv_t imaxdiv(intmax_t, intmax_t)}, respectively.
\end{itemize}
