# 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::pmr::polymorphic_allocator<CharT>>; } | (2) | (since C++17)

The class template `basic_string` stores and manipulates sequences of character-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()`)`, 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).

Member functions of `std::basic_string` are constexpr: it is possible to create and use `std::string` objects in the evaluation of a constant expression. However, `std::string` objects generally cannot be constexpr, because any dynamically allocated storage must be released in the same evaluation of constant expression. | (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>

### 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` | `value_type&`
`const_reference` | const value_type&
`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 and LegacyContiguousIterator to `value_type` | (until C++20)
LegacyRandomAccessIterator, `contiguous_iterator`, and ConstexprIterator to `value_type` | (since C++20)
`const_iterator` |
LegacyRandomAccessIterator and LegacyContiguousIterator to const value_type | (until C++20)
LegacyRandomAccessIterator, `contiguous_iterator`, and ConstexprIterator to const value_type | (since C++20)
`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)
assign_range (C++23) | assign a range of 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 (DR*) | accesses the first character (public member function)
back (DR*) | 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 (DR*) | returns an iterator to the beginning (public member function)
end cend (DR*) | returns an iterator to the end (public member function)
rbegin crbegin (DR*) | returns a reverse iterator to the beginning (public member function)
rend crend (DR*) | 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 (DR*) | reduces memory usage by freeing unused memory (public member function)
##### Operations
clear | clears the contents (public member function)
insert | inserts characters (public member function)
insert_range (C++23) | inserts a range of characters (public member function)
erase | removes characters (public member function)
push_back | appends a character to the end (public member function)
pop_back (DR*) | removes the last character (public member function)
append | appends characters to the end (public member function)
append_range (C++23) | appends a range of 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)
contains (C++23) | checks if the string contains the given substring or character (public member function)
replace | replaces specified portion of a string (public member function)
replace_with_range (C++23) | replaces specified portion of a string with a range of characters (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)
resize_and_overwrite (C++23) | changes the number of characters stored and possibly overwrites indeterminate contents via user-provided operation (public member function)
swap | swaps the contents (public member function)
##### Search
find | finds the first occurrence of the given substring (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>=operator<=> (removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) | 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++17)(C++20)(C++17)(C++17)(C++17) | hash support for strings (class template specialization)

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

### Notes

Although it is required that customized `construct` or `destroy` is used when constructing or destroying elements of `std::basic_string` until C++23, all implementations only used the default mechanism. The requirement is corrected by P1072R10 to match existing practice.

Feature-test macro | Value | Std | Comment
--- | --- | --- | ---
`__cpp_lib_string_udls` | 201304L | (C++14) | User-defined literals for string types
`__cpp_lib_string_contains` | 202011L | (C++23) | `contains`
`__cpp_lib_string_resize_and_overwrite` | 202110L | (C++23) | `resize_and_overwrite`
`__cpp_lib_containers_ranges` | 202202L | (C++23) | Member functions for construction, insertion, and replacement that accept container compatible range

### Example

Run this code

    #include <iostream>
    #include <string>

    int main()
    {
        using namespace std::literals;

        // Creating a string from const char*
        std::string str1 = "hello";

        // Creating a string using string literal
        auto str2 = "world"s;

        // Concatenating strings
        std::string str3 = str1 + " " + str2;

        // Print out the result
        std::cout << str3 << '\n';

        std::string::size_type pos = str3.find(" ");
        str1 = str3.substr(pos + 1); // the part after the space
        str2 = str3.substr(0, pos);  // the part till the space

        std::cout << str1 << ' ' << str2 << '\n';

        // Accessing an element using subscript operator[]
        std::cout << str1[0] << '\n';
        str1[0] = 'W';
        std::cout << str1 << '\n';
    }

Output:

    hello world
    world hello
    w
    World

### 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 530 | C++98 | contiguity of the storage for elements of `basic_string` was not required | required

### See also

basic_string_view (C++17) | read-only string view (class template)

### External links

C++ string handling

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