[filebuf.virtuals] (original) (raw)

31 Input/output library [input.output]

31.10 File-based streams [file.streams]

31.10.3 Class template basic_filebuf [filebuf]

31.10.3.5 Overridden virtual functions [filebuf.virtuals]

streamsize showmanyc() override;

Remarks: An implementation may provide an overriding definition for this function signature if it can determine whether more characters can be read from the input sequence.

int_type underflow() override;

Effects: Behaves according to the description ofbasic_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 (extern_buf) and then as if by doing:char extern_buf[XSIZE];const 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);

This shall be done in such a way that the class can recover the position (fpos_t) corresponding to each character betweenintern_bufandintern_end.

If the value ofrindicates thata_codecvt.in()ran out of space inintern_buf, retry with a largerintern_buf.

int_type uflow() override;

Effects: Behaves according to the description ofbasic_streambuf<charT, traits>​::​uflow(), with the specialization that a sequence of characters is read from the input with the same method as used byunderflow.

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

Effects: Puts back the character designated by c to the input sequence, if possible, in one of three ways:

• Iftraits​::​eq_int_type(c, traits​::​eof())returnsfalseand if the function makes a putback position available and iftraits​::​eq(to_char_type(c), gptr()[-1])returnstrue, decrements the next pointer for the input sequence,gptr().
• Iftraits​::​eq_int_type(c, traits​::​eof())returnsfalseand 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 c there.
• Iftraits​::​eq_int_type(c, traits​::​eof())returnstrue, 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,gptr().
  Returns:traits​::​not_eof(c).

Returns: As specified above, ortraits​::​eof()to indicate failure.

Remarks: Ifis_open() == false, the function always fails.

The function does not put back a character directly to the input sequence.

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.

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

Effects: Behaves according to the description ofbasic_streambuf<charT, traits>​::​overflow(c), except that the behavior of “consuming characters” is performed by first converting as if by:charT* b = pbase(); charT* p = pptr();const charT* end;char xbuf[XSIZE];char* xbuf_end; codecvt_base::result r = a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);and then

• If r == codecvt_base​::​error then fail.
• If r == codecvt_base​::​noconv then output characters fromb up to (and not including) p.
• If r == codecvt_base​::​partial then output to the file characters fromxbuf up to xbuf_end, and repeat using characters fromend to p.
  If output fails, fail (without repeating).
• Otherwise output from xbuf to xbuf_end, and fail if output fails.
  At this point if b != p and b == end (xbuf isn't large enough) then increase XSIZE and repeat from the beginning.

Returns: traits​::​not_eof(c)to indicate success, andtraits​::​eof()to indicate failure.

Ifis_open() == false, the function always fails.

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

Effects: Ifsetbuf(0, 0)is called on a stream before any I/O has occurred on that stream, the stream becomes unbuffered.

Otherwise the results are implementation-defined.

“Unbuffered” means thatpbase()andpptr()always return null and output to the file should appear as soon as possible.

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

Effects: Letwidthdenotea_codecvt.encoding().

Ifis_open() == false, oroff != 0 && width <= 0, then the positioning operation fails.

Otherwise, ifway != basic_ios​::​curoroff != 0, and if the last operation was output, then update the output sequence and write any unshift sequence.

Next, seek to the new position: ifwidth > 0, callfseek(file, width * off, whence), otherwise callfseek(file, 0, whence).

Returns: A newly constructedpos_typeobject that stores the resultant stream position, if possible.

If the positioning operation fails, or if the object cannot represent the resultant stream position, returnspos_type(off_type(-1)).

Remarks: “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, ifwidthis less than zero then calla_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)and output the resulting unshift sequence.

The function determines one of three values for the argument whence, of typeint, as indicated in Table 147.

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

Alters the file position, if possible, to correspond to the position stored in sp (as described below).

Altering the file position performs as follows:

where om is the open mode passed to the last call toopen().

The operation fails ifis_open()returns false.

If sp is an invalid stream position, or if the function positions neither sequence, the positioning operation fails.

If sp has not been obtained by a previous successful call to one of the positioning functions (seekofforseekpos) on the same file the effects are undefined.

Returns: spon success.

Otherwise returnspos_type(off_type(-1)).

Effects: If a put area exists, callsfilebuf​::​overflowto write the characters to the file, then flushes the file as if by calling fflush(file).

If a get area exists, the effect is implementation-defined.

void imbue(const locale& loc) override;

Preconditions: If the file is not positioned at its beginning and the encoding of the current locale as determined bya_codecvt.encoding()is state-dependent ([locale.codecvt.virtuals]) then that facet is the same as the corresponding facet of loc.

Effects: Causes characters inserted or extracted after this call to be converted according to loc until another call ofimbue.

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