21 Strings library [strings]

21.4 String view classes [string.view]

21.4.2 Class template basic_­string_­view [string.view.template]

namespace std {
  template<class charT, class traits = char_traits<charT>>
  class basic_string_view {
  public:
    // types
    using traits_type            = traits;
    using value_type             = charT;
    using pointer                = value_type*;
    using const_pointer          = const value_type*;
    using reference              = value_type&;
    using const_reference        = const value_type&;
    using const_iterator         = implementation-defined; // see [string.view.iterators]
    using iterator               = const_iterator;223
    using const_reverse_iterator = reverse_iterator<const_iterator>;
    using reverse_iterator       = const_reverse_iterator;
    using size_type              = size_t;
    using difference_type        = ptrdiff_t;
    static constexpr size_type npos = size_type(-1);

    // [string.view.cons], construction and assignment
    constexpr basic_string_view() noexcept;
    constexpr basic_string_view(const basic_string_view&) noexcept = default;
    constexpr basic_string_view& operator=(const basic_string_view&) noexcept = default;
    constexpr basic_string_view(const charT* str);
    constexpr basic_string_view(const charT* str, size_type len);
    template<class It, class End>
      constexpr basic_string_view(It begin, End end);

    // [string.view.iterators], iterator support
    constexpr const_iterator begin() const noexcept;
    constexpr const_iterator end() const noexcept;
    constexpr const_iterator cbegin() const noexcept;
    constexpr const_iterator cend() const noexcept;
    constexpr const_reverse_iterator rbegin() const noexcept;
    constexpr const_reverse_iterator rend() const noexcept;
    constexpr const_reverse_iterator crbegin() const noexcept;
    constexpr const_reverse_iterator crend() const noexcept;

    // [string.view.capacity], capacity
    constexpr size_type size() const noexcept;
    constexpr size_type length() const noexcept;
    constexpr size_type max_size() const noexcept;
    [[nodiscard]] constexpr bool empty() const noexcept;

    // [string.view.access], element access
    constexpr const_reference operator[](size_type pos) const;
    constexpr const_reference at(size_type pos) const;
    constexpr const_reference front() const;
    constexpr const_reference back() const;
    constexpr const_pointer data() const noexcept;

    // [string.view.modifiers], modifiers
    constexpr void remove_prefix(size_type n);
    constexpr void remove_suffix(size_type n);
    constexpr void swap(basic_string_view& s) noexcept;

    // [string.view.ops], string operations
    constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;

    constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;

    constexpr int compare(basic_string_view s) const noexcept;
    constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const;
    constexpr int compare(size_type pos1, size_type n1, basic_string_view s,
                          size_type pos2, size_type n2) const;
    constexpr int compare(const charT* s) const;
    constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
    constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;

    constexpr bool starts_with(basic_string_view x) const noexcept;
    constexpr bool starts_with(charT x) const noexcept;
    constexpr bool starts_with(const charT* x) const;
    constexpr bool ends_with(basic_string_view x) const noexcept;
    constexpr bool ends_with(charT x) const noexcept;
    constexpr bool ends_with(const charT* x) const;

    // [string.view.find], searching
    constexpr size_type find(basic_string_view s, size_type pos = 0) const noexcept;
    constexpr size_type find(charT c, size_type pos = 0) const noexcept;
    constexpr size_type find(const charT* s, size_type pos, size_type n) const;
    constexpr size_type find(const charT* s, size_type pos = 0) const;
    constexpr size_type rfind(basic_string_view s, size_type pos = npos) const noexcept;
    constexpr size_type rfind(charT c, size_type pos = npos) const noexcept;
    constexpr size_type rfind(const charT* s, size_type pos, size_type n) const;
    constexpr size_type rfind(const charT* s, size_type pos = npos) const;

