std::basic_string

The class template std::basic_string stores and manipulates sequences of character-like objects, which are non-array objects of TrivialType and StandardLayoutType. Character operations are supplied by the Traits parameter, typically a specialization of std::char_traits.

std::basic_string owns its storage, manages dynamic capacity, and provides a contiguous character sequence suitable for text processing, interoperation with C APIs, and general-purpose string algorithms.

From C++20, member functions of std::basic_string are broadly constexpr, although a std::string object usually cannot persist dynamic storage across constant-evaluation boundaries.

# Declarations

template<
class CharT,
class Traits = std::char_traits<CharT>,
class Allocator = std::allocator<CharT>
> class basic_string;

namespace pmr {
template<
class CharT,
class Traits = std::char_traits<CharT>
> using basic_string =
std::basic_string<CharT, Traits, std::pmr::polymorphic_allocator<CharT>>;
}

(since C++17)

# Common aliases

# Template parameters

• CharT: character type
• Traits: traits class that defines comparison, assignment, and other character operations
• Allocator: Allocator type used for internal storage

# Nested types

# Data members

• npos: special size_type(-1) sentinel used by search and substring operations

# Semantics

• A basic_string owns a contiguous sequence of characters.
• The stored sequence is suitable for C interop through c_str() and data(), with the usual null-termination guarantees for string access.
• Growth, replacement, and insertion operations may reallocate storage and therefore invalidate references, pointers, and iterators.
• The type models an owning string, unlike basic_string_view, which is non-owning.

# Example

#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';
}

This is the common basic_string pattern: owning contiguous text storage, direct character access, and rich search/substring operations on top of dynamically managed capacity.

# Reference map

# Iterator invalidation

References, pointers, and iterators to string elements may be invalidated by any standard library operation that takes a non-const reference to the string, such as std::getline, std::swap, or stream extraction, and by calling non-const member functions except operator[], at, data, front, back, begin, rbegin, end, and rend.

# Notes

Although the standard required customized construct/destroy use for std::basic_string element lifetime management until C++23, implementations already used the default mechanism in practice. P1072R10 aligned the wording with that established behavior.

# Defect reports

# See also

• basic_string_view: non-owning contiguous string view
• char_traits: character operations policy used by basic_string