[span.streams] - C++20 → C++23

Files changed (1) hide show

tmp/tmph2louhvc/{from.md → to.md} +637 -0

tmp/tmph2louhvc/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,637 @@

+## Span-based streams <a id="span.streams">[[span.streams]]</a>
+### Overview <a id="span.streams.overview">[[span.streams.overview]]</a>
+The header `<spanstream>` 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 subclause [[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*]
+### Header `<spanstream>` synopsis <a id="spanstream.syn">[[spanstream.syn]]</a>
+``` cpp
+namespace std {
+  template<class charT, class traits = char_traits<charT>>
+    class basic_spanbuf;
+  template<class charT, class traits>
+    void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);
+  using spanbuf = basic_spanbuf<char>;
+  using wspanbuf = basic_spanbuf<wchar_t>;
+  template<class charT, class traits = char_traits<charT>>
+    class basic_ispanstream;
+  template<class charT, class traits>
+    void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);
+  using ispanstream = basic_ispanstream<char>;
+  using wispanstream = basic_ispanstream<wchar_t>;
+  template<class charT, class traits = char_traits<charT>>
+    class basic_ospanstream;
+  template<class charT, class traits>
+    void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);
+  using ospanstream = basic_ospanstream<char>;
+  using wospanstream = basic_ospanstream<wchar_t>;
+  template<class charT, class traits = char_traits<charT>>
+    class basic_spanstream;
+  template<class charT, class traits>
+    void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);
+  using spanstream = basic_spanstream<char>;
+  using wspanstream = basic_spanstream<wchar_t>;
+}
+```
+### Class template `basic_spanbuf` <a id="spanbuf">[[spanbuf]]</a>
+#### General <a id="spanbuf.general">[[spanbuf.general]]</a>
+``` cpp
+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], 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], 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<charT> span() const noexcept;
+    void span(std::span<charT> 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<charT> buf;               // exposition only
+};
+}
+```
+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<charT>`.
+For the sake of exposition, the maintained data is presented here as:
+- `ios_base::openmode mode`, has `in` set if the input sequence can be
+  read, and `out` set if the output sequence can be written.
+- `std::span<charT> buf` is the view to the underlying character
+  sequence.
+#### Constructors <a id="spanbuf.cons">[[spanbuf.cons]]</a>
+``` cpp
+explicit basic_spanbuf(std::span<charT> s,
+                       ios_base::openmode which = ios_base::in | ios_base::out);
+```
+*Effects:* Initializes the base class with `basic_streambuf()`
+[[streambuf.cons]], and *mode* with `which`. Initializes the internal
+pointers as if calling `span(s)`.
+``` cpp
+basic_spanbuf(basic_spanbuf&& rhs);
+```
+*Effects:* Initializes the base class with `std::move(rhs)` and *mode*
+with `std::move(rhs.`*`mode`*`)` and *buf* with
+`std::move(rhs.`*`buf`*`)`. The sequence pointers in `*this` (`eback()`,
+`gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) obtain the values
+which `rhs` had. It is *implementation-defined* whether
+`rhs.`*`buf`*`.empty()` returns `true` after the move.
+*Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
+construction.
+- `span().data() == rhs_p.span().data()`
+- `span().size() == rhs_p.span().size()`
+- `eback() == rhs_p.eback()`
+- `gptr() == rhs_p.gptr()`
+- `egptr() == rhs_p.egptr()`
+- `pbase() == rhs_p.pbase()`
+- `pptr() == rhs_p.pptr()`
+- `epptr() == rhs_p.epptr()`
+- `getloc() == rhs_p.getloc()`
+#### Assignment and swap <a id="spanbuf.assign">[[spanbuf.assign]]</a>
+``` cpp
+basic_spanbuf& operator=(basic_spanbuf&& rhs);
+```
+*Effects:* Equivalent to:
+``` cpp
+basic_spanbuf tmp{std::move(rhs)};
+this->swap(tmp);
+return *this;
+```
+``` cpp
+void swap(basic_spanbuf& rhs);
+```
+*Effects:* Equivalent to:
+``` cpp
+basic_streambuf<charT, traits>::swap(rhs);
+std::swap(mode, rhs.mode);
+std::swap(buf, rhs.buf);
+```
+``` cpp
+template<class charT, class traits>
+  void swap(basic_spanbuf<charT, traits>& x, basic_spanbuf<charT, traits>& y);
+```
+*Effects:* Equivalent to `x.swap(y)`.
+#### Member functions <a id="spanbuf.members">[[spanbuf.members]]</a>
+``` cpp
+std::span<charT> span() const noexcept;
+```
+*Returns:* If `ios_base::out` is set in *mode*, returns
+`std::span<charT>(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<charT>`. — *end note*]
+``` cpp
+void span(std::span<charT> s) noexcept;
+```
+*Effects:* *`buf`*` = s`. Initializes the input and output sequences
+according to *mode*.
+*Ensures:*
+- If `ios_base::out` is set in *mode*,
+  `pbase() == s.data() && epptr() == pbase() + s.size()` is `true`;
+  - in addition, if `ios_base::ate` is set in *mode*,
+    `pptr() == pbase() + s.size()` is `true`,
+  - otherwise `pptr() == pbase()` is `true`.
+- If `ios_base::in` is set in *mode*,
+  `eback() == s.data() && gptr() == eback() && egptr() == eback() + s.size()`
+  is `true`.
+#### Overridden virtual functions <a id="spanbuf.virtuals">[[spanbuf.virtuals]]</a>
+[*Note 1*: Because the underlying buffer is of fixed size, neither
+`overflow`, `underflow`, nor `pbackfail` can provide useful
+behavior. — *end note*]
+``` cpp
+pos_type seekoff(off_type off, ios_base::seekdir way,
+                 ios_base::openmode which = ios_base::in | ios_base::out) override;
+```
+*Effects:* Alters the stream position within one or both of the
+controlled sequences, if possible, as follows:
+- If `ios_base::in` is set in `which`, positions the input sequence;
+  `xnext` is `gptr()`, `xbeg` is `eback()`.
+- If `ios_base::out` is set in `which`, positions the output sequence;
+  `xnext` is `pptr()`, `xbeg` is `pbase()`.
+If both `ios_base::in` and `ios_base::out` are set in `which` and `way`
+is `ios_base::cur`, the positioning operation fails.
+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:
+- `0` when `way` is `ios_base::beg`;
+- `(pptr() - pbase())` for the output sequence, or `(gptr() - eback())`
+  for the input sequence when `way` is `ios_base::cur`;
+- when `way` is `ios_base::end` :
+  - `(pptr() - pbase())` if `ios_base::out` is set in *mode* and
+    `ios_base::in` is not set in *mode*,
+  - `buf.size()` otherwise.
+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 computes
+``` cpp
+off_type newoff = baseoff + off;
+```
+and assigns `xbeg + newoff` to the next pointer `xnext`.
+*Returns:* `pos_type(off_type(-1))` if the positioning operation fails;
+`pos_type(newoff)` otherwise.
+``` cpp
+pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override;
+```
+*Effects:* Equivalent to:
+``` cpp
+return seekoff(off_type(sp), ios_base::beg, which);
+```
+``` cpp
+basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n) override;
+```
+*Effects:* Equivalent to:
+``` cpp
+this->span(std::span<charT>(s, n));
+return this;
+```
+### Class template `basic_ispanstream` <a id="ispanstream">[[ispanstream]]</a>
+#### General <a id="ispanstream.general">[[ispanstream.general]]</a>
+``` cpp
+namespace std {
+  template<class charT, class traits = char_traits<charT>>
+  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], constructors
+    explicit basic_ispanstream(std::span<charT> s,
+                               ios_base::openmode which = ios_base::in);
+    basic_ispanstream(const basic_ispanstream&) = delete;
+    basic_ispanstream(basic_ispanstream&& rhs);
+    template<class ROS> explicit basic_ispanstream(ROS&& s);
+    basic_ispanstream& operator=(const basic_ispanstream&) = delete;
+    basic_ispanstream& operator=(basic_ispanstream&& rhs);
+    // [ispanstream.swap], swap
+    void swap(basic_ispanstream& rhs);
+    // [ispanstream.members], member functions
+    basic_spanbuf<charT, traits>* rdbuf() const noexcept;
+    std::span<const charT> span() const noexcept;
+    void span(std::span<charT> s) noexcept;
+    template<class ROS> void span(ROS&& s) noexcept;
+  private:
+    basic_spanbuf<charT, traits> sb;    // exposition only
+  };
+}
+```
+[*Note 1*: Constructing an `ispanstream` from a *string-literal*
+includes the termination character `'\0'` in the underlying
+`spanbuf`. — *end note*]
+#### Constructors <a id="ispanstream.cons">[[ispanstream.cons]]</a>
+``` cpp
+explicit basic_ispanstream(std::span<charT> s, ios_base::openmode which = ios_base::in);
+```
+*Effects:* Initializes the base class with
+`basic_istream<charT, traits>(addressof(sb))` and `sb` with
+`basic_spanbuf<charT, traits>(s, which | ios_base::in)`
+[[spanbuf.cons]].
+``` cpp
+basic_ispanstream(basic_ispanstream&& rhs);
+```
+*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`.
+``` cpp
+template<class ROS> explicit basic_ispanstream(ROS&& s)
+```
+*Constraints:* `ROS` models `ranges::borrowed_range`.
+`!convertible_to<ROS, std::span<charT>> && convertible_to<ROS, std::span<charT const>>`
+is `true`.
+*Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
+Equivalent to
+``` cpp
+basic_ispanstream(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
+```
+#### Swap <a id="ispanstream.swap">[[ispanstream.swap]]</a>
+``` cpp
+void swap(basic_ispanstream& rhs);
+```
+*Effects:* Equivalent to:
+``` cpp
+basic_istream<charT, traits>::swap(rhs);
+sb.swap(rhs.sb);
+```
+``` cpp
+template<class charT, class traits>
+  void swap(basic_ispanstream<charT, traits>& x, basic_ispanstream<charT, traits>& y);
+```
+*Effects:* Equivalent to `x.swap(y)`.
+#### Member functions <a id="ispanstream.members">[[ispanstream.members]]</a>
+``` cpp
+basic_spanbuf<charT, traits>* rdbuf() const noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
+```
+``` cpp
+std::span<const charT> span() const noexcept;
+```
+*Effects:* Equivalent to: `return rdbuf()->span();`
+``` cpp
+void span(std::span<charT> s) noexcept;
+```
+*Effects:* Equivalent to `rdbuf()->span(s)`.
+``` cpp
+template<class ROS> void span(ROS&& s) noexcept;
+```
+*Constraints:* `ROS` models `ranges::borrowed_range`.
+`(!convertible_to<ROS, std::span<charT>>) && convertible_to<ROS, std::span<const charT>>`
+is `true`.
+*Effects:* Let `sp` be `std::span<const charT>(std::forward<ROS>(s))`.
+Equivalent to:
+``` cpp
+this->span(std::span<charT>(const_cast<charT*>(sp.data()), sp.size()))
+```
+### Class template `basic_ospanstream` <a id="ospanstream">[[ospanstream]]</a>
+#### General <a id="ospanstream.general">[[ospanstream.general]]</a>
+``` cpp
+namespace std {
+  template<class charT, class traits = char_traits<charT>>
+  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], constructors
+    explicit basic_ospanstream(std::span<charT> 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], swap
+    void swap(basic_ospanstream& rhs);
+    // [ospanstream.members], member functions
+    basic_spanbuf<charT, traits>* rdbuf() const noexcept;
+    std::span<charT> span() const noexcept;
+    void span(std::span<charT> s) noexcept;
+  private:
+    basic_spanbuf<charT, traits> sb;    // exposition only
+  };
+}
+```
+#### Constructors <a id="ospanstream.cons">[[ospanstream.cons]]</a>
+``` cpp
+explicit basic_ospanstream(std::span<charT> s,
+                           ios_base::openmode which = ios_base::out);
+```
+*Effects:* Initializes the base class with
+`basic_ostream<charT, traits>(addressof(sb))` and `sb` with
+`basic_spanbuf<charT, traits>(s, which | ios_base::out)`
+[[spanbuf.cons]].
+``` cpp
+basic_ospanstream(basic_ospanstream&& rhs) noexcept;
+```
+*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`.
+#### Swap <a id="ospanstream.swap">[[ospanstream.swap]]</a>
+``` cpp
+void swap(basic_ospanstream& rhs);
+```
+*Effects:* Equivalent to:
+``` cpp
+basic_ostream<charT, traits>::swap(rhs);
+sb.swap(rhs.sb);
+```
+``` cpp
+template<class charT, class traits>
+  void swap(basic_ospanstream<charT, traits>& x, basic_ospanstream<charT, traits>& y);
+```
+*Effects:* Equivalent to `x.swap(y)`.
+#### Member functions <a id="ospanstream.members">[[ospanstream.members]]</a>
+``` cpp
+basic_spanbuf<charT, traits>* rdbuf() const noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
+```
+``` cpp
+std::span<charT> span() const noexcept;
+```
+*Effects:* Equivalent to: `return rdbuf()->span();`
+``` cpp
+void span(std::span<charT> s) noexcept;
+```
+*Effects:* Equivalent to `rdbuf()->span(s)`.
+### Class template `basic_spanstream` <a id="spanstream">[[spanstream]]</a>
+#### General <a id="spanstream.general">[[spanstream.general]]</a>
+``` cpp
+namespace std {
+  template<class charT, class traits = char_traits<charT>>
+  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], constructors
+    explicit basic_spanstream(std::span<charT> 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], swap
+    void swap(basic_spanstream& rhs);
+    // [spanstream.members], members
+    basic_spanbuf<charT, traits>* rdbuf() const noexcept;
+    std::span<charT> span() const noexcept;
+    void span(std::span<charT> s) noexcept;
+  private:
+    basic_spanbuf<charT, traits> sb;    // exposition only
+  };
+}
+```
+#### Constructors <a id="spanstream.cons">[[spanstream.cons]]</a>
+``` cpp
+explicit basic_spanstream(std::span<charT> s,
+                          ios_base::openmode which = ios_base::out | ios_bas::in);
+```
+*Effects:* Initializes the base class with
+`basic_iostream<charT, traits>(addressof(sb))` and `sb` with
+`basic_spanbuf<charT, traits>(s, which)` [[spanbuf.cons]].
+``` cpp
+basic_spanstream(basic_spanstream&& rhs);
+```
+*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`.
+#### Swap <a id="spanstream.swap">[[spanstream.swap]]</a>
+``` cpp
+void swap(basic_spanstream& rhs);
+```
+*Effects:* Equivalent to:
+``` cpp
+basic_iostream<charT, traits>::swap(rhs);
+sb.swap(rhs.sb);
+```
+``` cpp
+template<class charT, class traits>
+  void swap(basic_spanstream<charT, traits>& x, basic_spanstream<charT, traits>& y);
+```
+*Effects:* Equivalent to `x.swap(y)`.
+#### Member functions <a id="spanstream.members">[[spanstream.members]]</a>
+``` cpp
+basic_spanbuf<charT, traits>* rdbuf() const noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+return const_cast<basic_spanbuf<charT, traits>*>(addressof(sb));
+```
+``` cpp
+std::span<charT> span() const noexcept;
+```
+*Effects:* Equivalent to: `return rdbuf()->span();`
+``` cpp
+void span(std::span<charT> s) noexcept;
+```
+*Effects:* Equivalent to `rdbuf()->span(s)`.

Diff to HTML by rtfpessoa