cppdraft_translate/cppdraft/span/streams.md

[span.streams]

31 Input/output library [input.output]

31.9 Span-based streams [span.streams]

31.9.1 Overview [span.streams.overview]

1

#

The header defines class templates and types that associate stream buffers with objects whose types are specializations of span as described in [views.span].

[Note 1:

A user of these classes is responsible for ensuring that the character sequence represented by the given span outlives the use of the sequence by objects of the classes in [span.streams].

Using multiple basic_spanbuf objects referring to overlapping underlying sequences from different threads, where at least one basic_spanbuf object is used for writing to the sequence, results in a data race.

— end note]

31.9.2 Header synopsis [spanstream.syn]

🔗

namespace std {// [spanbuf], class template basic_spanbuftemplate<class charT, class traits = char_traits>class basic_spanbuf; template<class charT, class traits>void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y); using spanbuf = basic_spanbuf; using wspanbuf = basic_spanbuf<wchar_t>; // [ispanstream], class template basic_ispanstreamtemplate<class charT, class traits = char_traits>class basic_ispanstream; template<class charT, class traits>void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y); using ispanstream = basic_ispanstream; using wispanstream = basic_ispanstream<wchar_t>; // [ospanstream], class template basic_ospanstreamtemplate<class charT, class traits = char_traits>class basic_ospanstream; template<class charT, class traits>void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y); using ospanstream = basic_ospanstream; using wospanstream = basic_ospanstream<wchar_t>; // [spanstream], class template basic_spanstreamtemplate<class charT, class traits = char_traits>class basic_spanstream; template<class charT, class traits>void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y); using spanstream = basic_spanstream; using wspanstream = basic_spanstream<wchar_t>;}

31.9.3 Class template basic_spanbuf [spanbuf]

31.9.3.1 General [spanbuf.general]

🔗

namespace std {template<class charT, class traits = char_traits>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], 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], assignment and swap basic_spanbuf& operator=(const basic_spanbuf&) = delete; basic_spanbuf& operator=(basic_spanbuf&& rhs); void swap(basic_spanbuf& rhs); // [spanbuf.members], member functions std::span span() const noexcept; void span(std::span s) noexcept; protected:// [spanbuf.virtuals], 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 buf; // exposition only};}

1

#

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.

The sequence is provided by an object of class span.

2

#

For the sake of exposition, the maintained data is presented here as:

• (2.1)

  ios_base​::​openmode mode, hasin set if the input sequence can be read, andout set if the output sequence can be written.

• (2.2)

  std​::​span buf is the view to the underlying character sequence.

31.9.3.2 Constructors [spanbuf.cons]

🔗

explicit basic_spanbuf(std::span<charT> s, ios_base::openmode which = ios_base::in | ios_base::out);

1

#

Effects: Initializes the base class with basic_streambuf() ([streambuf.cons]), and mode with which.

Initializes the internal pointers as if calling span(s).

🔗

basic_spanbuf(basic_spanbuf&& rhs);

2

#

Effects: Initializes the base class with std​::​move(rhs) andmode with std​::​move(rhs.mode) andbuf with std​::​move(rhs.buf).

The sequence pointers in *this (eback(), gptr(), egptr(),pbase(), pptr(), epptr()) obtain the values which rhs had.

It isimplementation-defined whether rhs.buf.​empty() returns true after the move.

3

#

Postconditions: Let rhs_p refer to the state of rhs just prior to this construction.

• (3.1)

span().data() == rhs_p.span().data()

• (3.2)

span().size() == rhs_p.span().size()

• (3.3)

eback() == rhs_p.eback()

• (3.4)

gptr() == rhs_p.gptr()

• (3.5)

egptr() == rhs_p.egptr()

• (3.6)

pbase() == rhs_p.pbase()

• (3.7)

pptr() == rhs_p.pptr()

• (3.8)

epptr() == rhs_p.epptr()

• (3.9)

getloc() == rhs_p.getloc()

31.9.3.3 Assignment and swap [spanbuf.assign]

🔗

basic_spanbuf& operator=(basic_spanbuf&& rhs);

1

#

Effects: Equivalent to:basic_spanbuf tmp{std::move(rhs)};this->swap(tmp);return *this;

🔗

void swap(basic_spanbuf& rhs);

2

#

Effects: Equivalent to:basic_streambuf<charT, traits>::swap(rhs); std::swap(mode, rhs.mode); std::swap(buf, rhs.buf);

🔗

template<class charT, class traits> void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);

3

#

Effects: Equivalent to x.swap(y).

31.9.3.4 Member functions [spanbuf.members]

🔗

std::span<charT> span() const noexcept;

1

#

Returns: If ios_base​::​out is set in mode, returns std​::​span(pbase(), pptr()), otherwise returns buf.

[Note 1:

In contrast to basic_stringbuf, the underlying sequence never grows and is not owned.

An owning copy can be obtained by converting the result to basic_string.

— end note]

🔗

void span(std::span<charT> s) noexcept;

2

#

Effects: buf = s.

Initializes the input and output sequences according to mode.

3

#

Postconditions:

