23 Strings library [strings]

23.3 String view classes [string.view]

23.3.3 Class template basic_string_view [string.view.template]

23.3.3.1 General [string.view.template.general]

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;206 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); basic_string_view(nullptr_t) = delete; constexpr basic_string_view(const charT* str, size_type len); template<class It, class End> constexpr basic_string_view(It begin, End end); template<class R> constexpr explicit basic_string_view(R&& r); // [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; constexpr bool contains(basic_string_view x) const noexcept; constexpr bool contains(charT x) const noexcept; constexpr bool contains(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 guides template<class It, class End> basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>; template<class R> basic_string_view(R&&) -> basic_string_view<ranges::range_value_t<R>>; }
In every specialization basic_string_view<charT, traits>, the type traits shall meet the character traits requirements ([char.traits]).
[Note 1: 
The program is ill-formed if traits​::​char_type is not the same type as charT.
— end note]
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.
The complexity of basic_string_view member functions is unless otherwise specified.
basic_string_view<charT, traits> is a trivially copyable type ([basic.types.general]).
206)206)
Because basic_string_view refers to a constant sequence, iterator and const_iterator are the same type.

23.3.3.2 Construction and assignment [string.view.cons]

constexpr basic_string_view() noexcept;
Postconditions: size_ == 0 and data_ == nullptr.
constexpr basic_string_view(const charT* str);
Preconditions: [str, str + traits​::​length(str)) is a valid range.
Effects: Constructs a basic_string_view, initializing data_ with str and initializing size_ with traits​::​length(str).
Complexity: .
constexpr basic_string_view(const charT* str, size_type len);
Preconditions: [str, str + len) is a valid range.
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);
Constraints:
Preconditions:
Effects: Initializes data_ with to_address(begin) and initializes size_ with end - begin.
Throws: When and what end - begin throws.
template<class R> constexpr explicit basic_string_view(R&& r);
Let d be an lvalue of type remove_cvref_t<R>.
Constraints:
  • remove_cvref_t<R> is not the same type as basic_string_view,
  • R models ranges​::​contiguous_range and ranges​::​sized_range,
  • is_same_v<ranges​::​range_value_t<R>, charT> is true,
  • is_convertible_v<R, const charT*> is false, and
  • d.operator ​::​std​::​basic_string_view<charT, traits>() is not a valid expression.
Effects: Initializes data_ with ranges​::​data(r) and size_ with ranges​::​size(r).
Throws: Any exception thrown by ranges​::​data(r) and ranges​::​size(r).

23.3.3.3 Deduction guides [string.view.deduct]

template<class It, class End> basic_string_view(It, End) -> basic_string_view<iter_value_t<It>>;
Constraints:
template<class R> basic_string_view(R&&) -> basic_string_view<ranges::range_value_t<R>>;
Constraints: R satisfies ranges​::​contiguous_range.

23.3.3.4 Iterator support [string.view.iterators]

using const_iterator = implementation-defined;
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.
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;
Returns: An iterator such that
  • if !empty(), addressof(*begin()) == data_,
  • otherwise, an unspecified value such that [begin(), end()) is a valid range.
constexpr const_iterator end() const noexcept; constexpr const_iterator cend() const noexcept;
Returns: begin() + size().
constexpr const_reverse_iterator rbegin() const noexcept; constexpr const_reverse_iterator crbegin() const noexcept;
Returns: const_reverse_iterator(end()).
constexpr const_reverse_iterator rend() const noexcept; constexpr const_reverse_iterator crend() const noexcept;
Returns: const_reverse_iterator(begin()).

23.3.3.5 Capacity [string.view.capacity]

constexpr size_type size() const noexcept; constexpr size_type length() const noexcept;
Returns: size_.
constexpr size_type max_size() const noexcept;
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;
Returns: size_ == 0.

23.3.3.6 Element access [string.view.access]

