# 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. 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 behavior is undefined.

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::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::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` | `RandomAccessIterator`
`const_iterator` | Constant random access iterator
`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 | access specified character with bounds checking (public member function)
operator[] | access 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)
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)

##### 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::u16string>std::hash<std::u32string>std::hash<std::wstring> (C++11)(C++11)(C++11)(C++11) | hash support for strings (class template specialization)

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string&oldid=91875"
Hidden category:

- Pages with unreviewed LWG DR marker