24 Strings library [strings]

24.4 String view classes [string.view]

1
#
The class template basic_­string_­view describes an object that can refer to a constant contiguous sequence of char-like ([strings.general]) objects with the first element of the sequence at position zero.
In the rest of this section, the type of the char-like objects held in a basic_­string_­view object is designated by charT.
2
#
[ Note
:
The library provides implicit conversions from const charT* and std​::​basic_­string<charT, ...> to std​::​basic_­string_­view<charT, ...> so that user code can accept just std​::​basic_­string_­view<charT> as a non-templated parameter wherever a sequence of characters is expected.
User-defined types should define their own implicit conversions to std​::​basic_­string_­view in order to interoperate with these functions.
— end note
 ]
3
#
The complexity of basic_­string_­view member functions is unless otherwise specified.

24.4.1 Header <string_­view> synopsis [string.view.synop]

namespace std {
  // [string.view.template], class template basic_­string_­view
  template<class charT, class traits = char_traits<charT>>
  class basic_string_view;

  // [string.view.comparison], non-member comparison functions
  template<class charT, class traits>
    constexpr bool operator==(basic_string_view<charT, traits> x,
                              basic_string_view<charT, traits> y) noexcept;
  template<class charT, class traits>
    constexpr bool operator!=(basic_string_view<charT, traits> x,
                              basic_string_view<charT, traits> y) noexcept;
  template<class charT, class traits>
    constexpr bool operator< (basic_string_view<charT, traits> x,
                              basic_string_view<charT, traits> y) noexcept;
  template<class charT, class traits>
    constexpr bool operator> (basic_string_view<charT, traits> x,
                              basic_string_view<charT, traits> y) noexcept;
  template<class charT, class traits>
    constexpr bool operator<=(basic_string_view<charT, traits> x,
                              basic_string_view<charT, traits> y) noexcept;
  template<class charT, class traits>
    constexpr bool operator>=(basic_string_view<charT, traits> x,
                              basic_string_view<charT, traits> y) noexcept;
  // see [string.view.comparison], sufficient additional overloads of comparison functions

  // [string.view.io], inserters and extractors
  template<class charT, class traits>
    basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os,
                 basic_string_view<charT, traits> str);

  // basic_­string_­view typedef names
  using string_view    = basic_string_view<char>;
  using u16string_view = basic_string_view<char16_t>;
  using u32string_view = basic_string_view<char32_t>;
  using wstring_view   = basic_string_view<wchar_t>;

  // [string.view.hash], hash support
  template<class T> struct hash;
  template<> struct hash<string_view>;
  template<> struct hash<u16string_view>;
  template<> struct hash<u32string_view>;
  template<> struct hash<wstring_view>;

  inline namespace literals {
  inline namespace string_view_literals {
    // [string.view.literals], suffix for basic_­string_­view literals
    constexpr string_view    operator""sv(const char* str, size_t len) noexcept;
    constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
    constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
    constexpr wstring_view   operator""sv(const wchar_t* str, size_t len) noexcept;
  }
  }
}
1
#
The function templates defined in [utility.swap] and [iterator.range] are available when <string_­view> is included.

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

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;228
  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);

  // [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;
  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
  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 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
};
1
#
In every specialization basic_­string_­view<charT, traits>, the type traits shall satisfy the character traits requirements ([char.traits]), and the type traits​::​char_­type shall name the same type as charT.
228)
Because basic_­string_­view refers to a constant sequence, iterator and const_­iterator are the same type.

24.4.2.1 Construction and assignment [string.view.cons]

constexpr basic_string_view() noexcept;
1
#
Effects: Constructs an empty basic_­string_­view.
2
#
Postconditions: size_­ == 0 and data_­ == nullptr.
constexpr basic_string_view(const charT* str);
3
#
Requires: [str, str + traits​::​length(str)) is a valid range.
4
#
Effects: Constructs a basic_­string_­view, with the postconditions in Table 59.
Table 59 — basic_­string_­view(const charT*) effects
Element
Value
data_­
str
size_­
traits​::​length(str)
5
#
Complexity: .
constexpr basic_string_view(const charT* str, size_type len);
6
#
Requires: [str, str + len) is a valid range.
7
#
Effects: Constructs a basic_­string_­view, with the postconditions in Table 60.
Table 60 — basic_­string_­view(const charT*, size_­type) effects
Element
Value
data_­
str
size_­
len