• (3.1)

  If ios_base​::​out is set in mode,pbase() == s.data() && epptr() == pbase() + s.size() is true;

  • (3.1.1)

in addition, if ios_base​::​ate is set in mode,pptr() == pbase() + s.size() is true,

• (3.1.2)

otherwise pptr() == pbase() is true.

• (3.2)

  If ios_base​::​in is set in mode,eback() == s.data() && gptr() == eback() && egptr() == eback() + s.size() is true.

31.9.3.5 Overridden virtual functions [spanbuf.virtuals]

1

#

[Note 1:

Because the underlying buffer is of fixed size, neither overflow, underflow, nor pbackfail can provide useful behavior.

— end note]

🔗

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

2

#

Effects: Alters the stream position within one or both of the controlled sequences, if possible, as follows:

• (2.1)

  If ios_base​::​in is set in which, positions the input sequence;xnext is gptr(), xbeg is eback().

• (2.2)

  If ios_base​::​out is set in which, positions the output sequence;xnext is pptr(), xbeg is pbase().

3

#

If both ios_base​::​in and ios_base​::​out are set in which and way is ios_base​::​cur, the positioning operation fails.

4

#

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.

Otherwise, the function determines baseoff as a value of type off_type as follows:

• (4.1)

0 when way is ios_base​::​beg;

• (4.2)

(pptr() - pbase()) for the output sequence, or(gptr() - eback()) for the input sequence when way is ios_base​::​cur;

• (4.3)

when way is ios_base​::​end :

• (4.3.1)

(pptr() - pbase()) if ios_base​::​out is set in mode andios_base​::​in is not set in mode,

• (4.3.2)

buf.size() otherwise.

5

#

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.

Otherwise, the function computesoff_type newoff = baseoff + off; and assigns xbeg + newoff to the next pointer xnext.

6

#

Returns: pos_type(off_type(-1)) if the positioning operation fails;pos_type(newoff) otherwise.

🔗

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

7

#

Effects: Equivalent to:return seekoff(off_type(sp), ios_base::beg, which);

🔗

basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n) override;

8

#

Effects: Equivalent to:this->span(std::span(s, n));return this;

31.9.4 Class template basic_ispanstream [ispanstream]

31.9.4.1 General [ispanstream.general]

🔗

namespace std {template<class charT, class traits = char_traits>class basic_ispanstream : public basic_istream<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; // [ispanstream.cons], constructorsexplicit basic_ispanstream(std::span s, ios_base::openmode which = ios_base::in); basic_ispanstream(const basic_ispanstream&) = delete; basic_ispanstream(basic_ispanstream&& rhs); template explicit basic_ispanstream(ROS&& s);

basic_ispanstream& operator=(const basic_ispanstream&) = delete; basic_ispanstream& operator=(basic_ispanstream&& rhs); // [ispanstream.swap], swapvoid swap(basic_ispanstream& rhs); // [ispanstream.members], member functions basic_spanbuf<charT, traits>* rdbuf() const noexcept;

std::span span() const noexcept; void span(std::span s) noexcept; template void span(ROS&& s) noexcept; private: basic_spanbuf<charT, traits> sb; // exposition only};}

1

#

[Note 1:

Constructing an ispanstream from a string-literal includes the termination character '\0' in the underlying spanbuf.

— end note]

31.9.4.2 Constructors [ispanstream.cons]

🔗

explicit basic_ispanstream(std::span<charT> s, ios_base::openmode which = ios_base::in);

1

#

Effects: Initializes the base class withbasic_istream<charT, traits>(addressof(sb)) and sb withbasic_spanbuf<charT, traits>(s, which | ios_base​::​in) ([spanbuf.cons]).

🔗

basic_ispanstream(basic_ispanstream&& rhs);

2

#

Effects: Initializes the base class with std​::​move(rhs) and sb with std​::​move(rhs.sb).

Next, basic_istream<charT, traits>​::​set_rdbuf(addressof(sb)) is called to install the contained basic_spanbuf.

🔗

template<class ROS> explicit basic_ispanstream(ROS&& s)

3

#

Constraints: ROS models ranges​::​borrowed_range.

<ROS, std​::​span> && convertible_to<ROS, std​::​span> is true.

4

#

Effects: Let sp be std​::​span(std​::​forward(s)).

Equivalent to:basic_ispanstream(std::span(const_cast<charT*>(sp.data()), sp.size()))

31.9.4.3 Swap [ispanstream.swap]

🔗

void swap(basic_ispanstream& rhs);

1

#

Effects: Equivalent to:basic_istream<charT, traits>::swap(rhs);sb.swap(rhs.sb);

🔗

template<class charT, class traits> void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);

2

#

Effects: Equivalent to x.swap(y).

31.9.4.4 Member functions [ispanstream.members]

🔗

basic_spanbuf<charT, traits>* rdbuf() const noexcept;

1

#

Effects: Equivalent to:return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));

🔗

std::span<const charT> span() const noexcept;

2

#

Effects: Equivalent to: return rdbuf()->span();

🔗

void span(std::span<charT> s) noexcept;

3

#

Effects: Equivalent to rdbuf()->span(s).

