[streambuf] (original) (raw)

31 Input/output library [input.output]

31.6 Stream buffers [stream.buffers]

31.6.3 Class template basic_streambuf [streambuf]

31.6.3.1 General [streambuf.general]

namespace std { template<class charT, class traits = char_traits<charT>> class basic_streambuf { public: using char_type = charT;using int_type = typename traits::int_type;using pos_type = typename traits::pos_type;using off_type = typename traits::off_type;using traits_type = traits;virtual ~basic_streambuf(); locale pubimbue(const locale& loc); locale getloc() const; basic_streambuf* 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(); streamsize in_avail(); int_type snextc(); int_type sbumpc(); int_type sgetc(); streamsize sgetn(char_type* s, streamsize n); int_type sputbackc(char_type c); int_type sungetc(); 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); 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); char_type* pbase() const; char_type* pptr() const; char_type* epptr() const;void pbump(int n);void setp(char_type* pbeg, char_type* pend);virtual void imbue(const locale& loc);virtual basic_streambuf* 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 streamsize showmanyc();virtual streamsize xsgetn(char_type* s, streamsize n);virtual int_type underflow();virtual int_type uflow();virtual int_type pbackfail(int_type c = traits::eof());virtual streamsize xsputn(const char_type* s, streamsize n);virtual int_type overflow(int_type c = traits::eof());};}

The class templatebasic_streambufserves as a base class for deriving variousstream bufferswhose objects each control twocharacter sequences:

31.6.3.2 Constructors [streambuf.cons]

Effects: Initializes:267

Remarks: Once thegetloc()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 memberimbueis called.

basic_streambuf(const basic_streambuf& rhs);

Postconditions:

31.6.3.3 Public member functions [streambuf.members]

31.6.3.3.1 Locales [streambuf.locales]

locale pubimbue(const locale& loc);

Effects: Callsimbue(loc).

Postconditions: loc == getloc().

Returns: Previous value ofgetloc().

Returns: Ifpubimbue()has ever been called, then the last value of loc supplied, otherwise the current global locale,locale(), in effect at the time of construction.

If called afterpubimbue()has been called but beforepubimbuehas returned (i.e., from within the call ofimbue()) then it returns the previous value.

31.6.3.3.2 Buffer management and positioning [streambuf.buffer]

basic_streambuf* 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);

Returns: seekoff(off, way, which).

pos_type pubseekpos(pos_type sp, ios_base::openmode which= ios_base::in | ios_base::out);

Returns: seekpos(sp, which).

31.6.3.3.3 Get area [streambuf.pub.get]

Returns: If a read position is available, returnsegptr() - gptr().

Returns: If that function returnstraits​::​eof(), returnstraits​::​eof().

Otherwise, returnssgetc().

Effects: If the input sequence read position is not available, returnsuflow().

Otherwise, returnstraits​::​to_int_type(*gptr())and increments the next pointer for the input sequence.

Returns: If the input sequence read position is not available, returnsunderflow().

Otherwise, returnstraits​::​to_int_type(*gptr()).

streamsize sgetn(char_type* s, streamsize n);

31.6.3.3.4 Putback [streambuf.pub.pback]

int_type sputbackc(char_type c);

Effects: If the input sequence putback position is not available, or iftraits​::​eq(c, gptr()[-1])is false, returnspbackfail(traits​::​to_int_type(c)).

Otherwise, decrements the next pointer for the input sequence and returnstraits​::​to_int_type(*gptr()).

Effects: If the input sequence putback position is not available, returnspbackfail().

Otherwise, decrements the next pointer for the input sequence and returnstraits​::​to_int_type(*gptr()).

31.6.3.3.5 Put area [streambuf.pub.put]

int_type sputc(char_type c);

Effects: If the output sequence write position is not available, returnsoverflow(traits​::​to_int_type(c)).

Otherwise, stores c at the next pointer for the output sequence, increments the pointer, and returnstraits​::​to_int_type(c).

streamsize sputn(const char_type* s, streamsize n);

31.6.3.4 Protected member functions [streambuf.protected]

31.6.3.4.1 Assignment [streambuf.assign]

basic_streambuf& operator=(const basic_streambuf& rhs);

Postconditions:

void swap(basic_streambuf& rhs);

Effects: Swaps the data members of rhsand *this.

31.6.3.4.2 Get area access [streambuf.get.area]

char_type* eback() const;

Returns: The beginning pointer for the input sequence.

Returns: The next pointer for the input sequence.

char_type* egptr() const;

Returns: The end pointer for the input sequence.

Effects: Adds n to the next pointer for the input sequence.

void setg(char_type* gbeg, char_type* gnext, char_type* gend);

Preconditions: [gbeg, gnext), [gbeg, gend), and [gnext, gend) are all valid ranges.

Postconditions: gbeg == eback(),gnext == gptr(), andgend == egptr() are all true.

31.6.3.4.3 Put area access [streambuf.put.area]

char_type* pbase() const;

Returns: The beginning pointer for the output sequence.

Returns: The next pointer for the output sequence.

char_type* epptr() const;

Returns: The end pointer for the output sequence.

Effects: Adds n to the next pointer for the output sequence.

void setp(char_type* pbeg, char_type* pend);

Preconditions: [pbeg, pend) is a valid range.

Postconditions: pbeg == pbase(),pbeg == pptr(), andpend == epptr() are all true.

31.6.3.5 Virtual functions [streambuf.virtuals]