24.4.2.2 Iterator support [string.view.iterators]

using const_iterator = implementation-defined;
1
#
A type that meets the requirements of a constant random access iterator ([random.access.iterators]) and of a contiguous iterator ([iterator.requirements.general]) whose value_­type is the template parameter charT.
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 methods.
3
#
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;
4
#
Returns: An iterator such that
  • (4.1)
    if !empty(), &*begin() == data_­,
  • (4.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;
5
#
Returns: begin() + size().
constexpr const_reverse_iterator rbegin() const noexcept; constexpr const_reverse_iterator crbegin() const noexcept;
6
#
Returns: const_­reverse_­iterator(end()).
constexpr const_reverse_iterator rend() const noexcept; constexpr const_reverse_iterator crend() const noexcept;
7
#
Returns: const_­reverse_­iterator(begin()).

24.4.2.3 Capacity [string.view.capacity]

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

24.4.2.4 Element access [string.view.access]

constexpr const_reference operator[](size_type pos) const;
1
#
Requires: 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
#
Requires: !empty().
8
#
Returns: data_­[0].
9
#
Throws: Nothing.
constexpr const_reference back() const;
10
#
Requires: !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
 ]

24.4.2.5 Modifiers [string.view.modifiers]

constexpr void remove_prefix(size_type n);
1
#
Requires: n <= size().
2
#
Effects: Equivalent to: data_­ += n; size_­ -= n;
constexpr void remove_suffix(size_type n);
3
#
Requires: 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.

24.4.2.6 String operations [string.view.ops]

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
#
Requires: [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 61.
Table 61 — compare() results
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));

24.4.2.7 Searching [string.view.find]

