std::basic_string
| Defined in header <string>
|
||
| template< class CharT, |
(1) | |
| namespace pmr { template< |
(2) | (since C++17) |
The class template basic_string stores and manipulates sequences of character-like objects, which are non-array objects of TrivialType and StandardLayoutType. The class is dependent neither on the character type nor on the nature of operations on that type. The definitions of the operations are supplied via the Traits template parameter - a specialization of std::char_traits or a compatible traits class.
The elements of a basic_string are stored contiguously, that is, for a basic_string s, &*(s.begin() + n) == &*s.begin() + n for any n in [0, s.size()), and *(s.begin() + s.size()) has value CharT() (a null terminator)(since C++11); or, equivalently, a pointer to s[0] can be passed to functions that expect a pointer to the first element of an array(until C++11)a null-terminated array(since C++11) of CharT.
std::basic_string satisfies the requirements of AllocatorAwareContainer (except that customized construct/destroy are not used for construction/destruction of elements), SequenceContainer and ContiguousContainer(since C++17).
If any of Traits::char_type and Allocator::value_type is different from CharT, the program is ill-formed.
All member functions of std::basic_string are constexpr: it is possible to create and use std::basic_string objects in the evaluation of a constant expression.However, |
(since C++20) |
Several typedefs for common character types are provided:
| Defined in header
<string> | |
| Type | Definition |
std::string
|
std::basic_string<char> |
std::wstring
|
std::basic_string<wchar_t> |
std::u8string (C++20)
|
std::basic_string<char8_t> |
std::u16string (C++11)
|
std::basic_string<char16_t> |
std::u32string (C++11)
|
std::basic_string<char32_t> |
std::pmr::string (C++17)
|
std::pmr::basic_string<char> |
std::pmr::wstring (C++17)
|
std::pmr::basic_string<wchar_t> |
std::pmr::u8string (C++20)
|
std::pmr::basic_string<char8_t> |
std::pmr::u16string (C++17)
|
std::pmr::basic_string<char16_t> |
std::pmr::u32string (C++17)
|
std::pmr::basic_string<char32_t> |
Contents |
[edit] Template parameters
| CharT | - | character type |
| Traits | - | traits class specifying the operations on the character type |
| Allocator | - | Allocator type used to allocate internal storage |
[edit] Nested types
| Type | Definition | ||||
traits_type
|
Traits
| ||||
value_type
|
CharT
| ||||
allocator_type
|
Allocator
| ||||
size_type
|
| ||||
difference_type
|
| ||||
reference
|
value_type& | ||||
const_reference
|
const value_type& | ||||
pointer
|
| ||||
const_pointer
|
| ||||
iterator
|
| ||||
const_iterator
|
| ||||
reverse_iterator
|
std::reverse_iterator<iterator> | ||||
const_reverse_iterator
|
std::reverse_iterator<const_iterator> |
[edit] Data members
constexpr size_type npos [static]
|
the special value size_type(-1), its exact meaning depends on the context |
[edit] Member functions
constructs a basic_string (public member function) | |
| destroys the string, deallocating internal storage if used (public member function) | |
| assigns values to the string (public member function) | |
| assign characters to a string (public member function) | |
| (C++23) |
assign a range of characters to a string (public member function) |
| returns the associated allocator (public member function) | |
Element access | |
| accesses the specified character with bounds checking (public member function) | |
| accesses the specified character (public member function) | |
| (DR*) |
accesses the first character (public member function) |
| (DR*) |
accesses the last character (public member function) |
| returns a pointer to the first character of a string (public member function) | |
| returns a non-modifiable standard C character array version of the string (public member function) | |
| (C++17) |
returns a non-modifiable basic_string_view into the entire string (public member function) |
Iterators | |
| (C++11) |
returns an iterator to the beginning (public member function) |
| (C++11) |
returns an iterator to the end (public member function) |
| (C++11) |
returns a reverse iterator to the beginning (public member function) |
| (C++11) |
returns a reverse iterator to the end (public member function) |
Capacity | |
| checks whether the string is empty (public member function) | |
| returns the number of characters (public member function) | |
| returns the maximum number of characters (public member function) | |
| reserves storage (public member function) | |
| returns the number of characters that can be held in currently allocated storage (public member function) | |
| (DR*) |
reduces memory usage by freeing unused memory (public member function) |
Modifiers | |
| clears the contents (public member function) | |
| inserts characters (public member function) | |
| (C++23) |
inserts a range of characters (public member function) |
| removes characters (public member function) | |
| appends a character to the end (public member function) | |
| (DR*) |
removes the last character (public member function) |
| appends characters to the end (public member function) | |
| (C++23) |
appends a range of characters to the end (public member function) |
| appends characters to the end (public member function) | |
| replaces specified portion of a string (public member function) | |
| (C++23) |
replaces specified portion of a string with a range of characters (public member function) |
| copies characters (public member function) | |
| changes the number of characters stored (public member function) | |
| (C++23) |
changes the number of characters stored and possibly overwrites indeterminate contents via user-provided operation (public member function) |
| swaps the contents (public member function) | |
Search | |
| finds the first occurrence of the given substring (public member function) | |
| find the last occurrence of a substring (public member function) | |