[spanbuf] # 31 Input/output library [[input.output]](./#input.output) ## 31.9 Span-based streams [[span.streams]](span.streams#spanbuf) ### 31.9.3 Class template basic_spanbuf [spanbuf] #### [31.9.3.1](#general) General [[spanbuf.general]](spanbuf.general) [🔗](#lib:basic_spanbuf) namespace std {template>class basic_spanbuf : public 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; // [[spanbuf.cons]](#cons "31.9.3.2 Constructors"), constructors basic_spanbuf() : basic_spanbuf(ios_base::in | ios_base::out) {}explicit basic_spanbuf(ios_base::openmode which): basic_spanbuf(std::span(), which) {}explicit basic_spanbuf(std::span s, ios_base::openmode which = ios_base::in | ios_base::out); basic_spanbuf(const basic_spanbuf&) = delete; basic_spanbuf(basic_spanbuf&& rhs); // [[spanbuf.assign]](#assign "31.9.3.3 Assignment and swap"), assignment and swap basic_spanbuf& operator=(const basic_spanbuf&) = delete; basic_spanbuf& operator=(basic_spanbuf&& rhs); void swap(basic_spanbuf& rhs); // [[spanbuf.members]](#members "31.9.3.4 Member functions"), member functions std::span span() const noexcept; void span(std::span s) noexcept; protected:// [[spanbuf.virtuals]](#virtuals "31.9.3.5 Overridden virtual functions"), overridden virtual functions basic_streambuf* setbuf(charT*, streamsize) override; pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out) override; pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override; private: ios_base::openmode *mode*; // *exposition only* std::span *buf*; // *exposition only*};} [1](#general-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10120) The class template basic_spanbuf is derived from basic_streambuf to associate possibly the input sequence and possibly the output sequence with a sequence of arbitrary characters[.](#general-1.sentence-1) The sequence is provided by an object of class span[.](#general-1.sentence-2) [2](#general-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10126) For the sake of exposition, the maintained data is presented here as: - [(2.1)](#general-2.1) ios_base​::​openmode *mode*, hasin set if the input sequence can be read, andout set if the output sequence can be written[.](#general-2.1.sentence-1) - [(2.2)](#general-2.2) std​::​span *buf* is the view to the underlying character sequence[.](#general-2.2.sentence-1) #### [31.9.3.2](#cons) Constructors [[spanbuf.cons]](spanbuf.cons) [🔗](#lib:basic_spanbuf,constructor) `explicit basic_spanbuf(std::span s, ios_base::openmode which = ios_base::in | ios_base::out); ` [1](#cons-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10147) *Effects*: Initializes the base class with basic_streambuf() ([[streambuf.cons]](streambuf.cons "31.6.3.2 Constructors")), and *mode* with which[.](#cons-1.sentence-1) Initializes the internal pointers as if calling span(s)[.](#cons-1.sentence-2) [🔗](#lib:basic_spanbuf,constructor_) `basic_spanbuf(basic_spanbuf&& rhs); ` [2](#cons-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10160) *Effects*: Initializes the base class with std​::​move(rhs) and*mode* with std​::​move(rhs.*mode*) and*buf* with std​::​move(rhs.*buf*)[.](#cons-2.sentence-1) The sequence pointers in *this (eback(), gptr(), egptr(),pbase(), pptr(), epptr()) obtain the values which rhs had[.](#cons-2.sentence-2) It isimplementation-defined whether rhs.*buf*.​empty() returns true after the move[.](#cons-2.sentence-3) [3](#cons-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10173) *Postconditions*: Let rhs_p refer to the state of rhs just prior to this construction[.](#cons-3.sentence-1) - [(3.1)](#cons-3.1) span().data() == rhs_p.span().data() - [(3.2)](#cons-3.2) span().size() == rhs_p.span().size() - [(3.3)](#cons-3.3) eback() == rhs_p.eback() - [(3.4)](#cons-3.4) gptr() == rhs_p.gptr() - [(3.5)](#cons-3.5) egptr() == rhs_p.egptr() - [(3.6)](#cons-3.6) pbase() == rhs_p.pbase() - [(3.7)](#cons-3.7) pptr() == rhs_p.pptr() - [(3.8)](#cons-3.8) epptr() == rhs_p.epptr() - [(3.9)](#cons-3.9) getloc() == rhs_p.getloc() #### [31.9.3.3](#assign) Assignment and swap [[spanbuf.assign]](spanbuf.assign) [🔗](#lib:operator=,basic_spanbuf) `basic_spanbuf& operator=(basic_spanbuf&& rhs); ` [1](#assign-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10198) *Effects*: Equivalent to:basic_spanbuf tmp{std::move(rhs)};this->swap(tmp);return *this; [🔗](#lib:swap,basic_spanbuf) `void swap(basic_spanbuf& rhs); ` [2](#assign-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10214) *Effects*: Equivalent to:basic_streambuf::swap(rhs); std::swap(*mode*, rhs.*mode*); std::swap(*buf*, rhs.*buf*); [🔗](#lib:swap,basic_spanbuf_) `template void swap(basic_spanbuf& x, basic_spanbuf& y); ` [3](#assign-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10231) *Effects*: Equivalent to x.swap(y)[.](#assign-3.sentence-1) #### [31.9.3.4](#members) Member functions [[spanbuf.members]](spanbuf.members) [🔗](#lib:span,basic_spanbuf) `std::span span() const noexcept; ` [1](#members-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10244) *Returns*: If ios_base​::​out is set in *mode*, returns std​::​span(pbase(), pptr()), otherwise returns *buf*[.](#members-1.sentence-1) [*Note [1](#members-note-1)*: In contrast to basic_stringbuf, the underlying sequence never grows and is not owned[.](#members-1.sentence-2) An owning copy can be obtained by converting the result to basic_string[.](#members-1.sentence-3) — *end note*] [🔗](#lib:span,basic_spanbuf_) `void span(std::span s) noexcept; ` [2](#members-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10264) *Effects*: *buf* = s[.](#members-2.sentence-1) Initializes the input and output sequences according to *mode*[.](#members-2.sentence-2) [3](#members-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10269) *Postconditions*: - [(3.1)](#members-3.1) If ios_base​::​out is set in *mode*,pbase() == s.data() && epptr() == pbase() + s.size() is true; * [(3.1.1)](#members-3.1.1) in addition, if ios_base​::​ate is set in *mode*,pptr() == pbase() + s.size() is true, * [(3.1.2)](#members-3.1.2) otherwise pptr() == pbase() is true[.](#members-3.1.sentence-1) - [(3.2)](#members-3.2) If ios_base​::​in is set in *mode*,eback() == s.data() && gptr() == eback() && egptr() == eback() + s.size() is true[.](#members-3.2.sentence-1) #### [31.9.3.5](#virtuals) Overridden virtual functions [[spanbuf.virtuals]](spanbuf.virtuals) [1](#virtuals-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10292) [*Note [1](#virtuals-note-1)*: Because the underlying buffer is of fixed size, neither overflow, underflow, nor pbackfail can provide useful behavior[.](#virtuals-1.sentence-1) — *end note*] [🔗](#lib:seekoff,basic_spanbuf) `pos_type seekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out) override; ` [2](#virtuals-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10306) *Effects*: Alters the stream position within one or both of the controlled sequences, if possible, as follows: - [(2.1)](#virtuals-2.1) If ios_base​::​in is set in which, positions the input sequence;xnext is gptr(), xbeg is eback()[.](#virtuals-2.1.sentence-1) - [(2.2)](#virtuals-2.2) If ios_base​::​out is set in which, positions the output sequence;xnext is pptr(), xbeg is pbase()[.](#virtuals-2.2.sentence-1) [3](#virtuals-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10319) If both ios_base​::​in and ios_base​::​out are set in which and way is ios_base​::​cur, the positioning operation fails[.](#virtuals-3.sentence-1) [4](#virtuals-4) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10324) For a sequence to be positioned, if its next pointer xnext (either gptr() or pptr()) is a null pointer and the new offset newoff as computed below is nonzero, the positioning operation fails[.](#virtuals-4.sentence-1) Otherwise, the function determines baseoff as a value of type off_type as follows: - [(4.1)](#virtuals-4.1) 0 when way is ios_base​::​beg; - [(4.2)](#virtuals-4.2) (pptr() - pbase()) for the output sequence, or(gptr() - eback()) for the input sequence when way is ios_base​::​cur; - [(4.3)](#virtuals-4.3) when way is ios_base​::​end : * [(4.3.1)](#virtuals-4.3.1) (pptr() - pbase()) if ios_base​::​out is set in *mode* andios_base​::​in is not set in *mode*, * [(4.3.2)](#virtuals-4.3.2) *buf*.size() otherwise[.](#virtuals-4.sentence-2) [5](#virtuals-5) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10351) If baseoff+off would overflow, or if baseoff+off is less than zero, or if baseoff+off is greater than *buf*.size(), the positioning operation fails[.](#virtuals-5.sentence-1) Otherwise, the function computesoff_type newoff = baseoff + off; and assigns xbeg + newoff to the next pointer xnext[.](#virtuals-5.sentence-2) [6](#virtuals-6) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10362) *Returns*: pos_type(off_type(-1)) if the positioning operation fails;pos_type(newoff) otherwise[.](#virtuals-6.sentence-1) [🔗](#lib:seekpos,basic_spanbuf) `pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override; ` [7](#virtuals-7) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10374) *Effects*: Equivalent to:return seekoff(off_type(sp), ios_base::beg, which); [🔗](#lib:setbuf,basic_spanbuf) `basic_streambuf* setbuf(charT* s, streamsize n) override; ` [8](#virtuals-8) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L10388) *Effects*: Equivalent to:this->span(std::span(s, n));return this;