cppdraft_translate/cppdraft/filebuf/virtuals.md

[filebuf.virtuals]

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;

1

#

Effects: Behaves the same asbasic_streambuf​::​showmanyc() ([streambuf.virtuals]).

2

#

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;

3

#

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];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_buf andintern_end.

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

🔗

int_type uflow() override;

4

#

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;

5

#

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

• (5.1)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse and 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(). Returns:c.

• (5.2)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse 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 c there. Returns:c.

• (5.3)

  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).

6

#

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

7

#

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

8

#

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

9

#

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;

10

#

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(); 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

• (10.1)

  If r == codecvt_base​::​error then fail.

• (10.2)

  If r == codecvt_base​::​noconv then output characters fromb up to (and not including) p.

• (10.3)

  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).

• (10.4)

  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.

Then establishes an observable checkpoint ([intro.abstract]).

11

#

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;

12

#

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;

13

#

Effects: Letwidth denotea_codecvt.encoding().

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

Otherwise, ifway != basic_ios​::​cur oroff != 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).

14

#

Returns: A newly constructedpos_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, returnspos_type(off_type(-1)).

15

#

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, ifwidth is 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.

Table 147 — seekoff effects [tab:filebuf.seekoff]

🔗 way Value	stdio Equivalent
🔗 basic_ios​::​beg	SEEK_SET
🔗 basic_ios​::​cur	SEEK_CUR
🔗 basic_ios​::​end	SEEK_END

🔗

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

16

#

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

Altering the file position performs as follows:

1.	if (om & ios_base​::​out) != 0, then update the output sequence and write any unshift sequence;
2.	set the file position to sp as if by a call to fsetpos;
3.	if (om & ios_base​::​in) != 0, then update the input sequence;

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

The operation fails ifis_open() returns false.

17

#

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 (seekoff orseekpos) on the same file the effects are undefined.

18

#

Returns: sp on success.

Otherwise returnspos_type(off_type(-1)).

🔗

int sync() override;

19

#

Effects: If a put area exists, callsfilebuf​::​overflow to 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;

20

#

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.

21

#

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

22

#

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.