    constexpr size_type find_first_of(basic_string_view s, size_type pos = 0) const noexcept;
    constexpr size_type find_first_of(charT c, size_type pos = 0) const noexcept;
    constexpr size_type find_first_of(const charT* s, size_type pos, size_type n) const;
    constexpr size_type find_first_of(const charT* s, size_type pos = 0) const;
    constexpr size_type find_last_of(basic_string_view s, size_type pos = npos) const noexcept;
    constexpr size_type find_last_of(charT c, size_type pos = npos) const noexcept;
    constexpr size_type find_last_of(const charT* s, size_type pos, size_type n) const;
    constexpr size_type find_last_of(const charT* s, size_type pos = npos) const;
    constexpr size_type find_first_not_of(basic_string_view s, size_type pos = 0) const noexcept;
    constexpr size_type find_first_not_of(charT c, size_type pos = 0) const noexcept;
    constexpr size_type find_first_not_of(const charT* s, size_type pos,
                                          size_type n) const;
    constexpr size_type find_first_not_of(const charT* s, size_type pos = 0) const;
    constexpr size_type find_last_not_of(basic_string_view s,
                                         size_type pos = npos) const noexcept;
    constexpr size_type find_last_not_of(charT c, size_type pos = npos) const noexcept;
    constexpr size_type find_last_not_of(const charT* s, size_type pos,
                                         size_type n) const;
    constexpr size_type find_last_not_of(const charT* s, size_type pos = npos) const;

  private:
    const_pointer data_;        // exposition only
    size_type size_;            // exposition only
  };

  // [string.view.deduct], deduction guide
  template<class It, class End>
    basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
}
1
#
In every specialization basic_­string_­view<charT, traits>, the type traits shall meet the character traits requirements ([char.traits]).
[Note
:
The program is ill-formed if traits​::​char_­type is not the same type as charT.
— end note
]
2
#
For a basic_­string_­view str, any operation that invalidates a pointer in the range [str.data(), ​str.data() + str.size()) invalidates pointers, iterators, and references returned from str's member functions.
3
#
The complexity of basic_­string_­view member functions is unless otherwise specified.
223)
Because basic_­string_­view refers to a constant sequence, iterator and const_­iterator are the same type.
⮥

21.4.2.1 Construction and assignment [string.view.cons]

🔗
constexpr basic_string_view() noexcept;
1
#
Postconditions: size_­ == 0 and data_­ == nullptr.
🔗
constexpr basic_string_view(const charT* str);
2
#
Preconditions: [str, str + traits​::​length(str)) is a valid range.
3
#
Effects: Constructs a basic_­string_­view, initializing data_­ with str and initializing size_­ with traits​::​length(str).
4
#
Complexity: .
🔗
constexpr basic_string_view(const charT* str, size_type len);
5
#
Preconditions: [str, str + len) is a valid range.
6
#
Effects: Constructs a basic_­string_­view, initializing data_­ with str and initializing size_­ with len.
🔗
template<class It, class End> constexpr basic_string_view(It begin, End end);
7
#
Constraints:
  • (7.1)
    It satisfies contiguous_­iterator.
  • (7.2)
    End satisfies sized_­sentinel_­for<It>.
  • (7.3)
    is_­same_­v<iter_­value_­t<It>, charT> is true.
  • (7.4)
    is_­convertible_­v<End, size_­type> is false.
8
#
Preconditions:
  • (8.1)
    [begin, end) is a valid range.
  • (8.2)
    It models contiguous_­iterator.
  • (8.3)
    End models sized_­sentinel_­for<It>.
9
#
Effects: Initializes data_­ with to_­address(begin) and initializes size_­ with end - begin.

21.4.2.2 Iterator support [string.view.iterators]

🔗
using const_iterator = implementation-defined;
1
#
A type that meets the requirements of a constant Cpp17RandomAccessIterator ([random.access.iterators]), models contiguous_­iterator ([iterator.concept.contiguous]), and meets the constexpr iterator requirements ([iterator.requirements.general]), whose value_­type is the template parameter charT.
2
#
All requirements on container iterators ([container.requirements]) apply to basic_­string_­view​::​const_­iterator as well.
🔗
constexpr const_iterator begin() const noexcept; constexpr const_iterator cbegin() const noexcept;
3
#
Returns: An iterator such that
  • (3.1)
    if !empty(), addressof(*begin()) == data_­,
  • (3.2)
    otherwise, an unspecified value such that [begin(), end()) is a valid range.