🔗

template<class ROS> void span(ROS&& s) noexcept;

4

#

Constraints: ROS models ranges​::​borrowed_range.

(<ROS, std​::​span>) && convertible_to<ROS, std​::​span> is true.

5

#

Effects: Let sp be std​::​span(std​::​forward(s)).

Equivalent to:this->span(std::span(const_cast<charT*>(sp.data()), sp.size()));

31.9.5 Class template basic_ospanstream [ospanstream]

31.9.5.1 General [ospanstream.general]

🔗

namespace std {template<class charT, class traits = char_traits>class basic_ospanstream : public basic_ostream<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; // [ospanstream.cons], constructorsexplicit basic_ospanstream(std::span s, ios_base::openmode which = ios_base::out); basic_ospanstream(const basic_ospanstream&) = delete; basic_ospanstream(basic_ospanstream&& rhs);

basic_ospanstream& operator=(const basic_ospanstream&) = delete; basic_ospanstream& operator=(basic_ospanstream&& rhs); // [ospanstream.swap], swapvoid swap(basic_ospanstream& rhs); // [ospanstream.members], member functions basic_spanbuf<charT, traits>* rdbuf() const noexcept;

std::span span() const noexcept; void span(std::span s) noexcept; private: basic_spanbuf<charT, traits> sb; // exposition only};}

31.9.5.2 Constructors [ospanstream.cons]

🔗

explicit basic_ospanstream(std::span<charT> s, ios_base::openmode which = ios_base::out);

1

#

Effects: Initializes the base class withbasic_ostream<charT, traits>(addressof(sb)) and sb withbasic_spanbuf<charT, traits>(s, which | ios_base​::​out) ([spanbuf.cons]).

🔗

basic_ospanstream(basic_ospanstream&& rhs) noexcept;

2

#

Effects: Initializes the base class with std​::​move(rhs) and sb with std​::​move(rhs.sb).

Next, basic_ostream<charT, traits>​::​set_rdbuf(addressof(sb)) is called to install the contained basic_spanbuf.

31.9.5.3 Swap [ospanstream.swap]

🔗

void swap(basic_ospanstream& rhs);

1

#

Effects: Equivalent to:basic_ostream<charT, traits>::swap(rhs);sb.swap(rhs.sb);

🔗

template<class charT, class traits> void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);

2

#

Effects: Equivalent to x.swap(y).

31.9.5.4 Member functions [ospanstream.members]

🔗

basic_spanbuf<charT, traits>* rdbuf() const noexcept;

1

#

Effects: Equivalent to:return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));

🔗

std::span<charT> span() const noexcept;

2

#

Effects: Equivalent to: return rdbuf()->span();

🔗

void span(std::span<charT> s) noexcept;

3

#

Effects: Equivalent to rdbuf()->span(s).

31.9.6 Class template basic_spanstream [spanstream]

31.9.6.1 General [spanstream.general]

🔗

namespace std {template<class charT, class traits = char_traits>class basic_spanstream : public basic_iostream<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; // [spanstream.cons], constructorsexplicit basic_spanstream(std::span s, ios_base::openmode which = ios_base::out | ios_base::in); basic_spanstream(const basic_spanstream&) = delete; basic_spanstream(basic_spanstream&& rhs);

basic_spanstream& operator=(const basic_spanstream&) = delete; basic_spanstream& operator=(basic_spanstream&& rhs); // [spanstream.swap], swapvoid swap(basic_spanstream& rhs); // [spanstream.members], members basic_spanbuf<charT, traits>* rdbuf() const noexcept;

std::span span() const noexcept; void span(std::span s) noexcept; private: basic_spanbuf<charT, traits> sb; // exposition only};}

31.9.6.2 Constructors [spanstream.cons]

🔗

explicit basic_spanstream(std::span<charT> s, ios_base::openmode which = ios_base::out | ios_bas::in);

1

#

Effects: Initializes the base class withbasic_iostream<charT, traits>(addressof(sb)) and sb withbasic_spanbuf<charT, traits>(s, which) ([spanbuf.cons]).

🔗

basic_spanstream(basic_spanstream&& rhs);

2

#

Effects: Initializes the base class with std​::​move(rhs) and sb with std​::​move(rhs.sb).

Next, basic_iostream<charT, traits>​::​set_rdbuf(addressof(sb)) is called to install the contained basic_spanbuf.

31.9.6.3 Swap [spanstream.swap]

🔗

void swap(basic_spanstream& rhs);

1

#

Effects: Equivalent to:basic_iostream<charT, traits>::swap(rhs);sb.swap(rhs.sb);

🔗

template<class charT, class traits> void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);

2

#

Effects: Equivalent to x.swap(y).

31.9.6.4 Member functions [spanstream.members]

🔗

basic_spanbuf<charT, traits>* rdbuf() const noexcept;

1

#

Effects: Equivalent to:return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));

🔗

std::span<charT> span() const noexcept;

2

#

Effects: Equivalent to: return rdbuf()->span();

🔗

void span(std::span<charT> s) noexcept;

3

#

Effects: Equivalent to rdbuf()->span(s).