# std::basic_string

From cppreference.com
< cpp‎ | string

Defined in header `<string>` |  |
template< class CharT, class Traits = std::char_traits<CharT>, class Allocator = std::allocator<CharT> > class basic_string; | (1) |
namespace pmr { template <class CharT, class Traits = std::char_traits<CharT>> using basic_string = std::basic_string< CharT, Traits, std::polymorphic_allocator<CharT>> } | (2) | (since C++17)

The class template `basic_string` stores and manipulates sequences of `char`-like objects, which are non-array objects of trivial standard-layout type. 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. `Traits::char_type` and `CharT` must name the same type; otherwise the program is ill-formed.

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())`, or, equivalently, a pointer to `s[0]` can be passed to functions that expect a pointer to the first element of a `CharT[]` array. | (since C++11)

`std::basic_string` satisfies the requirements of AllocatorAwareContainer, SequenceContainer and ContiguousContainer (since C++17)

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>

### Template parameters

CharT | - | character type
Traits | - | traits class specifying the operations on the character type
Allocator | - | Allocator type used to allocate internal storage

### Member types

Member type | Definition
`traits_type` | `Traits`
`value_type` | `CharT`
`allocator_type` | `Allocator`

`size_type`

`Allocator::size_type` | (until C++11)
std::allocator_traits<Allocator>::size_type | (since C++11)

`difference_type`

`Allocator::difference_type` | (until C++11)
std::allocator_traits<Allocator>::difference_type | (since C++11)

`reference`

`Allocator::reference` | (until C++11)
`value_type&` | (since C++11)

`const_reference`

`Allocator::const_reference` | (until C++11)
`const value_type&` | (since C++11)

`pointer`

`Allocator::pointer` | (until C++11)
std::allocator_traits<Allocator>::pointer | (since C++11)

`const_pointer`

`Allocator::const_pointer` | (until C++11)
std::allocator_traits<Allocator>::const_pointer | (since C++11)

`iterator` | LegacyRandomAccessIterator
`const_iterator` | Constant LegacyRandomAccessIterator
`reverse_iterator` | std::reverse_iterator<iterator>
`const_reverse_iterator` | std::reverse_iterator<const_iterator>

### Member functions

(constructor) | constructs a `basic_string` (public member function)
(destructor) | destroys the string, deallocating internal storage if used (public member function)
operator= | assigns values to the string (public member function)
assign | assign characters to a string (public member function)
get_allocator | returns the associated allocator (public member function)

##### Element access

at | accesses the specified character with bounds checking (public member function)
operator[] | accesses the specified character (public member function)
front (C++11) | accesses the first character (public member function)
back (C++11) | accesses the last character (public member function)
data | returns a pointer to the first character of a string (public member function)
c_str | returns a non-modifiable standard C character array version of the string (public member function)
operator basic_string_view (C++17) | returns a non-modifiable string_view into the entire string (public member function)

##### Iterators

begin cbegin (C++11) | returns an iterator to the beginning (public member function)
end cend (C++11) | returns an iterator to the end (public member function)
rbegin crbegin (C++11) | returns a reverse iterator to the beginning (public member function)
rend crend (C++11) | returns a reverse iterator to the end (public member function)

##### Capacity

empty | checks whether the string is empty (public member function)
size length | returns the number of characters (public member function)
max_size | returns the maximum number of characters (public member function)
reserve | reserves storage (public member function)
capacity | returns the number of characters that can be held in currently allocated storage (public member function)
shrink_to_fit (C++11) | reduces memory usage by freeing unused memory (public member function)

##### Operations

clear | clears the contents (public member function)
insert | inserts characters (public member function)
erase | removes characters (public member function)
push_back | appends a character to the end (public member function)
pop_back (C++11) | removes the last character (public member function)
append | appends characters to the end (public member function)
operator+= | appends characters to the end (public member function)
compare | compares two strings (public member function)
starts_with (C++20) | checks if the string starts with the given prefix (public member function)
ends_with (C++20) | checks if the string ends with the given suffix (public member function)
replace | replaces specified portion of a string (public member function)
substr | returns a substring (public member function)
copy | copies characters (public member function)
resize | changes the number of characters stored (public member function)
swap | swaps the contents (public member function)

##### Search

find | find characters in the string (public member function)
rfind | find the last occurrence of a substring (public member function)
find_first_of | find first occurrence of characters (public member function)
find_first_not_of | find first absence of characters (public member function)
find_last_of | find last occurrence of characters (public member function)
find_last_not_of | find last absence of characters (public member function)

### Constants

npos [static] | special value. The exact meaning depends on the context (public static member constant)

### Non-member functions

operator+ | concatenates two strings or a string and a char (function template)
operator==operator!=operator<operator>operator<=operator>= | lexicographically compares two strings (function template)
std::swap(std::basic_string) | specializes the std::swap algorithm (function template)
erase(std::basic_string)erase_if(std::basic_string) (C++20) | Erases all elements satisfying specific criteria (function template)

##### Input/output

operator<<operator>> | performs stream input and output on strings (function template)
getline | read data from an I/O stream into a string (function template)

##### Numeric conversions

stoi stol stoll (C++11)(C++11)(C++11) | converts a string to a signed integer (function)
stoul stoull (C++11)(C++11) | converts a string to an unsigned integer (function)
stof stod stold (C++11)(C++11)(C++11) | converts a string to a floating point value (function)
to_string (C++11) | converts an integral or floating point value to `string` (function)
to_wstring (C++11) | converts an integral or floating point value to `wstring` (function)

### Literals

Defined in inline namespace `std::literals::string_literals`
operator""s (C++14) | Converts a character array literal to `basic_string` (function)

### Helper classes

std::hash<std::string>std::hash<std::u8string>std::hash<std::u16string>std::hash<std::u32string>std::hash<std::wstring>std::hash<std::pmr::string>std::hash<std::pmr::u8string>std::hash<std::pmr::u16string>std::hash<std::pmr::u32string>std::hash<std::pmr::wstring> (C++11)(C++20)(C++11)(C++11)(C++11)(C++20)(C++20)(C++20)(C++20)(C++20) | hash support for strings (class template specialization)

### Deduction guides(since C++17)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string&oldid=109845"