🔗
constexpr const_iterator end() const noexcept; constexpr const_iterator cend() const noexcept;
4
#
Returns: begin() + size().
🔗
constexpr const_reverse_iterator rbegin() const noexcept; constexpr const_reverse_iterator crbegin() const noexcept;
5
#
Returns: const_­reverse_­iterator(end()).
🔗
constexpr const_reverse_iterator rend() const noexcept; constexpr const_reverse_iterator crend() const noexcept;
6
#
Returns: const_­reverse_­iterator(begin()).

21.4.2.3 Capacity [string.view.capacity]

🔗
constexpr size_type size() const noexcept; constexpr size_type length() const noexcept;
1
#
Returns: size_­.
🔗
constexpr size_type max_size() const noexcept;
2
#
Returns: The largest possible number of char-like objects that can be referred to by a basic_­string_­view.
🔗
[[nodiscard]] constexpr bool empty() const noexcept;
3
#
Returns: size_­ == 0.

21.4.2.4 Element access [string.view.access]

🔗
constexpr const_reference operator[](size_type pos) const;
1
#
Preconditions: pos < size().
2
#
Returns: data_­[pos].
3
#
Throws: Nothing.
4
#
[Note
:
Unlike basic_­string​::​operator[], basic_­string_­view​::​operator[](size()) has undefined behavior instead of returning charT().
— end note
]
🔗
constexpr const_reference at(size_type pos) const;
5
#
Throws: out_­of_­range if pos >= size().
6
#
Returns: data_­[pos].
🔗
constexpr const_reference front() const;
7
#
Preconditions: !empty().
8
#
Returns: data_­[0].
9
#
Throws: Nothing.
🔗
constexpr const_reference back() const;
10
#
Preconditions: !empty().
11
#
Returns: data_­[size() - 1].
12
#
Throws: Nothing.
🔗
constexpr const_pointer data() const noexcept;
13
#
Returns: data_­.
14
#
[Note
:
Unlike basic_­string​::​data() and string-literals, data() may return a pointer to a buffer that is not null-terminated.
Therefore it is typically a mistake to pass data() to a function that takes just a const charT* and expects a null-terminated string.
— end note
]

21.4.2.5 Modifiers [string.view.modifiers]

🔗
constexpr void remove_prefix(size_type n);
1
#
Preconditions: n <= size().
2
#
Effects: Equivalent to: data_­ += n; size_­ -= n;
🔗
constexpr void remove_suffix(size_type n);
3
#
Preconditions: n <= size().
4
#
Effects: Equivalent to: size_­ -= n;
🔗
constexpr void swap(basic_string_view& s) noexcept;
5
#
Effects: Exchanges the values of *this and s.

21.4.2.6 String operations [string.view.ops]

🔗
constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
1
#
Let rlen be the smaller of n and size() - pos.
2
#
Throws: out_­of_­range if pos > size().
3
#
Preconditions: [s, s + rlen) is a valid range.
4
#
Effects: Equivalent to traits​::​copy(s, data() + pos, rlen).
5
#
Returns: rlen.
6
#
Complexity: .
🔗
constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
7
#
Let rlen be the smaller of n and size() - pos.
8
#
Throws: out_­of_­range if pos > size().
9
#
Effects: Determines rlen, the effective length of the string to reference.
10
#
Returns: basic_­string_­view(data() + pos, rlen).
🔗
constexpr int compare(basic_string_view str) const noexcept;
11
#
Let rlen be the smaller of size() and str.size().
12
#
Effects: Determines rlen, the effective length of the strings to compare.
The function then compares the two strings by calling traits​::​compare(data(), str.data(), rlen).
13
#
Complexity: .
14
#
Returns: The nonzero result if the result of the comparison is nonzero.
Otherwise, returns a value as indicated in Table 70.
Table 70: compare() results   [tab:string.view.compare]
Condition
Return Value
size() < str.size()
< 0
size() == str.size()
 0