constexpr const_reference operator[](size_type pos) const;
Preconditions: pos < size().
Returns: data_[pos].
Throws: Nothing.
[Note 1: 
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;
Returns: data_[pos].
Throws: out_of_range if pos >= size().
constexpr const_reference front() const;
Preconditions: !empty().
Returns: data_[0].
Throws: Nothing.
constexpr const_reference back() const;
Preconditions: !empty().
Returns: data_[size() - 1].
Throws: Nothing.
constexpr const_pointer data() const noexcept;
Returns: data_.
[Note 2: 
Unlike basic_string​::​data() and string-literals, data() can 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]

23.3.3.7 Modifiers [string.view.modifiers]

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

23.3.3.8 String operations [string.view.ops]

constexpr size_type copy(charT* s, size_type n, size_type pos = 0) const;
Let rlen be the smaller of n and size() - pos.
Preconditions: [s, s + rlen) is a valid range.
Effects: Equivalent to traits​::​copy(s, data() + pos, rlen).
Returns: rlen.
Throws: out_of_range if pos > size().
Complexity: .
constexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const;
Let rlen be the smaller of n and size() - pos.
Effects: Determines rlen, the effective length of the string to reference.
Returns: basic_string_view(data() + pos, rlen).
Throws: out_of_range if pos > size().
constexpr int compare(basic_string_view str) const noexcept;
Let rlen be the smaller of size() and str.size().
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).
Returns: The nonzero result if the result of the comparison is nonzero.
Otherwise, returns a value as indicated in Table 80.
Table 80: compare() results [tab:string.view.compare]
Condition
Return Value
size() < str.size()
< 0
size() == str.size()
 0
size() > str.size()
> 0
Complexity: .
constexpr int compare(size_type pos1, size_type n1, basic_string_view str) const;
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;
Effects: Equivalent to: return substr(pos1, n1).compare(str.substr(pos2, n2));
constexpr int compare(const charT* s) const;
Effects: Equivalent to: return compare(basic_string_view(s));
constexpr int compare(size_type pos1, size_type n1, const charT* s) const;
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;
Effects: Equivalent to: return substr(pos1, n1).compare(basic_string_view(s, n2));
constexpr bool starts_with(basic_string_view x) const noexcept;
Effects: Equivalent to: return substr(0, x.size()) == x;
constexpr bool starts_with(charT x) const noexcept;
Effects: Equivalent to: return !empty() && traits​::​eq(front(), x);
constexpr bool starts_with(const charT* x) const;
Effects: Equivalent to: return starts_with(basic_string_view(x));
constexpr bool ends_with(basic_string_view x) const noexcept;
Effects: Equivalent to: return size() >= x.size() && compare(size() - x.size(), npos, x) == 0;
constexpr bool ends_with(charT x) const noexcept;
Effects: Equivalent to: return !empty() && traits​::​eq(back(), x);
constexpr bool ends_with(const charT* x) const;
Effects: Equivalent to: return ends_with(basic_string_view(x));
constexpr bool contains(basic_string_view x) const noexcept; constexpr bool contains(charT x) const noexcept; constexpr bool contains(const charT* x) const;
Effects: Equivalent to: return find(x) != npos;

23.3.3.9 Searching [string.view.find]

Member functions in this subclause have complexity at worst, although implementations should do better.
Let F be one of find, rfind, find_first_of, find_last_of, find_first_not_of, and find_last_not_of.
  • 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);
  • 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);
  • 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;
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • pos <= xpos
  • xpos + str.size() <= size()
  • traits​::​eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.
Effects: Determines xpos.
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;
Let xpos be the highest position, if possible, such that the following conditions hold:
  • xpos <= pos
  • xpos + str.size() <= size()
  • traits​::​eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.
Effects: Determines xpos.
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;
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • pos <= xpos
  • xpos < size()
  • traits​::​eq(at(xpos), str.at(I)) for some element I of the string referenced by str.
Effects: Determines xpos.
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;
Let xpos be the highest position, if possible, such that the following conditions hold:
  • xpos <= pos
  • xpos < size()
  • traits​::​eq(at(xpos), str.at(I)) for some element I of the string referenced by str.
Effects: Determines xpos.
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;
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • pos <= xpos
  • xpos < size()
  • traits​::​eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
Effects: Determines xpos.
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;
Let xpos be the highest position, if possible, such that the following conditions hold:
  • xpos <= pos
  • xpos < size()
  • traits​::​eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
Effects: Determines xpos.
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.