std::basic_string_view - cppreference.com (original) (raw)
The class template basic_string_view describes an object that can refer to a constant contiguous sequence of CharT with the first element of the sequence at position zero.
For a basic_string_view str, pointers, iterators, and references to elements of str are invalidated when an operation invalidates a pointer in the range [str.data(), str.data() + str.size()).
| Every specialization of std::basic_string_view is a TriviallyCopyable type. | (since C++23) |
|---|
Several typedefs for common character types are provided:
| Defined in header <string_view> | |
|---|---|
| Type | Definition |
| std::string_view (C++17) | std::basic_string_view<char> |
| std::wstring_view (C++17) | std::basic_string_view<wchar_t> |
| std::u8string_view (C++20) | std::basic_string_view<char8_t> |
| std::u16string_view (C++17) | std::basic_string_view<char16_t> |
| std::u32string_view (C++17) | std::basic_string_view<char32_t> |
Contents
- 1 Template parameters
- 2 Nested types
- 3 Data members
- 4 Member functions
- 5 Constants
- 6 Non-member functions
- 7 Literals
- 8 Helper classes
- 9 Helper templates
- 10 Deduction guides
- 11 Notes
- 12 Example
- 13 Defect reports
- 14 See also
[edit] Template parameters
| CharT | - | character type |
|---|---|---|
| Traits | - | CharTraits class specifying the operations on the character type. Like for std::basic_string, Traits::char_type must name the same type as CharT or the program is ill-formed. |
[edit] Nested types
| Type | Definition |
|---|---|
| traits_type | Traits |
| value_type | CharT |
| pointer | CharT* |
| const_pointer | const CharT* |
| reference | CharT& |
| const_reference | const CharT& |
| const_iterator | implementation-defined constant LegacyRandomAccessIterator,whose value_type is CharT |
| iterator | const_iterator |
| const_reverse_iterator | std::reverse_iterator<const_iterator> |
| reverse_iterator | const_reverse_iterator |
| size_type | std::size_t |
| difference_type | std::ptrdiff_t |
Note: iterator and const_iterator are the same type because string views are views into constant character sequences.
All requirements on the iterator types of a Container applies to the iterator and const_iterator types of basic_string_view as well.
[edit] Data members
| Member | Description |
|---|---|
| const_pointer data_ | a pointer to the underlying sequence(exposition-only member object*) |
| size_type size_ | the number of characters(exposition-only member object*) |
[edit] Member functions
| Constructors and assignment | |
|---|---|
| (constructor) | constructs a basic_string_view (public member function) [edit] |
| operator= | assigns a view (public member function) [edit] |
| Iterators | |
| begincbegin | returns an iterator to the beginning (public member function) [edit] |
| endcend | returns an iterator to the end (public member function) [edit] |
| rbegincrbegin | returns a reverse iterator to the beginning (public member function) [edit] |
| rendcrend | returns a reverse iterator to the end (public member function) [edit] |
| Element access | |
| operator[] | accesses the specified character (public member function) [edit] |
| at | accesses the specified character with bounds checking (public member function) [edit] |
| front | accesses the first character (public member function) [edit] |
| back | accesses the last character (public member function) [edit] |
| data | returns a pointer to the first character of a view (public member function) [edit] |
| Capacity | |
| sizelength | returns the number of characters (public member function) [edit] |
| max_size | returns the maximum number of characters (public member function) [edit] |
| empty | checks whether the view is empty (public member function) [edit] |
| Modifiers | |
| remove_prefix | shrinks the view by moving its start forward (public member function) [edit] |
| remove_suffix | shrinks the view by moving its end backward (public member function) [edit] |
| swap | swaps the contents (public member function) [edit] |
| Operations | |
| copy | copies characters (public member function) [edit] |
| substr | returns a substring (public member function) [edit] |
| compare | compares two views (public member function) [edit] |
| starts_with(C++20) | checks if the string view starts with the given prefix (public member function) [edit] |
| ends_with(C++20) | checks if the string view ends with the given suffix (public member function) [edit] |
| contains(C++23) | checks if the string view contains the given substring or character (public member function) [edit] |
| find | find characters in the view (public member function) [edit] |
| rfind | find the last occurrence of a substring (public member function) [edit] |
| find_first_of | find first occurrence of characters (public member function) [edit] |
| find_last_of | find last occurrence of characters (public member function) [edit] |
| find_first_not_of | find first absence of characters (public member function) [edit] |
| find_last_not_of | find last absence of characters (public member function) [edit] |
| Constants | |
| npos[static] | special value. The exact meaning depends on the context (public static member constant) [edit] |
[edit] Non-member functions
[edit] Literals
[edit] Helper classes
[edit] Helper templates
| template< class CharT, class Traits > inline constexpr bool ranges::enable_borrowed_range<std::basic_string_view<CharT, Traits>> = true; | | (since C++20) | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------- |
This specialization of ranges::enable_borrowed_range makes basic_string_view satisfy borrowed_range.
| template< class CharT, class Traits > inline constexpr bool ranges::enable_view<std::basic_string_view<CharT, Traits>> = true; | | (since C++20) | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ------------- |
This specialization of ranges::enable_view makes basic_string_view satisfy view.
[edit] Notes
It is the programmer's responsibility to ensure that std::string_view does not outlive the pointed-to character array:
std::string_view good{"a string literal"};
// "Good" case: good points to a static array.
// String literals reside in persistent data storage.
std::string_view bad{"a temporary string"s};
// "Bad" case: bad holds a dangling pointer since the std::string temporary,
// created by std::operator""s, will be destroyed at the end of the statement.
Specializations of std::basic_string_view are already trivially copyable types in all existing implementations, even before the formal requirement introduced in C++23.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
| __cpp_lib_string_view | 201606L | (C++17) | std::string_view |
| 201803L | (C++20) | ConstexprIterator | |
| __cpp_lib_string_contains | 202011L | (C++23) | contains |
[edit] Example
#include #include int main() { #define A "▀" #define B "▄" #define C "─" constexpr std::string_view blocks[]{A B C, B A C, A C B, B C A}; for (int y{}, p{}; y != 8; ++y, p = ((p + 1) % 4)) { for (char x{}; x != 29; ++x) std::cout << blocks[p]; std::cout << '\n'; } }
Output:
▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ ▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄ ▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀ ▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─ ▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─ ▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄▀─▄ ▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀▄─▀
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 3203 | C++17 | only pointers, iterators, and referencesreturned from the member functions ofbasic_string_view might be invalidated | all pointers, iterators, and referencesto elements of basic_string_viewmay be invalidated |