size() > str.size()
> 0
🔗
constexpr int compare(size_type pos1, size_type n1, basic_string_view str) const;
15
#
Effects: Equivalent to: return substr(pos1, n1).compare(str);
🔗
constexpr int compare(size_type pos1, size_type n1, basic_string_view str, size_type pos2, size_type n2) const;
16
#
Effects: Equivalent to: return substr(pos1, n1).compare(str.substr(pos2, n2));
🔗
constexpr int compare(const charT* s) const;
17
#
Effects: Equivalent to: return compare(basic_­string_­view(s));
🔗
constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
18
#
Effects: Equivalent to: return substr(pos1, n1).compare(basic_­string_­view(s));
🔗
constexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const;
19
#
Effects: Equivalent to: return substr(pos1, n1).compare(basic_­string_­view(s, n2));
🔗
constexpr bool starts_with(basic_string_view x) const noexcept;
20
#
Effects: Equivalent to: return substr(0, x.size()) == x;
🔗
constexpr bool starts_with(charT x) const noexcept;
21
#
Effects: Equivalent to: return !empty() && traits​::​eq(front(), x);
🔗
constexpr bool starts_with(const charT* x) const;
22
#
Effects: Equivalent to: return starts_­with(basic_­string_­view(x));
🔗
constexpr bool ends_with(basic_string_view x) const noexcept;
23
#
Effects: Equivalent to: 
return size() >= x.size() && compare(size() - x.size(), npos, x) == 0;
🔗
constexpr bool ends_with(charT x) const noexcept;
24
#
Effects: Equivalent to: return !empty() && traits​::​eq(back(), x);
🔗
constexpr bool ends_with(const charT* x) const;
25
#
Effects: Equivalent to: return ends_­with(basic_­string_­view(x));

21.4.2.7 Searching [string.view.find]

1
#
Member functions in this subclause have complexity at worst, although implementations should do better.
2
#
Let F be one of find, rfind, find_­first_­of, find_­last_­of, find_­first_­not_­of, and find_­last_­not_­of.
  • (2.1)
    Each member function of the form 
    constexpr return-type F(const charT* s, size_type pos) const;
    has effects equivalent to: return F(basic_­string_­view(s), pos);
  • (2.2)
    Each member function of the form 
    constexpr return-type F(const charT* s, size_type pos, size_type n) const;
    has effects equivalent to: return F(basic_­string_­view(s, n), pos);
  • (2.3)
    Each member function of the form 
    constexpr return-type F(charT c, size_type pos) const noexcept;
    has effects equivalent to: return F(basic_­string_­view(addressof(c), 1), pos);
🔗
constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
3
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (3.1)
    pos <= xpos
  • (3.2)
    xpos + str.size() <= size()
  • (3.3)
    traits​::​eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.
4
#
Effects: Determines xpos.
5
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
🔗
constexpr size_type rfind(basic_string_view str, size_type pos = npos) const noexcept;
6
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (6.1)
    xpos <= pos
  • (6.2)
    xpos + str.size() <= size()
  • (6.3)
    traits​::​eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.
7
#
Effects: Determines xpos.
8
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
🔗
constexpr size_type find_first_of(basic_string_view str, size_type pos = 0) const noexcept;
9
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (9.1)
    pos <= xpos
  • (9.2)
    xpos < size()
  • (9.3)
    traits​::​eq(at(xpos), str.at(I)) for some element I of the string referenced by str.
10
#
Effects: Determines xpos.
11
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
🔗
constexpr size_type find_last_of(basic_string_view str, size_type pos = npos) const noexcept;
12
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (12.1)
    xpos <= pos
  • (12.2)
    xpos < size()
  • (12.3)
    traits​::​eq(at(xpos), str.at(I)) for some element I of the string referenced by str.
13
#
Effects: Determines xpos.
14
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
🔗
constexpr size_type find_first_not_of(basic_string_view str, size_type pos = 0) const noexcept;
15
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (15.1)
    pos <= xpos
  • (15.2)
    xpos < size()
  • (15.3)
    traits​::​eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
16
#
Effects: Determines xpos.
17
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.
🔗
constexpr size_type find_last_not_of(basic_string_view str, size_type pos = npos) const noexcept;
18
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (18.1)
    xpos <= pos
  • (18.2)
    xpos < size()
  • (18.3)
    traits​::​eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
19
#
Effects: Determines xpos.
20
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.