31.6.3.5.1 Locales [streambuf.virt.locales]

void imbue(const locale&);

Effects: Change any translations based on locale.

Remarks: 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.

Default behavior: Does nothing.

31.6.3.5.2 Buffer management and positioning [streambuf.virt.buffer]

basic_streambuf* setbuf(char_type* s, streamsize n);

Default behavior: Does nothing.

Returnsthis.

pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which= ios_base::in | ios_base::out);

Effects: Alters the stream positions within one or more of the controlled sequences in a way that is defined separately for each class derived frombasic_streambufin this Clause ([stringbuf.virtuals], [filebuf.virtuals]).

Default behavior: Returnspos_type(off_type(-1)).

pos_type seekpos(pos_type sp, ios_base::openmode which= ios_base::in | ios_base::out);

Effects: Alters the stream positions within one or more of the controlled sequences in a way that is defined separately for each class derived frombasic_streambufin this Clause ([stringbuf], [filebuf]).

Default behavior: Returnspos_type(off_type(-1)).

Effects: Synchronizes the controlled sequences with the arrays.

That is, ifpbase()is non-null the characters betweenpbase()andpptr()are written to the controlled sequence.

The pointers may then be reset as appropriate.

Returns: -1 on failure.

What constitutes failure is determined by each derived class ([filebuf.virtuals]).

Default behavior: Returns zero.

31.6.3.5.3 Get area [streambuf.virt.get]

streamsize showmanyc();[268](#footnote-268 "The morphemes of showmanyc are “es-how-many-see”, not “show-manic”.")

Returns: An estimate of the number of characters available in the sequence, or .

If it returns a positive value, then successive calls tounderflow()will not returntraits​::​eof()until at least that number of characters have been extracted from the stream.

Ifshowmanyc()returns , then calls tounderflow()oruflow()will fail.269

Default behavior: Returns zero.

Remarks: Usestraits​::​eof().

streamsize xsgetn(char_type* s, streamsize n);

Effects: Assigns up to n characters to successive elements of the array whose first element is designated by s.

The characters assigned are read from the input sequence as if by repeated calls tosbumpc().

Assigning stops when either n characters have been assigned or a call tosbumpc()would returntraits​::​eof().

Returns: The number of characters assigned.270

Remarks: Usestraits​::​eof().

Thepending sequenceof characters is defined as the concatenation of

Theresult characteris the first character of the pending sequence if it is non-empty, otherwise the next character that would be read from the input sequence.

Thebackup sequenceis the empty sequence if eback() is null, otherwise the characters in [eback(), gptr()).

Effects: The function sets up thegptr()andegptr()such that if the pending sequence is non-empty, thenegptr()is non-null and the characters in [gptr(), egptr()) are the characters in the pending sequence, otherwise either gptr()is null orgptr() == egptr().

Ifeback()andgptr()are non-null then the function is not constrained as to their contents, but the “usual backup condition” is that either

Returns: traits​::​to_int_type(c), where c is the first_character_of thepending sequence, without moving the input sequence position past it.

If the pending sequence is null then the function returnstraits​::​eof()to indicate failure.

Default behavior: Returnstraits​::​eof().

Remarks: The public members ofbasic_streambufcall this virtual function only ifgptr()is null orgptr() >= egptr().

Preconditions: The constraints are the same as forunderflow(), except that the result character is transferred from the pending sequence to the backup sequence, and the pending sequence is not empty before the transfer.

Default behavior: Callsunderflow().

Ifunderflow()returnstraits​::​eof(), returnstraits​::​eof().

Otherwise, returns the value oftraits​::​to_int_type(*gptr())and increments the value of the next pointer for the input sequence.

Returns: traits​::​eof()to indicate failure.

31.6.3.5.4 Putback [streambuf.virt.pback]

int_type pbackfail(int_type c = traits::eof());

Thepending sequenceis defined as forunderflow(), with the modifications that

Postconditions: On return, the constraints ofgptr(),eback(), andpptr()are the same as forunderflow().

Returns: 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 cannot be set consistent with the constraints.

pbackfail()is called only when put back has really failed.

Returns some value other thantraits​::​eof()to indicate success.

Default behavior: Returnstraits​::​eof().

Remarks: The public functions ofbasic_streambufcall this virtual function only whengptr()is null,gptr() == eback(), ortraits​::​eq(traits​::​to_char_type(c), gptr()[-1])returnsfalse.

Other calls shall also satisfy that constraint.

31.6.3.5.5 Put area [streambuf.virt.put]

streamsize xsputn(const char_type* s, streamsize n);

Effects: Writes up to n characters to the output sequence as if by repeated calls tosputc(c).

The characters written are obtained from successive elements of the array whose first element is designated by s.

Writing stops when either n characters have been written or a call tosputc(c)would returntraits​::​eof().

It is unspecified whether the function calls overflow() when pptr() == epptr() becomes true or whether it achieves the same effects by other means.

Returns: The number of characters written.

int_type overflow(int_type c = traits::eof());

Effects: Consumes some initial subsequence of the characters of thepending sequence.

The pending sequence is defined as the concatenation of

Preconditions: Every overriding definition of this virtual function obeys the following constraints:

Returns: traits​::​eof()or throws an exception if the function fails.

Otherwise, returns some value other thantraits​::​eof()to indicate success.272

Default behavior: Returnstraits​::​eof().

Remarks: The member functionssputc()andsputn()call this function in case that no room can be found in the put buffer enough to accommodate the argument character sequence.