1
#
This section specifies the basic_­string_­view member functions named find, rfind, find_­first_­of, find_­last_­of, find_­first_­not_­of, and find_­last_­not_­of.
2
#
Member functions in this section have complexity at worst, although implementations are encouraged to do better.
3
#
Each member function of the form 
constexpr return-type F(const charT* s, size_type pos);
is equivalent to return F(basic_­string_­view(s), pos);
4
#
Each member function of the form 
constexpr return-type F(const charT* s, size_type pos, size_type n);
is equivalent to return F(basic_­string_­view(s, n), pos);
5
#
Each member function of the form 
constexpr return-type F(charT c, size_type pos);
is equivalent to return F(basic_­string_­view(&c, 1), pos);
constexpr size_type find(basic_string_view str, size_type pos = 0) const noexcept;
6
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (6.1)
    pos <= xpos
  • (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 rfind(basic_string_view str, size_type pos = npos) const noexcept;
9
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (9.1)
    xpos <= pos
  • (9.2)
    xpos + str.size() <= size()
  • (9.3)
    traits​::​eq(at(xpos + I), str.at(I)) for all elements 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_first_of(basic_string_view str, size_type pos = 0) const noexcept;
12
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (12.1)
    pos <= xpos
  • (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_last_of(basic_string_view str, size_type pos = npos) const noexcept;
15
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (15.1)
    xpos <= pos
  • (15.2)
    xpos < size()
  • (15.3)
    traits​::​eq(at(xpos), str.at(I)) for some 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_first_not_of(basic_string_view str, size_type pos = 0) const noexcept;
18
#
Let xpos be the lowest position, if possible, such that the following conditions hold:
  • (18.1)
    pos <= xpos
  • (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.
constexpr size_type find_last_not_of(basic_string_view str, size_type pos = npos) const noexcept;
21
#
Let xpos be the highest position, if possible, such that the following conditions hold:
  • (21.1)
    xpos <= pos
  • (21.2)
    xpos < size()
  • (21.3)
    traits​::​eq(at(xpos), str.at(I)) for no element I of the string referenced by str.
22
#
Effects: Determines xpos.
23
#
Returns: xpos if the function can determine such a value for xpos.
Otherwise, returns npos.

24.4.3 Non-member comparison functions [string.view.comparison]

1
#
Let S be basic_­string_­view<charT, traits>, and sv be an instance of S.
Implementations shall provide sufficient additional overloads marked constexpr and noexcept so that an object t with an implicit conversion to S can be compared according to Table 62.
Table 62 — Additional basic_­string_­view comparison overloads
Expression
Equivalent to
t == sv
S(t) == sv
sv == t
sv == S(t)
t != sv
S(t) != sv
sv != t
sv != S(t)
t < sv
S(t) < sv
sv < t
sv < S(t)
t > sv
S(t) > sv
sv > t
sv > S(t)
t <= sv
S(t) <= sv
sv <= t
sv <= S(t)
t >= sv
S(t) >= sv
sv >= t
sv >= S(t)
[ Example
:
A sample conforming implementation for operator== would be: 
template<class T> using __identity = decay_t<T>;
template<class charT, class traits>
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
                            basic_string_view<charT, traits> rhs) noexcept {
    return lhs.compare(rhs) == 0;
  }
template<class charT, class traits>
  constexpr bool operator==(basic_string_view<charT, traits> lhs,
                            __identity<basic_string_view<charT, traits>> rhs) noexcept {
    return lhs.compare(rhs) == 0;
  }
template<class charT, class traits>
  constexpr bool operator==(__identity<basic_string_view<charT, traits>> lhs,
                            basic_string_view<charT, traits> rhs) noexcept {
    return lhs.compare(rhs) == 0;
  }
— end example
 ]
template<class charT, class traits> constexpr bool operator==(basic_string_view<charT, traits> lhs, basic_string_view<charT, traits> rhs) noexcept;
2
#
Returns: lhs.compare(rhs) == 0.
template<class charT, class traits> constexpr bool operator!=(basic_string_view<charT, traits> lhs, basic_string_view<charT, traits> rhs) noexcept;
3
#
Returns: lhs.compare(rhs) != 0.
template<class charT, class traits> constexpr bool operator< (basic_string_view<charT, traits> lhs, basic_string_view<charT, traits> rhs) noexcept;
4
#
Returns: lhs.compare(rhs) < 0.
template<class charT, class traits> constexpr bool operator> (basic_string_view<charT, traits> lhs, basic_string_view<charT, traits> rhs) noexcept;
5
#
Returns: lhs.compare(rhs) > 0.
template<class charT, class traits> constexpr bool operator<=(basic_string_view<charT, traits> lhs, basic_string_view<charT, traits> rhs) noexcept;
6
#
Returns: lhs.compare(rhs) <= 0.
template<class charT, class traits> constexpr bool operator>=(basic_string_view<charT, traits> lhs, basic_string_view<charT, traits> rhs) noexcept;
7
#
Returns: lhs.compare(rhs) >= 0.

24.4.4 Inserters and extractors [string.view.io]

template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, basic_string_view<charT, traits> str);
1
#
Effects: Behaves as a formatted output function ([ostream.formatted.reqmts]) of os.
Forms a character sequence seq, initially consisting of the elements defined by the range [str.begin(), str.end()).
Determines padding for seq as described in [ostream.formatted.reqmts].
Then inserts seq as if by calling os.rdbuf()->sputn(​seq, n), where n is the larger of os.width() and str.size(); then calls os.​width(0).
2
#
Returns: os

24.4.5 Hash support [string.view.hash]

template<> struct hash<string_view>; template<> struct hash<u16string_view>; template<> struct hash<u32string_view>; template<> struct hash<wstring_view>;
1
#
The specialization is enabled ([unord.hash]).
[ Note
:
The hash value of a string view object is equal to the hash value of the corresponding string object ([basic.string.hash]).
— end note
 ]

24.4.6 Suffix for basic_­string_­view literals [string.view.literals]

constexpr string_view operator""sv(const char* str, size_t len) noexcept;
1
#
Returns: string_­view{str, len}.
constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;
2
#
Returns: u16string_­view{str, len}.
constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;
3
#
Returns: u32string_­view{str, len}.
constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;
4
#
Returns: wstring_­view{str, len}.