122 lines
4.9 KiB
Markdown
122 lines
4.9 KiB
Markdown
[streambuf.virt.put]
|
||
|
||
# 31 Input/output library [[input.output]](./#input.output)
|
||
|
||
## 31.6 Stream buffers [[stream.buffers]](stream.buffers#streambuf.virt.put)
|
||
|
||
### 31.6.3 Class template basic_streambuf [[streambuf]](streambuf#virt.put)
|
||
|
||
#### 31.6.3.5 Virtual functions [[streambuf.virtuals]](streambuf.virtuals#streambuf.virt.put)
|
||
|
||
#### 31.6.3.5.5 Put area [streambuf.virt.put]
|
||
|
||
[ð](#lib:xsputn,basic_streambuf)
|
||
|
||
`streamsize xsputn(const char_type* s, streamsize n);
|
||
`
|
||
|
||
[1](#1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4003)
|
||
|
||
*Effects*: Writes up to n characters to the output sequence as if
|
||
by repeated calls tosputc(c)[.](#1.sentence-1)
|
||
|
||
The characters written are obtained from successive elements of
|
||
the array whose first element is designated by s[.](#1.sentence-2)
|
||
|
||
Writing stops when either n characters have been written or
|
||
a call tosputc(c) would returntraits::eof()[.](#1.sentence-3)
|
||
|
||
It is unspecified whether the function calls overflow() when pptr() == epptr() becomes true or whether it achieves the same effects by other means[.](#1.sentence-4)
|
||
|
||
[2](#2)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4017)
|
||
|
||
*Returns*: The number of characters written[.](#2.sentence-1)
|
||
|
||
[ð](#lib:overflow,basic_streambuf)
|
||
|
||
`int_type overflow(int_type c = traits::eof());
|
||
`
|
||
|
||
[3](#3)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4028)
|
||
|
||
*Effects*: Consumes some initial subsequence of the characters of the[*pending sequence*](#def:pending_sequence)[.](#3.sentence-1)
|
||
|
||
The pending sequence is defined as the concatenation of
|
||
|
||
- [(3.1)](#3.1)
|
||
|
||
the empty sequence if pbase() is null, otherwise thepptr() - pbase() characters beginning atpbase(), followed by
|
||
|
||
- [(3.2)](#3.2)
|
||
|
||
the empty sequence
|
||
iftraits::eq_int_type(c, traits::eof()) returnstrue, otherwise the sequence consisting of c[.](#3.sentence-2)
|
||
|
||
[4](#4)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4047)
|
||
|
||
*Preconditions*: Every overriding definition of this virtual function
|
||
obeys the following constraints:
|
||
|
||
- [(4.1)](#4.1)
|
||
|
||
The effect of consuming a character on the associated output sequence is
|
||
specified[.](#4.1.sentence-1)[270](#footnote-270 "That is, for each class derived from a specialization of basic_streambuf in this Clause ([stringbuf], [filebuf]), a specification of how consuming a character effects the associated output sequence is given. There is no requirement on a program-defined class.")
|
||
|
||
- [(4.2)](#4.2)
|
||
|
||
Letr be the number of characters in the pending sequence not consumed[.](#4.2.sentence-1)
|
||
Ifr is nonzero thenpbase() andpptr() are set so that:pptr() - pbase() == r and the r characters starting atpbase() are the associated output stream[.](#4.2.sentence-2)
|
||
In case r is zero (all characters of the pending sequence have been consumed)
|
||
then eitherpbase() is set tonullptr,
|
||
orpbase() andpptr() are both set to the same non-null value[.](#4.2.sentence-3)
|
||
|
||
- [(4.3)](#4.3)
|
||
|
||
The function may fail if either
|
||
appending some character to the associated output stream fails or
|
||
if it is unable to establishpbase() andpptr() according to the above rules[.](#4.3.sentence-1)
|
||
|
||
[5](#5)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4097)
|
||
|
||
*Returns*: traits::eof() or throws an exception
|
||
if the function fails[.](#5.sentence-1)
|
||
|
||
Otherwise,
|
||
returns some value other thantraits::eof() to indicate success[.](#5.sentence-2)[271](#footnote-271 "Typically, overflow returns c to indicate success, except when traits::eq_int_type(c, traits::eof()) returns true, in which case it returns traits::not_eof(c).")
|
||
|
||
[6](#6)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4118)
|
||
|
||
*Default behavior*: Returnstraits::eof()[.](#6.sentence-1)
|
||
|
||
[7](#7)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L4123)
|
||
|
||
*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[.](#7.sentence-1)
|
||
|
||
[270)](#footnote-270)[270)](#footnoteref-270)
|
||
|
||
That is, for each class derived from a specialization ofbasic_streambuf in this Clause ([[stringbuf]](stringbuf "31.8.2 Class template basic_stringbuf"), [[filebuf]](filebuf "31.10.3 Class template basic_filebuf")),
|
||
a specification of how consuming a character effects the associated output sequence is given[.](#footnote-270.sentence-1)
|
||
|
||
There is no requirement on a program-defined class[.](#footnote-270.sentence-2)
|
||
|
||
[271)](#footnote-271)[271)](#footnoteref-271)
|
||
|
||
Typically,overflow returns c to indicate success, except whentraits::eq_int_type(c, traits::eof()) returnstrue,
|
||
in which case it returnstraits::not_eof(c)[.](#footnote-271.sentence-1)
|