21 Strings library [strings]

21.4 String view classes [string.view]

21.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                = charT*;
  using const_pointer          = const charT*;
  using reference              = charT&;
  using const_reference        = const charT&;
  using const_iterator         = implementation-defined; // see [string.view.iterators]
  using iterator               = const_iterator;229
  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.

229)

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

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 [tab:string.view.ctr.2].

Table 64 — basic_string_view(const charT*) effects
ElementValue
data_ str
size_ traits::length(str)
5

Complexity: Ο(traits::length(str)).

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 [tab:string.view.ctr.3].

Table 65 — basic_string_view(const charT*, size_type) effects
ElementValue
data_ str
size_ len

21.4.2.2 Iterator support [string.view.iterators]

using const_iterator = implementation-defined;

1

A constant random-access iterator type such that, for a const_iterator it, if &*(it + N) is valid, then &*(it + N) == (&*it) + N.

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()).

21.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.

21.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 routine 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

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.

21.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: Ο(rlen).

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: Ο(rlen).

14

Returns: The nonzero result if the result of the comparison is nonzero. Otherwise, returns a value as indicated in Table [tab:string.view.compare].

Table 66 — compare() results
ConditionReturn 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));

21.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 Ο(size() * str.size()) 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.

9

Remarks: Uses traits::eq().

constexpr size_type rfind(basic_string_view str, size_type pos = npos) const noexcept;

10

Let xpos be the highest position, if possible, such that the following conditions hold:

  • (10.1)

    xpos <= pos

  • (10.2)

    xpos + str.size() <= size()

  • (10.3)

    traits::eq(at(xpos + I), str.at(I)) for all elements I of the string referenced by str.

11

Effects: Determines xpos.

12

Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.

13

Remarks: Uses traits::eq().

constexpr size_type find_first_of(basic_string_view str, size_type pos = 0) const noexcept;

14

Let xpos be the lowest position, if possible, such that the following conditions hold:

  • (14.1)

    pos <= xpos

  • (14.2)

    xpos < size()

  • (14.3)

    traits::eq(at(xpos), str.at(I)) for some element I of the string referenced by str.

15

Effects: Determines xpos.

16

Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.

17

Remarks: Uses traits::eq().

constexpr size_type find_last_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 some 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.

21

Remarks: Uses traits::eq().

constexpr size_type find_first_not_of(basic_string_view str, size_type pos = 0) const noexcept;

22

Let xpos be the lowest position, if possible, such that the following conditions hold:

  • (22.1)

    pos <= xpos

  • (22.2)

    xpos < size()

  • (22.3)

    traits::eq(at(xpos), str.at(I)) for no element I of the string referenced by str.

23

Effects: Determines xpos.

24

Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.

25

Remarks: Uses traits::eq().

constexpr size_type find_last_not_of(basic_string_view str, size_type pos = npos) const noexcept;

26

Let xpos the highest position, if possible, such that the following conditions hold:

  • (26.1)

    xpos <= pos

  • (26.2)

    xpos < size()

  • (26.3)

    traits::eq(at(xpos), str.at(I)) for no element I of the string referenced by str.

27

Effects: Determines xpos.

28

Returns: xpos if the function can determine such a value for xpos. Otherwise, returns npos.

29

Remarks: Uses traits::eq().