Files
2025-10-25 03:02:53 +03:00

48 KiB
Raw Permalink Blame History

[string.view]

27 Strings library [strings]

27.3 String view classes [string.view]

27.3.1 General [string.view.general]

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 [string.view], the type of the char-like objects held in a basic_string_view object is designated by charT.

2

#

[Note 1:

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 as a non-templated parameter wherever a sequence of characters is expected.

User-defined types can define their own implicit conversions to std::basic_string_view in order to interoperate with these functions.

— end note]

27.3.2 Header <string_view> synopsis [string.view.synop]

🔗

// mostly freestanding#include // see [compare.syn]namespace std {// [string.view.template], class template basic_string_viewtemplate<class charT, class traits = char_traits>class basic_string_view; // partially freestandingtemplate<class charT, class traits>constexpr bool ranges::enable_view<basic_string_view<charT, traits>> = true; template<class charT, class traits>constexpr bool ranges::enable_borrowed_range<basic_string_view<charT, traits>> = true; // [string.view.comparison], non-member comparison functionstemplate<class charT, class traits>constexpr bool operator==(basic_string_view<charT, traits> x, type_identity_t<basic_string_view<charT, traits>> y) noexcept; template<class charT, class traits>constexpr see below operator<=>(basic_string_view<charT, traits> x, type_identity_t<basic_string_view<charT, traits>> y) noexcept; // [string.view.io], inserters and extractorstemplate<class charT, class traits> basic_ostream<charT, traits>&operator<<(basic_ostream<charT, traits>& os, basic_string_view<charT, traits> str); // hosted// basic_string_view typedef-namesusing string_view = basic_string_view; using u8string_view = basic_string_view<char8_t>; 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 supporttemplate struct hash; template<> struct hash<string_view>; template<> struct hash<u8string_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 literalsconstexpr string_view operator""sv(const char* str, size_t len) noexcept; constexpr u8string_view operator""sv(const char8_t* 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.

27.3.3 Class template basic_string_view [string.view.template]

27.3.3.1 General [string.view.template.general]

🔗

namespace std {template<class charT, class traits = char_traits>class basic_string_view {public:// typesusing 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;211using 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 assignmentconstexpr 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); templateconstexpr explicit basic_string_view(R&& r); // [string.view.iterators], iterator supportconstexpr 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], capacityconstexpr 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 accessconstexpr const_reference operator[](size_type pos) const; constexpr const_reference at(size_type pos) const; // freestanding-deletedconstexpr const_reference front() const; constexpr const_reference back() const; constexpr const_pointer data() const noexcept; // [string.view.modifiers], modifiersconstexpr 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 operationsconstexpr size_type copy(charT* s, size_type n, size_type pos = 0) const; // freestanding-deletedconstexpr basic_string_view substr(size_type pos = 0, size_type n = npos) const; // freestanding-deletedconstexpr basic_string_view subview(size_type pos = 0, size_type n = npos) const; // freestanding-deletedconstexpr int compare(basic_string_view s) const noexcept; constexpr int compare(size_type pos1, size_type n1, basic_string_view s) const; // freestanding-deletedconstexpr int compare(size_type pos1, size_type n1, basic_string_view s, size_type pos2, size_type n2) const; // freestanding-deletedconstexpr int compare(const charT* s) const; constexpr int compare(size_type pos1, size_type n1, const charT* s) const; // freestanding-deletedconstexpr int compare(size_type pos1, size_type n1, const charT* s, size_type n2) const; // freestanding-deletedconstexpr 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], searchingconstexpr 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 guidestemplate<class It, class End> basic_string_view(It, End) -> basic_string_view<iter_value_t>; template basic_string_view(R&&) -> basic_string_view<ranges::range_value_t>;}

1

#

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]

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 to elements of str.

3

#

The complexity of basic_string_view member functions is O(1) unless otherwise specified.

4

#

basic_string_view<charT, traits> is a trivially copyable type ([basic.types.general]).

211)211)

