[stringbuf.members] - C++17 → C++20

Files changed (1) hide show

tmp/tmpz3cq73pc/{from.md → to.md} +126 -31

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

@@ -1,40 +1,135 @@
 #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
 ``` cpp
-basic_string<charT, traits, Allocator> str() const;
-```
-*Returns:* A `basic_string` object whose content is equal to the
-`basic_stringbuf` underlying character sequence. If the
-`basic_stringbuf` was created only in input mode, the resultant
-`basic_string` contains the character sequence in the range \[`eback()`,
-`egptr()`). If the `basic_stringbuf` was created with
-`which & ios_base::out` being nonzero then the resultant `basic_string`
-contains the character sequence in the range \[`pbase()`, `high_mark`),
-where `high_mark` represents the position one past the highest
-initialized character in the buffer. Characters can be initialized by
-writing to the stream, by constructing the `basic_stringbuf` with a
-`basic_string`, or by calling the `str(basic_string)` member function.
-In the case of calling the `str(basic_string)` member function, all
-characters initialized prior to the call are now considered
-uninitialized (except for those characters re-initialized by the new
-`basic_string`). Otherwise the `basic_stringbuf` has been created in
-neither input nor output mode and a zero length `basic_string` is
-returned.
 ``` cpp
 void str(const basic_string<charT, traits, Allocator>& s);
 ```
-*Effects:* Copies the content of `s` into the `basic_stringbuf`
-underlying character sequence and initializes the input and output
-sequences according to `mode`.
-*Postconditions:* If `mode & ios_base::out` is nonzero, `pbase()` points
-to the first underlying character and `epptr()` `>= pbase() + s.size()`
-holds; in addition, if `mode & ios_base::ate` is nonzero,
-`pptr() == pbase() + s.size()` holds, otherwise `pptr() == pbase()` is
-`true`. If `mode & ios_base::in` is nonzero, `eback()` points to the
-first underlying character, and both `gptr() == eback()` and
-`egptr() == eback() + s.size()` hold.

 #### Member functions <a id="stringbuf.members">[[stringbuf.members]]</a>
+The member functions getting the underlying character sequence all refer
+to a `high_mark` value, where `high_mark` represents the position one
+past the highest initialized character in the buffer. Characters can be
+initialized by writing to the stream, by constructing the
+`basic_stringbuf` passing a `basic_string` argument, or by calling one
+of the `str` member functions passing a `basic_string` as an argument.
+In the latter case, all characters initialized prior to the call are now
+considered uninitialized (except for those characters re-initialized by
+the new `basic_string`).
+``` cpp
+void init_buf_ptrs(); // exposition only
+```
+*Effects:* Initializes the input and output sequences from `buf`
+according to `mode`.
+*Ensures:*
+- If `ios_base::out` is set in `mode`, `pbase()` points to `buf.front()`
+  and `epptr() >= pbase() + buf.size()` is `true`;
+  - in addition, if `ios_base::ate` is set in `mode`,
+    `pptr() == pbase() + buf.size()` is `true`,
+  - otherwise `pptr() == pbase()` is `true`.
+- If `ios_base::in` is set in `mode`, `eback()` points to `buf.front()`,
+  and `(gptr() == eback() && egptr() == eback() + buf.size())` is
+  `true`.
+[*Note 1*: For efficiency reasons, stream buffer operations might
+violate invariants of `buf` while it is held encapsulated in the
+`basic_stringbuf`, e.g., by writing to characters in the range
+\[`buf.data() + buf.size()`, `buf.data() + buf.capacity()`). All
+operations retrieving a `basic_string` from `buf` ensure that the
+`basic_string` invariants hold on the returned value. — *end note*]
+``` cpp
+allocator_type get_allocator() const noexcept;
+```
+*Returns:* `buf.get_allocator()`.
+``` cpp
+basic_string<charT, traits, Allocator> str() const &;
+```
+*Effects:* Equivalent to:
+``` cpp
+return basic_string<charT, traits, Allocator>(view(), get_allocator());
+```
 ``` cpp
+template<class SAlloc>
+  basic_string<charT, traits, SAlloc> str(const SAlloc& sa) const;
+```
+*Constraints:* `SAlloc` is a type that qualifies as an
+allocator [[container.requirements.general]].
+*Effects:* Equivalent to:
+``` cpp
+return basic_string<charT, traits, SAlloc>(view(), sa);
+```
+``` cpp
+basic_string<charT, traits, Allocator> str() &&;
+```
+*Returns:* A `basic_string<charT, traits, Allocator>` object move
+constructed from the `basic_stringbuf`’s underlying character sequence
+in `buf`. This can be achieved by first adjusting `buf` to have the same
+content as `view()`.
+*Ensures:* The underlying character sequence `buf` is empty and
+`pbase()`, `pptr()`, `epptr()`, `eback()`, `gptr()`, and `egptr()` are
+initialized as if by calling `init_buf_ptrs()` with an empty `buf`.
+``` cpp
+basic_string_view<charT, traits> view() const noexcept;
+```
+Let `sv` be `basic_string_view<charT, traits>`.
+*Returns:* A `sv` object referring to the `basic_stringbuf`’s underlying
+character sequence in `buf`:
+- If `ios_base::out` is set in `mode`, then
+  `sv(pbase(), high_mark-pbase())` is returned.
+- Otherwise, if `ios_base::in` is set in `mode`, then
+  `sv(eback(), egptr()-eback())` is returned.
+- Otherwise, `sv()` is returned.
+[*Note 2*: Using the returned `sv` object after destruction or
+invalidation of the character sequence underlying `*this` is undefined
+behavior, unless `sv.empty()` is `true`. — *end note*]
 ``` cpp
 void str(const basic_string<charT, traits, Allocator>& s);
 ```
+*Effects:* Equivalent to:
+``` cpp
+buf = s;
+init_buf_ptrs();
+```
+``` cpp
+template<class SAlloc>
+  void str(const basic_string<charT, traits, SAlloc>& s);
+```
+*Constraints:* `is_same_v<SAlloc,Allocator>` is `false`.
+*Effects:* Equivalent to:
+``` cpp
+buf = s;
+init_buf_ptrs();
+```
+``` cpp
+void str(basic_string<charT, traits, Allocator>&& s);
+```
+*Effects:* Equivalent to:
+``` cpp
+buf = std::move(s);
+init_buf_ptrs();
+```

Diff to HTML by rtfpessoa