cppdraft_translate/cppdraft/spanbuf.md

[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 charT, class traits = char_traits<charT>>class basic_spanbuf : public basic_streambuf<charT, traits> {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<charT>(), which) {}explicit basic_spanbuf(std::span<charT> 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<charT> span() const noexcept; void span(std::span<charT> s) noexcept; protected:// [[spanbuf.virtuals]](#virtuals "31.9.3.5 Overridden virtual functions"), overridden virtual functions basic_streambuf<charT, traits>* 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<charT> *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<charT>[.](#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<charT> *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<charT> 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<charT, traits>::swap(rhs);
std::swap(*mode*, rhs.*mode*);
std::swap(*buf*, rhs.*buf*);

[🔗](#lib:swap,basic_spanbuf_)

`template<class charT, class traits>
  void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& 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<charT> 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<charT>(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<charT>[.](#members-1.sentence-3)

— *end note*]

[🔗](#lib:span,basic_spanbuf_)

`void span(std::span<charT> 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<charT, traits>* 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<charT>(s, n));return this;