Because basic_string_view refers to a constant sequence, iterator and const_iterator are the same type.

27.3.3.2 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: O(traits::length(str)).

🔗

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:

8

#

Preconditions:

9

#

Effects: Initializes data_ with to_address(begin) and initializes size_ with end - begin.

10

#

Throws: When and what end - begin throws.

🔗

template<class R> constexpr explicit basic_string_view(R&& r);

11

#

Let d be an lvalue of type remove_cvref_t.

12

#

Constraints:

remove_cvref_t is not the same type as basic_string_view,

R modelsranges::contiguous_range and ranges::sized_range,

is_same_v<ranges::range_value_t, 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.

13

#

Effects: Initializes data_ with ranges::data(r) andsize_ with ranges::size(r).

14

#

Throws: Any exception thrown by ranges::data(r) and ranges::size(r).

27.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>>;

1

#

Constraints:

🔗

template<class R> basic_string_view(R&&) -> basic_string_view<ranges::range_value_t<R>>;

2

#

Constraints: R satisfies ranges::contiguous_range.

27.3.3.4 Iterator support [string.view.iterators]

🔗

using const_iterator = implementation-defined;

1

#

A type that meets the requirements of a constantCpp17RandomAccessIterator ([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

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;

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

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

🔗

constexpr bool empty() const noexcept;

3

#

Returns: size_ == 0.

27.3.3.6 Element access [string.view.access]

🔗

constexpr const_reference operator[](size_type pos) const;

1

#

Hardened preconditions: pos < size() is true.

[Note 1:

This precondition is stronger than the one on basic_string::operator[].

— end note]

2

#

Returns: data_[pos].

3

#

Throws: Nothing.

🔗

constexpr const_reference at(size_type pos) const;

4

#

Returns: data_[pos].

5

#

Throws: out_of_range if pos >= size().

🔗

constexpr const_reference front() const;

6

#

Hardened preconditions: empty() is false.

7

#

Returns: data_[0].

8

#

Throws: Nothing.

🔗

constexpr const_reference back() const;

9

#

Hardened preconditions: empty() is false.

10

#

Returns: data_[size() - 1].

11

#

Throws: Nothing.

🔗

constexpr const_pointer data() const noexcept;

12

#

Returns: data_.

13

#

[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]

27.3.3.7 Modifiers [string.view.modifiers]

🔗

constexpr void remove_prefix(size_type n);

1

#

Hardened preconditions: n <= size() is true.

2

#

Effects: Equivalent to: data_ += n; size_ -= n;

🔗

constexpr void remove_suffix(size_type n);

3

#

Hardened preconditions: n <= size() is true.

4

#

Effects: Equivalent to: size_ -= n;

🔗

constexpr void swap(basic_string_view& s) noexcept;

5

#

Effects: Exchanges the values of *this and s.

27.3.3.8 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

#

Preconditions: [s, s + rlen) is a valid range.

3

#

Effects: Equivalent to traits::copy(s, data() + pos, rlen).

4

#

Returns: rlen.

5

#

Throws: out_of_range if pos > size().

6

#

Complexity: O(rlen).

🔗

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

7

#

Let rlen be the smaller of n and size() - pos.

8

#

Effects: Determines rlen, the effective length of the string to reference.

9

#

Returns: basic_string_view(data() + pos, rlen).

10

#

Throws: out_of_range if pos > size().

🔗

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

#

Returns: The nonzero result if the result of the comparison is nonzero.

Otherwise, returns a value as indicated in Table 88.

Table 88 — compare() results [tab:string.view.compare]

🔗
Condition
Return Value
🔗
size() < str.size()
< 0
🔗
size() == str.size()
0
🔗
size() > str.size()
> 0

14

#

Complexity: O(rlen).

🔗

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

#

Let rlen be the smaller of size() and x.size().

21

#

Effects: Equivalent to: return basic_string_view(data(), rlen) == x;

🔗

constexpr bool starts_with(charT x) const noexcept;

22

#

Effects: Equivalent to: return !empty() && traits::eq(front(), x);

🔗

constexpr bool starts_with(const charT* x) const;

23

#

Effects: Equivalent to: return starts_with(basic_string_view(x));

🔗

constexpr bool ends_with(basic_string_view x) const noexcept;

24

#

Let rlen be the smaller of size() and x.size().

25

#

Effects: Equivalent to:return basic_string_view(data() + (size() - rlen), rlen) == x;

🔗

constexpr bool ends_with(charT x) const noexcept;

26

#

Effects: Equivalent to: return !empty() && traits::eq(back(), x);

🔗

constexpr bool ends_with(const charT* x) const;

27

#

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;

28

#

Effects: Equivalent to: return find(x) != npos;

27.3.3.9 Searching [string.view.find]

1

#

Member functions in this subclause have complexity O(size() * str.size()) at worst, although implementations should do better.

2

#

Let F be one offind,rfind,find_first_of,find_last_of,find_first_not_of, andfind_last_not_of.

Each member function of the formconstexpr 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 formconstexpr 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 formconstexpr 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:

pos <= xpos

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

traits::eq(data_[xpos + I], str[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:

xpos <= pos

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

traits::eq(data_[xpos + I], str[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:

pos <= xpos

xpos < size()

traits::eq(data_[xpos], str[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:

xpos <= pos

xpos < size()

traits::eq(data_[xpos], str[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:

pos <= xpos

xpos < size()

traits::eq(data_[xpos], str[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:

xpos <= pos

xpos < size()

traits::eq(data_[xpos], str[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.

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

🔗

template<class charT, class traits> constexpr bool operator==(basic_string_view<charT, traits> lhs, type_identity_t<basic_string_view<charT, traits>> rhs) noexcept;

1

#

Returns: lhs.compare(rhs) == 0.

🔗

template<class charT, class traits> constexpr see below operator<=>(basic_string_view<charT, traits> lhs, type_identity_t<basic_string_view<charT, traits>> rhs) noexcept;

2

#

Let R denote the type traits::comparison_category if that qualified-id is valid and denotes a type ([temp.deduct]), otherwise R is weak_ordering.

3

#

Mandates: R denotes a comparison category type ([cmp.categories]).

4

#

Returns: static_cast(lhs.compare(rhs) <=> 0).

5

#

[Note 1:

The usage of type_identity_t as parameter ensures that an object of type basic_string_view<charT, traits> can always be compared with an object of a type T with an implicit conversion to basic_string_view<charT, traits>, and vice versa, as per [over.match.oper].

— end note]

27.3.5 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 sequenceseq, 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 callingos.rdbuf()->sputn(seq, n), where n is the larger of os.width() and str.size(); then calls os.width(0).

2

#

Returns: os.

27.3.6 Hash support [string.view.hash]

🔗

template<> struct hash<string_view>; template<> struct hash<u8string_view>; template<> struct hash<u16string_view>; template<> struct hash<u32string_view>; template<> struct hash<wstring_view>;

1

#

The specialization is enabled ([unord.hash]).

[Note 1:

The hash value of a string view object is equal to the hash value of the corresponding string object ([basic.string.hash]).

— end note]

27.3.7 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 u8string_view operator""sv(const char8_t* str, size_t len) noexcept;

2

#

Returns: u8string_view{str, len}.

🔗

constexpr u16string_view operator""sv(const char16_t* str, size_t len) noexcept;

3

#

Returns: u16string_view{str, len}.

🔗

constexpr u32string_view operator""sv(const char32_t* str, size_t len) noexcept;

4

#

Returns: u32string_view{str, len}.

🔗

constexpr wstring_view operator""sv(const wchar_t* str, size_t len) noexcept;

5

#

Returns: wstring_view{str, len}.