[basic.string] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpp8m1gihc/{from.md → to.md} +47 -40

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

@@ -25,14 +25,14 @@ namespace std {
   public:
     // types
     using traits_type            = traits;
     using value_type             = charT;
     using allocator_type         = Allocator;
-    using size_type              = typename allocator_traits<Allocator>::size_type;
-    using difference_type        = typename allocator_traits<Allocator>::difference_type;
-    using pointer                = typename allocator_traits<Allocator>::pointer;
-    using const_pointer          = typename allocator_traits<Allocator>::const_pointer;
     using reference              = value_type&;
     using const_reference        = const value_type&;
     using iterator               = implementation-defined  // type of basic_string::iterator; // see [container.requirements]
     using const_iterator         = implementation-defined  // type of basic_string::const_iterator; // see [container.requirements]
@@ -108,11 +108,11 @@ namespace std {
     template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
     constexpr size_type capacity() const noexcept;
     constexpr void reserve(size_type res_arg);
     constexpr void shrink_to_fit();
     constexpr void clear() noexcept;
- [[nodiscard]] constexpr bool empty() const noexcept;
     // [string.access], element access
     constexpr const_reference operator[](size_type pos) const;
     constexpr reference       operator[](size_type pos);
     constexpr const_reference at(size_type n) const;
@@ -274,10 +274,12 @@ namespace std {
     constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
     constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
     constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
     constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
     template<class T>
       constexpr int compare(const T& t) const noexcept(see below);
     template<class T>
       constexpr int compare(size_type pos1, size_type n1, const T& t) const;
@@ -347,24 +349,23 @@ operation throws an exception object of type `length_error`.
 If any member function or operator of `basic_string` throws an
 exception, that function or operator has no other effect on the
 `basic_string` object.
-In every specialization `basic_string<charT, traits, Allocator>`, the
-type `allocator_traits<Allocator>::value_type` shall name the same type
-as `charT`. Every object of type
-`basic_string<charT, traits, Allocator>` uses an object of type
-`Allocator` to allocate and free storage for the contained `charT`
-objects as needed. The `Allocator` object used is obtained as described
-in [[container.requirements.general]]. In every specialization
 `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
 the character traits requirements [[char.traits]].
 [*Note 1*: Every specialization
-`basic_string<charT, traits, Allocator>` is an allocator-aware
-container, but does not use the allocator’s `construct` and `destroy`
-member functions [[container.requirements.general]]. — *end note*]
 [*Note 2*: The program is ill-formed if `traits::char_type` is not the
 same type as `charT`. — *end note*]
 References, pointers, and iterators referring to the elements of a
@@ -470,11 +471,11 @@ is equal to `0`.
 ``` cpp
 constexpr basic_string(const charT* s, const Allocator& a = Allocator());
 ```
 *Constraints:* `Allocator` is a type that qualifies as an
-allocator [[container.requirements.general]].
 [*Note 1*: This affects class template argument
 deduction. — *end note*]
 *Effects:* Equivalent to: `basic_string(s, traits::length(s), a)`.
@@ -482,11 +483,11 @@ deduction. — *end note*]
 ``` cpp
 constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
 ```
 *Constraints:* `Allocator` is a type that qualifies as an
-allocator [[container.requirements.general]].
 [*Note 2*: This affects class template argument
 deduction. — *end note*]
 *Effects:* Constructs an object whose value consists of `n` copies of
@@ -496,11 +497,11 @@ deduction. — *end note*]
 template<class InputIterator>
   constexpr basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
-iterator [[container.requirements.general]].
 *Effects:* Constructs a string from the values in the range \[`begin`,
 `end`), as specified in [[sequence.reqmts]].
 ``` cpp
@@ -538,11 +539,11 @@ template<class InputIterator,
                     Allocator>;
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
 iterator, and `Allocator` is a type that qualifies as an
-allocator [[container.requirements.general]].
 ``` cpp
 template<class charT,
          class traits,
          class Allocator = allocator<charT>>
@@ -557,11 +558,11 @@ template<class charT,
                const Allocator& = Allocator())
     -> basic_string<charT, traits, Allocator>;
 ```
 *Constraints:* `Allocator` is a type that qualifies as an
-allocator [[container.requirements.general]].
 ``` cpp
 constexpr basic_string& operator=(const basic_string& str);
 ```
@@ -574,13 +575,12 @@ Otherwise, replaces the value of `*this` with a copy of `str`.
 constexpr basic_string& operator=(basic_string&& str)
   noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
            allocator_traits<Allocator>::is_always_equal::value);
 ```
-*Effects:* Move assigns as a sequence
-container [[container.requirements]], except that iterators, pointers
-and references may be invalidated.
 *Returns:* `*this`.
 ``` cpp
 template<class T>
@@ -746,14 +746,14 @@ constexpr size_type capacity() const noexcept;
 constexpr void reserve(size_type res_arg);
 ```
 *Effects:* A directive that informs a `basic_string` of a planned change
 in size, so that the storage allocation can be managed accordingly.
-After `reserve()`, `capacity()` is greater or equal to the argument of
-`reserve` if reallocation happens; and equal to the previous value of
-`capacity()` otherwise. Reallocation happens at this point if and only
-if the current capacity is less than the argument of `reserve()`.
 *Throws:* `length_error` if `res_arg > max_size()` or any exceptions
 thrown by `allocator_traits` `<Allocator>::allocate`.
 ``` cpp
@@ -784,11 +784,11 @@ constexpr void clear() noexcept;
 ```
 *Effects:* Equivalent to: `erase(begin(), end());`
 ``` cpp
-[[nodiscard]] constexpr bool empty() const noexcept;
 ```
 *Effects:* Equivalent to: `return size() == 0;`
 #### Element access <a id="string.access">[[string.access]]</a>
@@ -796,11 +796,11 @@ constexpr void clear() noexcept;
 ``` cpp
 constexpr const_reference operator[](size_type pos) const;
 constexpr reference       operator[](size_type pos);
 ```
-*Preconditions:* `pos <= size()`.
 *Returns:* `*(begin() + pos)` if `pos < size()`. Otherwise, returns a
 reference to an object of type `charT` with value `charT()`, where
 modifying the object to any value other than `charT()` leads to
 undefined behavior.
@@ -821,20 +821,20 @@ constexpr reference       at(size_type pos);
 ``` cpp
 constexpr const charT& front() const;
 constexpr charT& front();
 ```
-*Preconditions:* `!empty()`.
 *Effects:* Equivalent to: `return operator[](0);`
 ``` cpp
 constexpr const charT& back() const;
 constexpr charT& back();
 ```
-*Preconditions:* `!empty()`.
 *Effects:* Equivalent to: `return operator[](size() - 1);`
 #### Modifiers <a id="string.modifiers">[[string.modifiers]]</a>
@@ -964,11 +964,11 @@ constexpr basic_string& append(size_type n, charT c);
 template<class InputIterator>
   constexpr basic_string& append(InputIterator first, InputIterator last);
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
-iterator [[container.requirements.general]].
 *Effects:* Equivalent to:
 `return append(basic_string(first, last, get_allocator()));`
 ``` cpp
@@ -1092,11 +1092,11 @@ return *this;
 template<class InputIterator>
   constexpr basic_string& assign(InputIterator first, InputIterator last);
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
-iterator [[container.requirements.general]].
 *Effects:* Equivalent to:
 `return assign(basic_string(first, last, get_allocator()));`
 ``` cpp
@@ -1192,11 +1192,11 @@ constexpr basic_string& insert(size_type pos, size_type n, charT c);
 ```
 *Effects:* Inserts `n` copies of `c` before the character at position
 `pos` if `pos < size()`, or otherwise at the end of the string.
-*Returns:* `*this`
 *Throws:*
 - `out_of_range` if `pos > size()`,
 - `length_error` if `n > max_size() - size()`, or
@@ -1227,11 +1227,11 @@ constexpr iterator insert(const_iterator p, size_type n, charT c);
 template<class InputIterator>
   constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
-iterator [[container.requirements.general]].
 *Preconditions:* `p` is a valid iterator on `*this`.
 *Effects:* Equivalent to
 `insert(p - begin(), basic_string(first, last, get_allocator()))`.
@@ -1291,11 +1291,11 @@ constexpr iterator erase(const_iterator first, const_iterator last);
 ```
 *Preconditions:* `first` and `last` are valid iterators on `*this`.
 \[`first`, `last`) is a valid range.
-*Effects:* Removes the characters in the range `[first, last)`.
 *Returns:* An iterator which points to the element pointed to by `last`
 prior to the other elements being erased. If no such element exists,
 `end()` is returned.
@@ -1303,11 +1303,11 @@ prior to the other elements being erased. If no such element exists,
 ``` cpp
 constexpr void pop_back();
 ```
-*Preconditions:* `!empty()`.
 *Effects:* Equivalent to `erase(end() - 1)`.
 *Throws:* Nothing.
@@ -1409,12 +1409,12 @@ the function replaces the characters in the range \[`begin() + pos1`,
 *Returns:* `*this`.
 *Throws:*
 - `out_of_range` if `pos1 > size()`,
-- `length_error` if the length of the resulting string would
- exceed`max_size()`, or
 - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
 ``` cpp
 constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
 ```
@@ -1469,11 +1469,11 @@ template<class InputIterator>
   constexpr basic_string& replace(const_iterator i1, const_iterator i2,
                                   InputIterator j1, InputIterator j2);
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
-iterator [[container.requirements.general]].
 *Effects:* Equivalent to:
 `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
 ``` cpp
@@ -1649,10 +1649,17 @@ constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
 ```
 *Effects:* Equivalent to:
 `return basic_string(std::move(*this), pos, n);`
 ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
 ``` cpp
 template<class T>
   constexpr int compare(const T& t) const noexcept(see below);

   public:
     // types
     using traits_type            = traits;
     using value_type             = charT;
     using allocator_type         = Allocator;
+    using size_type              = allocator_traits<Allocator>::size_type;
+    using difference_type        = allocator_traits<Allocator>::difference_type;
+    using pointer                = allocator_traits<Allocator>::pointer;
+    using const_pointer          = allocator_traits<Allocator>::const_pointer;
     using reference              = value_type&;
     using const_reference        = const value_type&;
     using iterator               = implementation-defined  // type of basic_string::iterator; // see [container.requirements]
     using const_iterator         = implementation-defined  // type of basic_string::const_iterator; // see [container.requirements]
     template<class Operation> constexpr void resize_and_overwrite(size_type n, Operation op);
     constexpr size_type capacity() const noexcept;
     constexpr void reserve(size_type res_arg);
     constexpr void shrink_to_fit();
     constexpr void clear() noexcept;
+    constexpr bool empty() const noexcept;
     // [string.access], element access
     constexpr const_reference operator[](size_type pos) const;
     constexpr reference       operator[](size_type pos);
     constexpr const_reference at(size_type n) const;
     constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;
     constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
     constexpr basic_string substr(size_type pos = 0, size_type n = npos) const &;
     constexpr basic_string substr(size_type pos = 0, size_type n = npos) &&;
+    constexpr basic_string_view<charT, traits> subview(size_type pos = 0,
+                                                       size_type n = npos) const;
     template<class T>
       constexpr int compare(const T& t) const noexcept(see below);
     template<class T>
       constexpr int compare(size_type pos1, size_type n1, const T& t) const;
 If any member function or operator of `basic_string` throws an
 exception, that function or operator has no other effect on the
 `basic_string` object.
+Every object of type `basic_string<charT, traits, Allocator>` uses an
+object of type `Allocator` to allocate and free storage for the
+contained `charT` objects as needed. The `Allocator` object used is
+obtained as described in [[container.reqmts]]. In every specialization
 `basic_string<charT, traits, Allocator>`, the type `traits` shall meet
 the character traits requirements [[char.traits]].
 [*Note 1*: Every specialization
+`basic_string<charT, traits, Allocator>` is an allocator-aware container
+[[container.alloc.reqmts]], but does not use the allocator’s `construct`
+and `destroy` member functions [[container.requirements.pre]]. The
+program is ill-formed if `Allocator::value_type` is not the same type as
+`charT`. — *end note*]
 [*Note 2*: The program is ill-formed if `traits::char_type` is not the
 same type as `charT`. — *end note*]
 References, pointers, and iterators referring to the elements of a
 ``` cpp
 constexpr basic_string(const charT* s, const Allocator& a = Allocator());
 ```
 *Constraints:* `Allocator` is a type that qualifies as an
+allocator [[container.reqmts]].
 [*Note 1*: This affects class template argument
 deduction. — *end note*]
 *Effects:* Equivalent to: `basic_string(s, traits::length(s), a)`.
 ``` cpp
 constexpr basic_string(size_type n, charT c, const Allocator& a = Allocator());
 ```
 *Constraints:* `Allocator` is a type that qualifies as an
+allocator [[container.reqmts]].
 [*Note 2*: This affects class template argument
 deduction. — *end note*]
 *Effects:* Constructs an object whose value consists of `n` copies of
 template<class InputIterator>
   constexpr basic_string(InputIterator begin, InputIterator end, const Allocator& a = Allocator());
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
+iterator [[container.reqmts]].
 *Effects:* Constructs a string from the values in the range \[`begin`,
 `end`), as specified in [[sequence.reqmts]].
 ``` cpp
                     Allocator>;
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
 iterator, and `Allocator` is a type that qualifies as an
+allocator [[container.reqmts]].
 ``` cpp
 template<class charT,
          class traits,
          class Allocator = allocator<charT>>
                const Allocator& = Allocator())
     -> basic_string<charT, traits, Allocator>;
 ```
 *Constraints:* `Allocator` is a type that qualifies as an
+allocator [[container.reqmts]].
 ``` cpp
 constexpr basic_string& operator=(const basic_string& str);
 ```
 constexpr basic_string& operator=(basic_string&& str)
   noexcept(allocator_traits<Allocator>::propagate_on_container_move_assignment::value ||
            allocator_traits<Allocator>::is_always_equal::value);
 ```
+*Effects:* Move assigns as a sequence container [[sequence.reqmts]],
+except that iterators, pointers and references may be invalidated.
 *Returns:* `*this`.
 ``` cpp
 template<class T>
 constexpr void reserve(size_type res_arg);
 ```
 *Effects:* A directive that informs a `basic_string` of a planned change
 in size, so that the storage allocation can be managed accordingly.
+Following a call to `reserve`, `capacity()` is greater or equal to the
+argument of `reserve` if reallocation happens; and equal to the previous
+value of `capacity()` otherwise. Reallocation happens at this point if
+and only if the current capacity is less than the argument of `reserve`.
 *Throws:* `length_error` if `res_arg > max_size()` or any exceptions
 thrown by `allocator_traits` `<Allocator>::allocate`.
 ``` cpp
 ```
 *Effects:* Equivalent to: `erase(begin(), end());`
 ``` cpp
+constexpr bool empty() const noexcept;
 ```
 *Effects:* Equivalent to: `return size() == 0;`
 #### Element access <a id="string.access">[[string.access]]</a>
 ``` cpp
 constexpr const_reference operator[](size_type pos) const;
 constexpr reference       operator[](size_type pos);
 ```
+`pos <= size()` is `true`.
 *Returns:* `*(begin() + pos)` if `pos < size()`. Otherwise, returns a
 reference to an object of type `charT` with value `charT()`, where
 modifying the object to any value other than `charT()` leads to
 undefined behavior.
 ``` cpp
 constexpr const charT& front() const;
 constexpr charT& front();
 ```
+`empty()` is `false`.
 *Effects:* Equivalent to: `return operator[](0);`
 ``` cpp
 constexpr const charT& back() const;
 constexpr charT& back();
 ```
+`empty()` is `false`.
 *Effects:* Equivalent to: `return operator[](size() - 1);`
 #### Modifiers <a id="string.modifiers">[[string.modifiers]]</a>
 template<class InputIterator>
   constexpr basic_string& append(InputIterator first, InputIterator last);
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
+iterator [[container.reqmts]].
 *Effects:* Equivalent to:
 `return append(basic_string(first, last, get_allocator()));`
 ``` cpp
 template<class InputIterator>
   constexpr basic_string& assign(InputIterator first, InputIterator last);
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
+iterator [[container.reqmts]].
 *Effects:* Equivalent to:
 `return assign(basic_string(first, last, get_allocator()));`
 ``` cpp
 ```
 *Effects:* Inserts `n` copies of `c` before the character at position
 `pos` if `pos < size()`, or otherwise at the end of the string.
+*Returns:* `*this`.
 *Throws:*
 - `out_of_range` if `pos > size()`,
 - `length_error` if `n > max_size() - size()`, or
 template<class InputIterator>
   constexpr iterator insert(const_iterator p, InputIterator first, InputIterator last);
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
+iterator [[container.reqmts]].
 *Preconditions:* `p` is a valid iterator on `*this`.
 *Effects:* Equivalent to
 `insert(p - begin(), basic_string(first, last, get_allocator()))`.
 ```
 *Preconditions:* `first` and `last` are valid iterators on `*this`.
 \[`first`, `last`) is a valid range.
+*Effects:* Removes the characters in the range \[`first`, `last`).
 *Returns:* An iterator which points to the element pointed to by `last`
 prior to the other elements being erased. If no such element exists,
 `end()` is returned.
 ``` cpp
 constexpr void pop_back();
 ```
+`empty()` is `false`.
 *Effects:* Equivalent to `erase(end() - 1)`.
 *Throws:* Nothing.
 *Returns:* `*this`.
 *Throws:*
 - `out_of_range` if `pos1 > size()`,
+- `length_error` if the length of the resulting string would exceed
+  `max_size()`, or
 - any exceptions thrown by `allocator_traits<Allocator>::allocate.`
 ``` cpp
 constexpr basic_string& replace(const_iterator i1, const_iterator i2, const basic_string& str);
 ```
   constexpr basic_string& replace(const_iterator i1, const_iterator i2,
                                   InputIterator j1, InputIterator j2);
 ```
 *Constraints:* `InputIterator` is a type that qualifies as an input
+iterator [[container.reqmts]].
 *Effects:* Equivalent to:
 `return replace(i1, i2, basic_string(j1, j2, get_allocator()));`
 ``` cpp
 ```
 *Effects:* Equivalent to:
 `return basic_string(std::move(*this), pos, n);`
+``` cpp
+constexpr basic_string_view<charT, traits> subview(size_type pos = 0, size_type n = npos) const;
+```
+*Effects:* Equivalent to:
+`return basic_string_view<charT, traits>(*this).subview(pos, n);`
 ##### `basic_string::compare` <a id="string.compare">[[string.compare]]</a>
 ``` cpp
 template<class T>
   constexpr int compare(const T& t) const noexcept(see below);

Diff to HTML by rtfpessoa